工具提示

工具提示是一个弹出窗口，其中包含有关另一个控件或对象的其他信息。 当用户将焦点移动到、长按或将指针悬停在关联的控件上时，工具提示会自动显示。 当用户将焦点移开、停止按或停止将指针悬停在关联控件 (上时，工具提示将消失，除非指针) 向工具提示移动。

注意

从 Windows 11 版本 21H2 开始，也可以按 Ctrl 键关闭工具提示。

这是正确的控件吗？

要求用户执行操作之前，使用工具提示显示有关控件的详细信息。 工具提示应尽量少用，仅应在用户为尝试完成某个任务而需要添加不同的值时才使用。 一个经验规则是，如果信息在同一体验的其他位置提供，则不需要工具提示。 一个有价值的工具提示可以澄清不明确的操作。

应在何时使用工具提示？ 在决定之前，请考虑以下问题：

• 信息是否应当基于指针悬停显示？ 如果不是，请使用其他控件。 仅在与用户交互时显示提示，工具提示从来不会自行显示。

• 控件是否有文本标签？ 如果没有，请使用工具提示提供标签。 比较好的 UX 设计做法是以内联方式为大多数控件添加标签，对于这些控件，你不需要使用工具提示。 仅显示图标的工具栏控件和命令按钮需要工具提示。

• 对象是否受益于相关说明或更详细的信息？ 如果是，请使用工具提示。 但是，文本必须是补充性的文本，也就是说不是主要任务必需的文本。 如果是必需的文本，请将它直接放在 UI 中，这样用户便不必查找或搜寻它。

• 补充信息是否为错误、警告或状态？ 如果是，请使用其他 UI 元素（如弹出窗口）。

• 用户是否需要与提示进行交互？ 如果是，请使用其他控件。 用户不能与提示进行交互，因为移动鼠标会导致提示消失。

• 用户是否需要打印补充信息？ 如果是，请使用其他控件。

• 用户是否会觉得提示令人厌烦或者让人分心？ 如果是，请考虑使用其他解决方案（包括不执行任何操作）。 如果你的确使用了可能会让人分心的提示，请允许用户关闭它们。

建议

• 慎用工具提示（或者完全不使用）。 工具提示可使用户中断。 工具提示的干扰性类似于弹出窗口，因此不要使用它们，除非它们可以显著增加价值。
• 使工具提示文本保持简单。 工具提示最适用简短语句和语句片段。 较大的文本块可能会让人不知所措，并且工具提示可能会在用户阅读完之前就超时了。
• 创建有帮助的补充性工具提示文本。 工具提示文本的内容必须丰富。 不要使工具提示过于明显，也不要只是复制屏幕上已有的内容。 由于工具提示文本不总是可见，因此它应当是用户不必阅读的补充信息。 使用明白易懂的控件标签或就地的补充文本来表示重要信息。
• 适当时使用图像。 有时最好在工具提示中使用图像。 例如，当用户将鼠标指针悬停在超链接上时，你可以使用工具提示显示链接页面的预览。
• 默认情况下，键盘快捷方式显示在工具提示中。 如果添加自己的工具提示，请确保它包含有关可用键盘快捷方式的信息。
• 不要使用工具提示来显示 UI 中已有的文本。 例如，不要在按钮上放置显示内容与按钮文本相同的工具提示。
• 不要在工具提示内部放置交互式控件。
• 不要将看上去像交互式控件的图像放在工具提示内部。

UWP 和 WinUI 2

重要

本文中的信息和示例针对使用 Windows 应用 SDK 和 WinUI 3 的应用进行优化，但通常适用于使用 WinUI 2 的 UWP 应用。 有关特定于平台的信息和示例，请参阅 UWP API 参考。

本部分包含你在 UWP 或 WinUI 2 应用中使用该控件所需的信息。

此控件的 API 存在于 Windows.UI.Xaml.Controls 命名空间中。

• UWP API：ToolTip 类、 ToolTipService 类
• 打开 WinUI 2 库应用，查看运行中的工具提示。 WinUI 2 库应用包括大多数 WinUI 2 控件、特性和功能的交互式示例。 通过 Microsoft Store 获取应用，或在 GitHub 上获取源代码。

建议使用最新的 WinUI 2 来获取所有控件的最新样式和模板。 WinUI 2.2 或更高版本包含此控件的新模板，该模板使用圆角。 有关详细信息，请参阅圆角半径。

创建工具提示

• 重要 API：ToolTip 类、 ToolTipService 类

打开 WinUI 3 库应用，查看运行中的工具提示。

WinUI 3 库应用包括大多数 WinUI 3 控件、特性和功能的交互式示例。 通过 Microsoft Store 获取应用，或在 GitHub 上获取源代码

工具提示必须分配到其所有者的其他 UI 元素。 ToolTipService 类提供用于显示工具提示的静态方法。

在 XAML 中，可使用 ToolTipService.Tooltip 附加属性将工具提示分配给所有者。

<Button Content="New" ToolTipService.ToolTip="Create a new document"/>

在代码中，可使用 ToolTipService.SetToolTip 方法将工具提示分配给所有者。

<Button x:Name="submitButton" Content="New"/>

ToolTip toolTip = new ToolTip();
toolTip.Content = "Create a new document";
ToolTipService.SetToolTip(submitButton, toolTip);

内容

可以使用任何对象作为工具提示的内容。 下面是一个在工具提示中使用图像的示例。

<TextBlock Text="store logo">
    <ToolTipService.ToolTip>
        <Image Source="Assets/StoreLogo.png"/>
    </ToolTipService.ToolTip>
</TextBlock>

放置

默认情况下，工具提示在指针上方居中显示。 工具提示的放置位置不受应用窗口的约束，因此工具提示可能部分或完全显示在应用窗口边界的外部。

若要进行广泛的调整，请使用 Placement 属性或 ToolTipService.Placement 附加属性指定是将工具提示放置在指针的上方、下方、左方还是右方。 可以通过设置 VerticalOffset 或 HorizontalOffset 属性更改指针与工具提示之间的距离。 只有两个偏移值中的一个会影响最终位置 - 当 Placement 为 Top 或 Bottom 时，VerticalOffset 会影响该位置；当 Placement 为 Left 或 Right 时，HorizontalOffset 会影响该位置。

<!-- An Image with an offset ToolTip. -->
<Image Source="Assets/StoreLogo.png">
    <ToolTipService.ToolTip>
        <ToolTip Content="Offset ToolTip."
                 Placement="Right"
                 HorizontalOffset="20"/>
    </ToolTipService.ToolTip>
</Image>

如果工具提示遮盖了它所引用的内容，则可以使用 PlacementRect 属性精确调整其位置。 PlacementRect 锚定工具提示的位置，且工具提示不得遮蔽该区域，前提是有足够的屏幕空间，因此可以在该区域之外放置工具提示。 可以指定矩形的原点（相对于工具提示的所有者），以及排除区域的高和宽。 可以通过 Placement 属性来定义是将工具提示放置在指针的上方、下方、左方还是右方。

<!-- An Image with a non-occluding ToolTip. -->
<Image Source="Assets/StoreLogo.png" Height="64" Width="96">
    <ToolTipService.ToolTip>
        <ToolTip Content="Non-occluding ToolTip."
                 PlacementRect="0,0,96,64"/>
    </ToolTipService.ToolTip>
</Image>

获取示例代码

• WinUI 库示例 - 以交互式格式查看所有 XAML 控件。

相关文章

• ToolTip 类