跳到内容
+

工具提示

当用户悬停、聚焦或点击元素时,工具提示会显示信息性文本。

激活后,工具提示会显示一个文本标签,标识元素,例如对其功能的描述。

Enter 开始编辑

定位的工具提示

Tooltip 组件有 12 个 placement 选择。它们没有方向箭头;相反,它们依靠源头发出的运动来传达方向。



自定义

以下是一些自定义组件的示例。您可以在覆盖文档页面中了解更多信息。

箭头工具提示

您可以使用 arrow 属性为工具提示添加一个箭头,指示它指的是哪个元素。

Enter 开始编辑

与锚点的距离

要调整工具提示与其锚点之间的距离,您可以使用 slotProps 属性来修改 popper 的 offset

或者,您可以使用 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 毫秒。

受控工具提示

您可以使用 openonOpenonClose 属性来控制工具提示的行为。

Enter 开始编辑

可变宽度

默认情况下,Tooltip 组件会包裹长文本以使其可读。

Enter 开始编辑

交互式

工具提示默认是交互式的(以通过 WCAG 2.1 成功标准 1.4.13)。在 leaveDelay 过期之前,当用户悬停在工具提示上时,它不会关闭。您可以通过传递 disableInteractive 来禁用此行为(从而未能达到 AA 级别的成功标准)。

Enter 开始编辑

禁用元素

默认情况下,像 <button> 这样的禁用元素不会触发用户交互,因此 Tooltip 组件不会在像悬停这样的正常事件上激活。为了适应禁用元素,请添加一个简单的包装元素,例如 span

Enter 开始编辑
<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} 来启用工具提示跟随光标。

禁用操作
Enter 开始编辑

虚拟元素

如果您需要实现自定义放置,可以使用 anchorEl 属性:anchorEl 属性的值可以是伪造 DOM 元素的引用。您需要创建一个类似于 VirtualElement 的对象。

悬停

显示和隐藏

通常,当用户的鼠标悬停在元素上时,工具提示会立即显示,并在用户的鼠标离开时立即隐藏。可以通过 enterDelayleaveDelay 属性添加显示或隐藏工具提示的延迟。

在移动设备上,当用户长按元素时,工具提示会显示,并在 1500 毫秒的延迟后隐藏。您可以使用 disableTouchListener 属性禁用此功能。

Enter 开始编辑

可访问性

(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

Enter 开始编辑

API

请参阅下面的文档,获取此处提及的组件的所有属性和类的完整参考。