跳转到内容

Tooltip

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

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

简单的工具提示

<Tooltip title="Delete">
  <IconButton>
    <DeleteIcon />
  </IconButton>
</Tooltip>

文字提示的位置

The Tooltip has 12 placement choices. 它们没有方向箭头,而是依靠源头发出的运动来传递方向。



自定义文字提示

你可以参考以下一些例子来自定义组件。 You can learn more about this in the overrides documentation page.

文字提示的箭头

您可以通过添加 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>

You can find a similar concept in the wrapping components guide.

If using a class component as a child, you'll also need to ensure that the ref is forwarded to the underlying DOM element. (A ref to the class component itself will not work.)

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>

触发器

You can define the types of events that cause a tooltip to show.

The touch action requires a long press due to the enterTouchDelay prop being set to 700ms by default.

可控的工具提示

You can use the open, onOpen and onClose props to control the behavior of the tooltip.

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

变量宽度

The Tooltip wraps long text by default to make it readable.

<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>

交互式

Tooltips are interactive by default (to pass WCAG 2.1 success criterion 1.4.13). It won't close when the user hovers over the tooltip before the leaveDelay is expired. You can disable this behavior (thus failing the success criterion which is required to reach level AA) by passing disableInteractive.

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

禁用元素

By default disabled elements like <button> do not trigger user interactions so a Tooltip will not activate on normal events like hover. To accommodate disabled elements, add a simple wrapper element, such as a span.

<Tooltip title="You don't have permission to do this">
  <span>
    <Button disabled>A Disabled Button</Button>
  </span>
</Tooltip>
<Tooltip title="You don't have permission to do this">
  <span>
    <button disabled={disabled} style={disabled ? { pointerEvents: 'none' } : {}}>
      A disabled button
    </button>
  </span>
</Tooltip>

过渡动画

Use a different transition.

<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>

跟踪光标

You can enable the tooltip to follow the cursor by setting 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>

虚拟元素

In the event you need to implement a custom placement, you can use the anchorEl prop: The value of the anchorEl prop can be a reference to a fake DOM element. You need to create an object shaped like the VirtualElement.

Hover

显示和隐藏组件

The tooltip is normally shown immediately when the user's mouse hovers over the element, and hides immediately when the user's mouse leaves. A delay in showing or hiding the tooltip can be added through the enterDelay and leaveDelay props, as shown in the Controlled Tooltips demo above.

On mobile, the tooltip is displayed when the user longpresses the element and hides after a delay of 1500ms. You can disable this feature with the disableTouchListener prop.

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

无障碍设计

(WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/)

By default, the tooltip only labels its child element. This is notably different from title which can either label or describe its child depending on whether the child already has a label. For example, in:

<button title="some more information">A button</button>

the title acts as an accessible description. If you want the tooltip to act as an accessible description you can pass describeChild. Note that you shouldn't use describeChild if the tooltip provides the only visual label. Otherwise, the child would have no accessible name and the tooltip would violate 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>