# Tooltip 使用文档本文档介绍 AtomUI ToolTip 控件的各种使用方式，示例代码摘自 Gallery 演示程序。 > 📖 Gallery 源码位置：`controlgallery/AtomUIGallery/ShowCases/Views/DataDisplay/TooltipShowCase.axaml` --- ## 前置准备在 AXAML 中使用 ToolTip，需要引入以下命名空间： ```xml xmlns:atom="https://atomui.net" ``` 在 C# 代码中引入： ```csharp using AtomUI.Desktop.Controls; // ToolTip 控件 ``` --- ## 1. 基本用法鼠标悬浮时显示简单文字提示。ToolTip 通过附加属性附加到任意控件上，无需嵌套或修改控件模板： ```xml Tooltip will show on mouse enter. ``` 也可以附加到按钮等其他控件上： ```xml Hover me ``` > **提示**：当 `Tip` 为字符串时，ToolTip 内部自动将其转换为带自动换行的 `TextBlock`（`TextWrapping="Wrap"`），超过 `ToolTipMaxWidth`（默认 250px）时自动换行。 --- ## 2. 弹出方向通过 `Placement` 附加属性设置 12 种弹出方向。不设置时默认为 `Top`。 ```xml Top Bottom Left Right TopLeft TopRight ``` ### 完整的 12 方向布局 Gallery 中展示了 12 种方向的完整布局，使用 Grid 排列： ```xml ``` > 📖 参考：`controlgallery/AtomUIGallery/ShowCases/Views/DataDisplay/TooltipShowCase.axaml` 中 "Placement" 示例。 --- ## 3. 箭头控制 ToolTip 支持三种箭头模式：显示、隐藏和居中指向。 ### 显示箭头（默认） ```xml Arrow ``` ### 隐藏箭头 ```xml No Arrow ``` ### 箭头指向目标中心 ```xml Point at Center ``` ### 通过 Segmented 切换箭头模式（Gallery 示例） Gallery 中提供了通过 `Segmented` 控件动态切换箭头模式的示例： ```xml Show Hide Center Top ``` ```csharp // ViewModel 处理 Segmented 选中变更 public void HandleSelectionChanged(object? sender, SelectionChangedEventArgs args) { if (sender is Segmented segmented) { if (segmented.SelectedIndex == 0) { ShowArrow = true; IsPointAtCenter = false; } else if (segmented.SelectedIndex == 1) { ShowArrow = false; IsPointAtCenter = false; } else if (segmented.SelectedIndex == 2) { IsPointAtCenter = true; ShowArrow = true; } } } ``` > 📖 参考：`controlgallery/AtomUIGallery/ShowCases/Views/DataDisplay/TooltipShowCase.axaml` 中 "Arrow" 示例。 --- ## 4. 预设颜色使用 Ant Design 调色板提供的 14 种标准颜色： ```xml prompt text Top prompt text Top prompt text Top prompt text Top prompt text Top prompt text Top prompt text Top prompt text Top prompt text Top prompt text Top prompt text Top prompt text Top prompt text Top prompt text Top ``` > 📖 参考：`controlgallery/AtomUIGallery/ShowCases/Views/DataDisplay/TooltipShowCase.axaml` 中 "Colorful Tooltip" → "Presets" 示例。 --- ## 5. 自定义颜色使用任意颜色值作为 ToolTip 背景色： ```xml prompt text Top prompt text Top prompt text Top prompt text Top ``` > 📖 参考：`controlgallery/AtomUIGallery/ShowCases/Views/DataDisplay/TooltipShowCase.axaml` 中 "Colorful Tooltip" → "Custom" 示例。 --- ## 6. 延迟显示通过 `ShowDelay` 控制鼠标悬浮后多久显示 ToolTip： ```xml Instant Default (400ms) Delayed ``` ### 快速切换（BetweenShowDelay）当用户在多个带 ToolTip 的控件之间快速移动鼠标时，`BetweenShowDelay` 控制是否跳过 `ShowDelay` 直接显示： ```xml A B C ``` --- ## 7. 程序化控制通过 `IsOpen` 附加属性控制 ToolTip 的显示/隐藏，需同时设置 `IsCustomShowAndHide="True"`： ```xml Controlled ``` ```csharp // ViewModel public class MyViewModel : ReactiveObject { private bool _isTooltipOpen; public bool IsTooltipOpen { get => _isTooltipOpen; set => this.RaiseAndSetIfChanged(ref _isTooltipOpen, value); } // 通过按钮或其他操作控制 public void ToggleTooltip() { IsTooltipOpen = !IsTooltipOpen; } } ``` > ⚠️ 必须设置 `IsCustomShowAndHide="True"`，否则 `ToolTipService` 的自动管理会覆盖 `IsOpen` 绑定。 --- ## 8. 在禁用控件上显示默认情况下，禁用的控件不显示 ToolTip。设置 `ShowOnDisabled="True"` 可改变此行为： ```xml Disabled ``` --- ## 9. 拦截 ToolTip 打开事件可以在 ToolTip 打开前拦截并取消： ```csharp // 在 Code-behind 中 ToolTip.AddToolTipOpeningHandler(myButton, (sender, args) => { // 根据条件决定是否允许打开 if (ShouldPreventTooltip()) { args.Cancel = true; } }); ``` --- ## 常见组合模式 ### 图标按钮提示为仅图标的按钮提供功能说明： ```xml ``` ### 工具栏按钮提示为工具栏中的每个按钮添加功能提示： ```xml ``` ### 截断文本提示完整内容当文本被截断时，使用 ToolTip 显示完整内容： ```xml ``` ### 表单字段说明为表单输入框提供辅助说明： ```xml ``` ### 导航菜单项提示折叠状态的侧边栏菜单项： ```xml ```