一个 React 提示，采用 Liquid Glass 浮层，支持可配置延迟、定位与可选箭头。
Tooltip 内部负责触发器、Portal、定位器、玻璃浮层、方向箭头和内容。它面向鼠标与键盘用户，是补充性的视觉提示，不能替代可见标签或无障碍描述。
触发器本身的可访问名称应与提示内容一致。纯图标触发器需要 aria-label，Tooltip 只提供额外提示。
通过 trigger 传入一个元素，它必须像 Button 一样转发 props 与 ref。
side、align、sideOffset 与 alignOffset 控制首选位置。空间不足时，提示会自动翻转或偏移。
使用 open 与 onOpenChange 控制显示状态；设置 arrow={false} 可隐藏箭头。
The tooltip is closed.
delay 控制鼠标停留多久后打开，closeDelay 控制关闭延迟，两者都会传给 Base UI 触发器。新手引导需要即时反馈时可设 delay={0}；提示出现频繁时则使用更长的延迟。
Tooltip 常与图标按钮搭配使用。请为触发器提供独立的 aria-label；提示文字不能替代按钮的可访问名称。
Tooltip 在触发器被悬停或获得键盘焦点时打开，在失焦、按 Escape 或点击外部时关闭。浮层仅作视觉提示：它不会被暴露为描述，触屏与屏幕阅读器用户也无法使用 Tooltip。触发器必须通过可见文字、aria-label 或 aria-labelledby 自己提供完整的可访问名称。
提示内容应简短且仅作补充。不要在 Tooltip 中放置交互控件或独有信息，因为部分用户可能永远不会打开它。标签与焦点规范见可访问性指南。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
trigger | ReactElement | — | 打开提示的触发器。必填，必须转发 props 与 ref。 |
children | ReactNode | — | 浮层中的简短提示。必填。 |
arrow | boolean | true | 是否渲染方向箭头。 |
delay | number | 600 | 悬停后打开前的延迟，单位毫秒。 |
closeDelay | number | 0 | 关闭前的延迟，单位毫秒。 |
side | "top" | "bottom" | "left" | "right" | "inline-start" | "inline-end" | "top" | 首选方位。 |
align | "start" | "center" | "end" | "center" | 相对触发器的对齐方式。 |
sideOffset | number | OffsetFunction | 8 | 触发器与浮层的像素距离。 |
alignOffset | number | OffsetFunction | 0 | 沿对齐轴的像素偏移。 |
collisionPadding | Padding | 每边 5px | 浮层与碰撞边界之间的留白。 |
open | boolean | — | 受控显示状态。 |
defaultOpen | boolean | false | 非受控时的初始显示状态。 |
onOpenChange | (open: boolean, details) => void | — | 打开或关闭时调用。 |
onOpenChangeComplete | (open: boolean) => void | — | 打开或关闭动画结束后调用。 |
disabled | boolean | false | 禁止打开提示。 |
trackCursorAxis | "none" | "x" | "y" | "both" | "none" | 提示跟随指针移动的轴。 |
disableHoverablePopup | boolean | false | 是否允许悬停在提示内容上而不关闭提示。 |
actionsRef | RefObject<Tooltip.Root.Actions | null> | — | 命令式的 close 与 unmount 操作。 |
triggerId | string | null | — | 受控提示所用触发器的 ID。 |
defaultTriggerId | string | null | — | 初始打开提示所用触发器的 ID。 |
handle | Tooltip.Handle<Payload> | — | 允许外部触发器控制提示的 handle。 |
className | string | — | 合并到浮层的 Tailwind 类名。 |
style | CSSProperties | — | 内联样式，合并到与 className 相同的元素。 |
ui | { positioner?: ClassValue; popup?: ClassValue; glass?: ClassValue; overlay?: ClassValue; arrow?: ClassValue; content?: ClassValue } | — | 按 data-slot 组织的内部槽位类名。 |
ui 的键对应下方列出的 data-slot 值。其余 Base UI Tooltip.Root 属性都会透传。
| 属性 | 说明 |
|---|---|
data-open | 浮层打开时存在。 |
data-closed | 浮层关闭时存在。 |
data-side | 实际方位（top、bottom、left、right、inline-start 或 inline-end）。 |
data-align | 实际对齐方式（start、center 或 end）。 |
data-starting-style | 浮层开始进入动画时存在。 |
data-ending-style | 浮层正在退出动画时存在。 |
data-instant | 需要跳过动画时存在。 |
data-popup-open | 提示打开时存在于触发器上。 |
data-slot | 标记内部结构（positioner、popup、glass、overlay、arrow、content）。 |
组件使用共享玻璃材质。可以在父级调整 --ui-glass-* token，用 className 控制布局，并通过 ui 按 data-slot 调整内部槽位。组件级数值位于 src/theme/tooltip.ts。Token 分层与预设见主题指南。