跳到主要內容
+

工具提示

當使用者懸停、專注於或點擊元素時,工具提示會顯示資訊性文字。

啟用時,工具提示會顯示文字標籤以識別元素,例如其功能的描述。

按下 Enter 鍵開始編輯

定位的工具提示

Tooltip 元件有 12 種位置選擇。它們沒有方向箭頭;相反地,它們依靠從來源發出的運動來傳達方向。



客製化

以下是一些客製化元件的範例。您可以在覆寫文件頁面中了解更多資訊。

箭頭工具提示

您可以使用 arrow 屬性為您的工具提示加上箭頭,以指示它指向哪個元素。

按下 Enter 鍵開始編輯

與錨點的距離

若要調整工具提示及其錨點之間的距離,您可以使用 slotProps 屬性來修改 popper 的 offset

或者,您可以使用 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 毫秒,因此觸控操作需要長按。

受控工具提示

您可以使用 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

請參閱以下文件,以取得此處提及之元件的所有屬性和類別的完整參考。