Tooltip 工具提示

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

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

<Tooltip title="Delete">
  <IconButton>
    <DeleteIcon />
  </IconButton>
</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>

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

触发器

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

可控的工具提示

使用 open， onOpen 和 onClose 这些属性，您可以控制工具提示的行为。

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

变量宽度

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

<Tooltip title={longText}>
  <Button sx={{ m: 1 }}>Default Width [300px]</Button>
</Tooltip>
<CustomWidthTooltip title={longText}>
  <Button sx={{ m: 1 }}>Custom Width [500px]</Button>
</CustomWidthTooltip>
<NoMaxWidthTooltip title={longText}>
  <Button sx={{ m: 1 }}>No wrapping</Button>
</NoMaxWidthTooltip>

交互式

工具提示组件默认是可交互的（遵循 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

显示和隐藏组件

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

在移动设备上使用时，用户长按元素就会显示出文字提示，并且持续 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>

API

<Tooltip />