Tooltip 文字提示
悬停或键盘聚焦时,给一个控件补一句简短说明,最常见的是给图标按钮配上名字和快捷键。触屏上不显示,所以不要把必要信息只放在提示里;需要可点击的内容用 Popover。
基本用法
把被提示的元素作为 children 传入。首次出现有 380ms 延迟;一个提示刚收起后马上移到相邻的目标,新提示会立即出现并滑过去。
快捷键
用 shortcut 在文字后面显示快捷键;内容是字符串时也可以写成“文字|快捷键”。
位置与延迟
禁用的目标
原生 disabled 的按钮不触发指针和焦点事件,提示出不来。想解释“为什么不可用”,给按钮用 aria-disabled:它仍可聚焦,点击会被拦下。Tooltip 自己的 disabled 则是暂时不显示提示。
受控用法
规格
- 延迟
- 首次 380ms · 320ms 内再次悬停立即出现
- 进场
- 上移 6px + scale .86 → 1 · 弹簧
- 热切换
- left / top · spring-snappy
- 可停留
- 提示与目标之间无缝衔接 · 离开 160ms 后收起
- 可选中
- 文字可选中复制
API
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
content* | ReactNode | — | 提示文字。字符串可以写成“文字|快捷键”。 |
shortcut | ReactNode | — | 快捷键提示位。 |
children* | ReactElement | — | 被提示的元素:要能接收 ref 和事件。 |
placement | Placement | 'top' | 位置,放不下时自动翻面。 |
offset | number | 8 | 与目标的间距(px)。 |
delay | number | 380 | 首次出现前的等待(ms)。键盘聚焦不等待。 |
skipDelayWithin | number | 320 | 上一个提示收起后多久之内再次悬停可以跳过等待(ms)。 |
hideDelay | number | 160 | 指针离开后多久收起(ms),期间可以把指针移到提示上。 |
disabled | boolean | — | 不显示提示。 |
open / defaultOpen / onOpenChange | boolean / boolean / (open) => void | — | 受控与非受控的显示状态。 |
className | string | — | 提示气泡的类名。 |
无障碍
- 气泡是
role="tooltip",显示时通过aria-describedby关联到目标——它是“描述”,不是名称。图标按钮仍然要有自己的aria-label。 - 键盘聚焦目标时显示,失焦收起;Esc 立即收起(不影响外层浮层的焦点)。
- 指针可以移到提示上停留,文字可以选中复制(满足 WCAG 1.4.13:可悬停、可关闭、不自动消失)。
- 触屏上不显示:触屏没有悬停,长按留给系统菜单。必要的信息请直接写在界面上。
- 同一时间只显示一个提示。