展示类 · Tooltip
工具提示
工具提示用于对一个元素进行标识或者附上少量辅助信息,最典型的场景是向用户解释图标的含义、展示被截断的文本、显示图片的描述等。

代码演示

如何引入

注意事项

Tooltip 需要将 DOM 事件监听器应用到 children 中,如果子元素是自定义的组件,你需要确保它能将属性传递至底层的 DOM 元素
同时为了计算弹出层的定位,需要获取到 children 的真实 DOM 元素,因此 Tooltip 支持如下类型的 children
  1. Class Component,不强制绑定ref,但需要确保 props 可被透传至真实的 DOM 节点上
  2. 使用 forwardRef 包裹后的函数式组件,将 props 与 ref 透传到 children 内真实的 DOM 节点上
  3. 真实 DOM 节点, 如 span,div,p...

位置

可以通过 position 配置弹出层方向以及对齐位置,position 详细可选值请参考下方 API 文档
配置为 top 时 向上弹出
配置为 topLeft 时,向上弹出,且弹出层与 children 左对齐(当arrowPointAtCenter=false时)
配置为 topRight 时,向上弹出,且弹出层与 children 右对齐(当arrowPointAtCenter=false时)
其他方向同理

指向元素中心

默认情况下 arrowPointAtCenter=true,小三角始终指向 children 元素中心位置。 你可以将其设置为 false,此时小三角将不再保持指向元素中心。弹出层与 children 边缘对齐

触发时机

  • 配置触发展示的时机,默认为 hover,可选 hover/focus/click/custom/ 'contextMenu'
  • 设为 custom 时,需要配合 visible 属性使用,此时显示与否完全受控
  • contextMenu 右键触发在 v 2.42.0 后开始提供

覆盖特定样式

你可以通过 className、style 为弹出层配置特定样式,例如覆盖默认的 maxWidth (280px)

渲染至指定 DOM

传入 getPopupContainer,弹层将会渲染至该函数返回的 DOM 中。 这会改变浮层 DOM 树位置,但不会改变视图渲染位置。
需要注意的是: 返回的容器如果不是 document.bodyposition 需要设为 "relative"(版本 >= 0.18.0)。

搭配 Popover 或 Popconfirm 使用

Tooltip、Popconfirm、Popover 都需要劫持 children 的相关事件(onMouseEnter/onMouseLeave/onClick....),用于配置 trigger。
如果直接嵌套使用的话,会使外层 trigger 失效。
需要在中间加一层元素(div 或 span)以防止 trigger 的事件劫持失效。

仅当内容宽度超出时展示 Tooltip

Semi 为这种场景提供了 Typography 组件,可以更简单快捷地满足需求。不需要自己再对 Tooltip 的出现做条件判断,详细的使用请参考Typography 组件文档

API 参考


属性说明类型默认值版本
autoAdjustOverflow弹出层被遮挡时是否自动调整方向booleantrue
arrowPointAtCenter“小三角”是否指向元素中心,需要同时传入"showArrow=true"booleantrue
content弹出层内容string|ReactNode
className弹出层的样式名string
clickToHide点击弹出层及内部任一元素时是否自动关闭弹层booleanfalse
disableFocusListenertrigger为hover时,不响应键盘聚焦弹出浮层事件,详见issue#977booleanfalse2.17.0
getPopupContainer指定父级 DOM,弹层将会渲染至该 DOM 中,自定义需要设置 position: relative 这会改变浮层 DOM 树位置,但不会改变视图渲染位置。function():HTMLElement() => document.body
keepDOM关闭时是否保留内部组件不销毁booleanfalse2.31.0
margin计算溢出时的增加的冗余值,详见issue#549number |
MarginObject
02.23.0
mouseEnterDelay鼠标移入后,延迟显示的时间,单位毫秒(仅当 trigger 为 hover/focus 时生效)number50
mouseLeaveDelay鼠标移出后,延迟消失的时间,单位毫秒(仅当 trigger 为 hove/focus 时生效),不小于 mouseEnterDelaynumber50
motion是否展示弹出层动画booleantrue
position弹出层展示位置,可选值:top, topLeft, topRight, left, leftTop, leftBottom, right, rightTop, rightBottom, bottom, bottomLeft, bottomRightstring'top'
prefixCls弹出层 wrapper div 的 className 前缀,设置该项时,弹出层将不再带 Tooltip 的样式string'semi-tooltip'
preventScroll指示浏览器是否应滚动文档以显示新聚焦的元素,作用于组件内的 focus 方法boolean
rePosKey可以更新该项值手动触发弹出层的重新定位string|number
style弹出层的内联样式object
spacing弹出层与 children 元素的距离,单位 px(object类型自 v2.45后支持)number |
SpacingObject
8
showArrow是否显示箭头三角形booleantrue
stopPropagation是否阻止弹层上的点击事件冒泡booleanfalse0.34.0
transformFromCenter是否从包裹的元素水平或垂直中心处变换,该参数仅影响动效变换的 transform-origin,一般无需改动booleantrue
trigger触发展示的时机,可选值:hover / focus / click / custom / contextMenu (v2.42后提供)string'hover'
visible是否展示弹出层boolean
wrapperClassName当 children 为 disabled ,或者 children 为多个元素时,外层将会包裹一层 span 元素,该 api 用于设置此 span 的样式类名string
wrapperId弹出层 wrapper 节点的 id,trigger 的 aria 属性指向此 id,若不设置组件会随机生成一个 idstring2.11.0
zIndex弹层层级number1060
onVisibleChange弹出层展示/隐藏时触发的回调function(isVisible:boolean)
onClickOutSide当弹出层处于展示状态,点击非Children、非浮层内部区域时的回调(仅trigger为custom、click时有效)function(e:event)2.1.0

Accessibility

ARIA

  • Tooltip 具有 tooltip role,遵循 WAI-ARIA 规范中对于 Tooltip 的定义
  • Tooltip 的 content 与 children
    • 关于 content
      • content 的 wrapper 会被自动添加 id 属性,用于与 children 的 aria-describedby 匹配,关联 content 与 children
    • 关于 children
      • Tooltip 的内容(content)与其触发器(children)之间应当具有显式联系。Tooltip 会自动为 children 元素添加 aria-describedby 属性,值为 content wraper的 id
      • 若你 Tooltip的children 是Icon,不包含可见文本,我们推荐你在 children 上添加 aria-label 属性进行相应描述

文案规范

  • 只展示信息说明和引导,不展示报错信息
  • 不在 tooltip 里只能是额外的链接和按钮
  • 尽量精简至一句话进行说明,不展示标点符号

设计变量

FAQ

  • 为什么 Tooltip content 配置很长很长的内容时,某些情况下内容会超出显示区域?
    在 v2.36.0 版本以前,考虑到不同语言内容(纯英文、中文、中英文混合、其他语种混合)对换行的需求不太一致,所以组件层没有做这个预设。在接收到较多使用反馈后,自 v2.36.0 版本,Tooltip 内部通过设置 word-wrap 为 break-word 处理文本换行。对于任意版本,如果默认设置不符合预期,使用方都可以通过 style/className API 设置换行相关 CSS 属性进行调整。