工具提示
当用户悬停、聚焦或点击元素时,工具提示会显示信息性文本。
激活后,工具提示会显示一个文本标签,标识元素,例如对其功能的描述。
定位的工具提示
Tooltip
组件有 12 个 placement 选择。它们没有方向箭头;相反,它们依靠源头发出的运动来传达方向。
箭头工具提示
您可以使用 arrow
属性为工具提示添加一个箭头,指示它指的是哪个元素。
或者,您可以使用 slotProps
属性来自定义 popper 的 margin。
自定义子元素
工具提示需要将其 DOM 事件监听器应用于其子元素。如果子元素是自定义 React 元素,则需要确保它将其 props 传播到基础 DOM 元素。
const MyComponent = React.forwardRef(function MyComponent(props, ref) {
// Spread the props to the underlying DOM element.
return (
<div {...props} ref={ref}>
Bin
</div>
);
});
// ...
<Tooltip title="Delete">
<MyComponent />
</Tooltip>;
如果使用类组件作为子组件,您还需要确保 ref 被转发到基础 DOM 元素。(指向类组件本身的 ref 将不起作用。)
class MyComponent extends React.Component {
render() {
const { innerRef, ...props } = this.props;
// Spread the props to the underlying DOM element.
return (
<div {...props} ref={innerRef}>
Bin
</div>
);
}
}
// Wrap MyComponent to forward the ref as expected by Tooltip
const WrappedMyComponent = React.forwardRef(function WrappedMyComponent(props, ref) {
return <MyComponent {...props} innerRef={ref} />;
});
// ...
<Tooltip title="Delete">
<WrappedMyComponent />
</Tooltip>;
触发器
您可以定义导致工具提示显示的事件类型。
触摸操作需要长按,因为 enterTouchDelay
属性默认设置为 700
毫秒。
受控工具提示
您可以使用 open
、onOpen
和 onClose
属性来控制工具提示的行为。
可变宽度
默认情况下,Tooltip
组件会包裹长文本以使其可读。
交互式
工具提示默认是交互式的(以通过 WCAG 2.1 成功标准 1.4.13)。在 leaveDelay
过期之前,当用户悬停在工具提示上时,它不会关闭。您可以通过传递 disableInteractive
来禁用此行为(从而未能达到 AA 级别的成功标准)。
禁用元素
默认情况下,像 <button>
这样的禁用元素不会触发用户交互,因此 Tooltip
组件不会在像悬停这样的正常事件上激活。为了适应禁用元素,请添加一个简单的包装元素,例如 span
。
<Tooltip title="You don't have permission to do this">
<span>
<button disabled={disabled} style={disabled ? { pointerEvents: 'none' } : {}}>
A disabled button
</button>
</span>
</Tooltip>
过渡
使用不同的过渡效果。
跟随光标
您可以通过设置 followCursor={true}
来启用工具提示跟随光标。
虚拟元素
如果您需要实现自定义放置,可以使用 anchorEl
属性:anchorEl
属性的值可以是伪造 DOM 元素的引用。您需要创建一个类似于 VirtualElement
的对象。
显示和隐藏
通常,当用户的鼠标悬停在元素上时,工具提示会立即显示,并在用户的鼠标离开时立即隐藏。可以通过 enterDelay
和 leaveDelay
属性添加显示或隐藏工具提示的延迟。
在移动设备上,当用户长按元素时,工具提示会显示,并在 1500 毫秒的延迟后隐藏。您可以使用 disableTouchListener
属性禁用此功能。
可访问性
(WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/)
默认情况下,工具提示仅标记其子元素。这与 title
显着不同,后者可以标记或描述其子元素,具体取决于子元素是否已经有标签。例如,在
<button title="some more information">A button</button>
title
充当可访问的描述。如果您希望工具提示充当可访问的描述,您可以传递 describeChild
。请注意,如果工具提示提供了唯一的视觉标签,则不应使用 describeChild
。否则,子元素将没有可访问的名称,并且工具提示将违反 WCAG 2.1 中的成功标准 2.5.3。