Tooltip

Tooltip 用于在鼠标悬停或元素获得焦点时显示补充信息。它支持纯文本、自定义内容、快捷键信息以及多种触发方式，适合做解释说明、状态提示和操作说明。

#移动端行为

iOS 和 Android 上会禁用由 GPUI Base overlay 管理的 tooltip。共享组件可以保留 tooltip 配置，但移动端操作仍应提供可见或可访问的标签。直接使用 GPUI .tooltip() 的调用（包括下方的基础 div() 示例）不经过此 overlay，因此不受该策略限制。集成方式请参阅移动端。

#导入

use gpui_kit::component::tooltip::Tooltip;

#用法

div()
    .child("Hover me")
    .id("basic-tooltip")
    .tooltip(|window, cx| {
        Tooltip::new("This is a helpful tooltip").build(window, cx)
    })

Button::new("save-btn")
    .label("Save")
    .tooltip("Save the current document")

#携带快捷键信息

actions!(my_actions, [SaveDocument]);

Button::new("save-btn")
    .label("Save")
    .tooltip_with_action(
        "Save the current document",
        &SaveDocument,
        Some("MyContext")
    )

div()
    .child("Hover for rich content")
    .id("rich-tooltip")
    .tooltip(|window, cx| {
        Tooltip::element(|_, cx| {
            h_flex()
                .gap_x_1()
                .child(IconName::Info)
                .child(
                    div()
                        .child("Muted Text")
                        .text_color(cx.theme().muted_foreground)
                )
                .child(
                    div()
                        .child("Danger Text")
                        .text_color(cx.theme().danger)
                )
                .child(IconName::ArrowUp)
        })
        .build(window, cx)
    })

#手动指定快捷键

div()
    .child("Custom keybinding")
    .id("custom-kb")
    .tooltip(|window, cx| {
        Tooltip::new("Delete item")
            .key_binding(Some(Kbd::new("Delete")))
            .build(window, cx)
    })

#显示时机

组件自带的 Tooltip（例如通过 Button::tooltip 设置的）在指针停留于触发元素 500 ms 后出现。指针离开后，Tooltip 会再保留 300 ms 宽限期；在宽限期内移入另一个触发元素，会立即切换到它的 Tooltip，不再重新等待。

如需在整个应用中调整这两个时长，安装一次 TooltipDefaults 即可。已打开的窗口会在下一次悬停时使用新值。

use std::time::Duration;
use gpui_kit::component::tooltip::TooltipDefaults;

gpui_kit::init(cx);
TooltipDefaults::new()
    .with_show_delay(Duration::from_millis(300))
    .with_grace_period(Duration::from_millis(200))
    .install(cx);

单个触发元素可以用 tooltip_show_delay 覆盖显示延迟。延迟为零时，指针一移入就显示：

Button::new("help")
    .icon(IconName::Info)
    .tooltip("帮助")
    .tooltip_show_delay(Duration::ZERO)

宽限期由窗口内所有触发元素共享，不能按单个元素覆盖。直接调用 GPUI .tooltip() 的元素不受这些设置影响，请改用 GPUI 的 .tooltip_show_delay()。

#API 参考

方法	说明
`new(text)`	创建文本型 Tooltip
`element(builder)`	创建自定义内容 Tooltip
`action(action, context)`	关联 action，显示对应快捷键信息
`key_binding(kbd)`	手动设置快捷键展示
`build(window, cx)`	构建并返回 Tooltip 视图

很多组件内置了 Tooltip 支持，常见形式包括：

方法	说明
`tooltip(text)`	添加简单文本提示
`tooltip_with_action(text, action, context)`	添加带快捷键的提示
`tooltip_show_delay(duration)`	覆盖该触发元素的显示延迟，见显示时机
`tooltip(closure)`	使用构建器生成自定义提示

#样式

Tooltip 默认会自动应用与主题匹配的样式：

背景：theme.popover
文字：theme.popover_foreground
边框：theme.border
阴影：中等投影
圆角：约 6px

也可以继续通过 Styled trait 自定义：

Tooltip::new("Custom styled tooltip")
    .bg(cx.theme().accent)
    .text_color(cx.theme().accent_foreground)
    .build(window, cx)

#示例

#工具栏提示

h_flex()
    .gap_1()
    .child(
        Button::new("new")
            .icon(IconName::Plus)
            .tooltip_with_action("Create new file", &NewFile, Some("Editor"))
    )
    .child(
        Button::new("save")
            .icon(IconName::Save)
            .tooltip_with_action("Save file", &SaveFile, Some("Editor"))
    )

#表单说明

v_flex()
    .gap_4()
    .child(
        Input::new("email")
            .placeholder("Enter your email")
            .tooltip("We'll never share your email address")
    )
    .child(
        Input::new("password")
            .input_type(InputType::Password)
            .placeholder("Password")
            .tooltip("Must be at least 8 characters with special characters")
    )

#最佳实践

提示文案应简短直接，不重复界面上已经明显存在的信息。
Tooltip 适合做补充说明，不应用来承载关键流程信息。
图标按钮、缩写和危险操作尤其适合配套 Tooltip。
需要高频触发的 Tooltip 应尽量避免复杂内容，以减少渲染开销。

#移动端行为

#导入

#用法

#纯文本 Tooltip

#按钮 Tooltip