工具提示

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

注意

从 Windows 11 版本 21H2 开始，还可以通过按 Ctrl 键消除工具提示。

这是正确的控件吗？

在要求用户执行操作之前，使用工具提示显示有关控件的详细信息。 应谨慎使用工具提示，并且仅当工具提示为尝试完成任务的用户添加非重复值时。 经验法则之一是，如果信息在同一体验中的其他位置可用，则不需要工具提示。 有价值的工具提示将澄清一个不清楚的操作。

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

• 信息是否应当基于指针悬停显示？ 如果没有，请使用另一个控件。 仅显示提示作为用户交互的结果，从不自行显示它们。

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

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

• 补充信息是否为错误、警告或状态？ 如果是，请使用另一个 UI 元素，例如浮出控件。

• 用户是否需要与提示进行交互？ 如果是，请使用另一个控件。 用户无法与提示交互，因为移动鼠标会使提示消失。

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

• 用户是否会觉得提示令人厌烦或者让人分心？ 如果是这样，请考虑使用另一个解决方案，包括根本不执行任何操作。 如果你确实使用提示来分散注意力，则允许用户将其关闭。

建议

• 请谨慎使用工具提示（或者根本不使用）。 工具提示是中断。 工具提示可以像弹出窗口一样分散注意力，因此不要使用它们，除非它们增加了重要的价值。
• 使工具提示文本保持简洁。 工具提示非常适合短句子和句子片段。 大型文本块可能非常困难，工具提示可能会在用户完成阅读之前超时。
• 创建有用的补充工具提示文本。 工具提示文本必须具有信息性。 不要使它变得明显或只是重复屏幕上已有的内容。 由于工具提示文本并不总是可见，因此用户不必阅读它应该是补充信息。 使用自解释性控件标签或就地补充文本传达重要信息。
• 适当时使用图像。 有时最好在工具提示中使用图像。 例如，当用户将鼠标悬停在超链接上时，可以使用工具提示显示链接页面的预览。
• 默认情况下，键盘快捷方式显示在工具提示中。 如果添加自己的工具提示，请确保它包含有关可用键盘快捷方式的信息。
• 不要使用工具提示显示 UI 中已可见的文本。 例如，不要在显示按钮的相同文本的按钮上放置工具提示。
• 不要在工具提示中放置交互式控件。
• 不要在工具提示中放置看起来类似于交互的图像。

UWP 和 WinUI 2

重要

本文中的信息和示例是针对使用 Windows App 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 类