跳到主要内容

Tooltip 文字提示

悬停或键盘聚焦时,给一个控件补一句简短说明,最常见的是给图标按钮配上名字和快捷键。触屏上不显示,所以不要把必要信息只放在提示里;需要可点击的内容用 Popover。

基本用法

把被提示的元素作为 children 传入。首次出现有 380ms 延迟;一个提示刚收起后马上移到相邻的目标,新提示会立即出现并滑过去。

快捷键

用 shortcut 在文字后面显示快捷键;内容是字符串时也可以写成“文字|快捷键”。

位置与延迟

禁用的目标

原生 disabled 的按钮不触发指针和焦点事件,提示出不来。想解释“为什么不可用”,给按钮用 aria-disabled:它仍可聚焦,点击会被拦下。Tooltip 自己的 disabled 则是暂时不显示提示。

受控用法

规格

延迟
首次 380ms · 320ms 内再次悬停立即出现
进场
上移 6px + scale .86 → 1 · 弹簧
热切换
left / top · spring-snappy
可停留
提示与目标之间无缝衔接 · 离开 160ms 后收起
可选中
文字可选中复制

API

属性

属性类型默认值说明
content*ReactNode—提示文字。字符串可以写成“文字|快捷键”。
shortcutReactNode—快捷键提示位。
children*ReactElement—被提示的元素:要能接收 ref 和事件。
placementPlacement'top'位置,放不下时自动翻面。
offsetnumber8与目标的间距(px)。
delaynumber380首次出现前的等待(ms)。键盘聚焦不等待。
skipDelayWithinnumber320上一个提示收起后多久之内再次悬停可以跳过等待(ms)。
hideDelaynumber160指针离开后多久收起(ms),期间可以把指针移到提示上。
disabledboolean—不显示提示。
open / defaultOpen / onOpenChangeboolean / boolean / (open) => void—受控与非受控的显示状态。
classNamestring—提示气泡的类名。

无障碍

  • 气泡是 role="tooltip",显示时通过 aria-describedby 关联到目标——它是“描述”,不是名称。图标按钮仍然要有自己的 aria-label。
  • 键盘聚焦目标时显示,失焦收起;Esc 立即收起(不影响外层浮层的焦点)。
  • 指针可以移到提示上停留,文字可以选中复制(满足 WCAG 1.4.13:可悬停、可关闭、不自动消失)。
  • 触屏上不显示:触屏没有悬停,长按留给系统菜单。必要的信息请直接写在界面上。
  • 同一时间只显示一个提示。