跳转到内容

Tooltip 工具提示

当用户鼠标悬停,聚焦或者轻触一个元素时,工具提示组件会显示一段有意义的文本。

当它触发时, Tooltips 会显示标识一个元素的文本标签,比如对该功能的描述。

简单的文字提示

<Tooltip title="Delete">
  <IconButton>
    <DeleteIcon />
  </IconButton>
</Tooltip>
<Tooltip title="Add">
  <Fab color="primary" className={classes.fab}>
    <AddIcon />
  </Fab>
</Tooltip>
<Tooltip title="Add">
  <Fab color="secondary" className={classes.absolute}>
    <AddIcon />
  </Fab>
</Tooltip>

文字提示的位置

Tooltip 有 12 个位置 选项。 它们没有方向箭头,而是依靠代码指示的移动情况来移动文字提示的出现位置。



自定义文字提示

你可以参考以下一些例子来自定义组件。 您可以在重写文档页中了解有关此内容的更多信息。

文字提示的箭头

您可以通过添加 arrow 属性向提示标签增加箭头指示器,从而可以凸显所指示的元素。

<Tooltip title="Add" arrow>
  <Button>Arrow</Button>
</Tooltip>

自定义子元素

文字提示组件需要将 DOM 事件监听器应用到其子元素当中。 如果子元素是自定义的 React 组件,你需要确保它能够将其属性传播到底部的 DOM 元素。

const MyComponent = React.forwardRef(function MyComponent(props, ref) {
  // 将属性传递给底部的 DOM 元素。
  return <div {...props} ref={ref}>Bin</div>
});

// ...

<Tooltip title="删除">
  <MyComponent>
</Tooltip>

您可以在包装的组件指南中找到类似的概念。

触发器

你可以定义各种类型的事件来触发显示工具提示组件。

受控的文字提示

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

<Tooltip open={open} onClose={handleClose} onOpen={handleOpen} title="Add">
  <Button>Controlled</Button>
</Tooltip>

变量宽度

为了保证可阅读性,工具提示组件 默认将较长的文字折行。

<Tooltip title={longText}>
  <Button className={classes.button}>Default Width [300px]</Button>
</Tooltip>
<Tooltip title={longText} classes={{ tooltip: classes.customWidth }}>
  <Button className={classes.button}>Custom Width [500px]</Button>
</Tooltip>
<Tooltip title={longText} classes={{ tooltip: classes.noMaxWidth }}>
  <Button className={classes.button}>No wrapping</Button>
</Tooltip>

交互式

工具提示组件默认是可交互的(遵循 WCAG 2.1 success criterion 1.4.13)。 若用户在 leaveDelay 过期之前将鼠标悬停在工具提示上时,它则不会被关闭。 你可以通过 disableInteractive 来禁止交互(但是这将无法达到 AA 级所需的标准)。

<Tooltip title="Add" disableInteractive>
  <Button>Not interactive</Button>
</Tooltip>

禁用元素

默认情况下,被禁用的元素(如 <Button>)不会触发用户交互行为,因此 hover 等普通的事件不会激活工具提示的显示。 若想容纳已禁用的元素激活工具提示,请添加一个简单的包装元素,如 span

⚠️ 为了在 Safari 中正常显示,在文字提示的包装组件中,您至少需要一个 display 为 block 或 flex 的元素。

<Tooltip title="You don't have permission to do this">
  <span>
    <Button disabled>A Disabled Button</Button>
  </span>
</Tooltip>

如果你没有包装从 ButtonBase 继承的 Material-UI 组件,譬如一个原生的 <button> 元素,当禁用元素的时候,你应该将 pointer-events: none; 这个CSS 属性添加到您的元素中:

<Tooltip title="您没有足够的操作权限">
  <span>
    <button disabled={disabled} style={disabled ? { pointerEvents: 'none' } : {}}>
      一个禁用的按钮
    </button>
  </span>
</Tooltip>

过渡动画

使用不同的过渡动画。

<Tooltip title="Add">
  <Button>Grow</Button>
</Tooltip>
<Tooltip
  TransitionComponent={Fade}
  TransitionProps={{ timeout: 600 }}
  title="Add"
>
  <Button>Fade</Button>
</Tooltip>
<Tooltip TransitionComponent={Zoom} title="Add">
  <Button>Zoom</Button>
</Tooltip>

跟踪光标

你可以通过设置 followCursor={true} 使工具提示组件跟随光标。

Disabled Action
<Tooltip title="You don't have permission to do this" followCursor>
  <Box sx={{ bgcolor: 'text.disabled', color: 'background.paper', p: 2 }}>
    Disabled Action
  </Box>
</Tooltip>

虚拟元素

如果你需要实现一个自定义的布局,那么你可以使用 anchorEl 属性: anchorEl 属性的值可以是一个假(fake) DOM 元素的引用。 你需要创建一个类似 VirtualElement 的对象。

Hover

显示和隐藏组件

一般情况下,当用户的鼠标悬停在元素上时,工具提示会立即显示,而用户的鼠标离开当前元素时,它则会立即隐藏。 可以通过 enterDelayleaveDelay 属性来控制显示及隐藏文字提示的延迟,如上面的"受控的文字提示"部分的例子所示。

在移动设备上使用时,用户长按元素就会显示出文字提示,并且持续 1500ms 之后就会自动隐藏。 您可以使用 disableTouchListener 属性禁用此功能。

<Tooltip title="Add" enterDelay={500} leaveDelay={200}>
  <Button>[500ms, 200ms]</Button>
</Tooltip>

无障碍设计

(WAI-ARIA: https://www.w3.org/TR/wai-aria-practices/#tooltip)

默认情况下,工具提示组件只会标注其子元素。 这与 title 明显不同,后者可以标注 描述它的子代,这取决于子代是否已经有标签。 例如,在:

<button title="some more information">一个按钮</button>

title 可以作为一种无障碍描述。 你可以通过设置 describeChild 来让你的工具提示组件具有无障碍描述的功能。 请注意,如果工具提示组件提供了唯一的视觉标签,那么你就不应该使用 describeChild。 否则,子元素将不会存在可访问的名称,而工具提示将违反 WCAG 2.1 success criterion 2.5.3 in WCAG 2.1

<Tooltip title="Delete">
  <IconButton>
    <DeleteIcon />
  </IconButton>
</Tooltip>
<Tooltip describeChild title="Does not add if it already exists.">
  <Button>Add</Button>
</Tooltip>