工具提示
當使用者懸停、專注於或點擊元素時,工具提示會顯示資訊性文字。
啟用時,工具提示會顯示文字標籤以識別元素,例如其功能的描述。
定位的工具提示
Tooltip
元件有 12 種位置選擇。它們沒有方向箭頭;相反地,它們依靠從來源發出的運動來傳達方向。
箭頭工具提示
您可以使用 arrow
屬性為您的工具提示加上箭頭,以指示它指向哪個元素。
或者,您可以使用 slotProps
屬性來自訂 popper 的邊距。
自訂子元素
工具提示需要將 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。