工具提示

文件和範例，說明如何使用 CSS 和 JavaScript 加入自訂 Bootstrap 工具提示，其中 CSS3 用於動畫，而 data-bs-attributes 則用於儲存本地標題。

在此頁面上

概述

使用工具提示外掛程式時應注意的事項

工具提示仰賴第三方函式庫 Popper 來定位。你必須在 bootstrap.js 之前包含 popper.min.js，或使用包含 Popper 的 bootstrap.bundle.min.js。
工具提示是為了效能而選擇加入的，因此你必須自己初始化。
標題長度為零的工具提示絕不會顯示。
指定 container: 'body' 以避免在更複雜的元件（例如我們的輸入群組、按鈕群組等）中產生渲染問題。
在隱藏元素上觸發工具提示將無法運作。
.disabled 或 disabled 元素的工具提示必須在包裝元素上觸發。
當從跨越多行的超連結觸發時，工具提示將置中。在您的 <a> 上使用 white-space: nowrap; 以避免此行為。
工具提示必須在對應的元素從 DOM 中移除之前隱藏。
工具提示可以透過陰影 DOM 中的元素觸發。

都了解了嗎？很好，讓我們透過一些範例看看它們如何運作。

預設情況下，此元件使用內建的內容消毒程式，它會移除任何未明確允許的 HTML 元素。請參閱我們的 JavaScript 文件中的消毒程式區段以取得更多詳細資訊。

此元件的動畫效果取決於 prefers-reduced-motion 媒體查詢。請參閱我們的無障礙文件中的減少動作區段。

範例

啟用工具提示

如上所述，您必須在使用工具提示之前初始化它們。初始化頁面上所有工具提示的一種方法是透過其 data-bs-toggle 屬性選取它們，如下所示

const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]')
const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new bootstrap.Tooltip(tooltipTriggerEl))

連結上的工具提示

將滑鼠游標移到以下連結上以查看工具提示

html

<p class="muted">Placeholder text to demonstrate some <a href="#" data-bs-toggle="tooltip" data-bs-title="Default tooltip">inline links</a> with tooltips. This is now just filler, no killer. Content placed here just to mimic the presence of <a href="#" data-bs-toggle="tooltip" data-bs-title="Another tooltip">real text</a>. And all that just to give you an idea of how tooltips would look when used in real-world situations. So hopefully you've now seen how <a href="#" data-bs-toggle="tooltip" data-bs-title="Another one here too">these tooltips on links</a> can work in practice, once you use them on <a href="#" data-bs-toggle="tooltip" data-bs-title="The last tip!">your own</a> site or project.</p>

請在 HTML 中自由使用 title 或 data-bs-title。當使用 title 時，Popper 會在元素呈現時自動將其替換為 data-bs-title。

自訂工具提示

在 v5.2.0 中新增

您可以使用 CSS 變數自訂工具提示的外觀。我們使用 data-bs-custom-class="custom-tooltip" 設定自訂類別，以設定自訂外觀的範圍，並用它來覆寫本機 CSS 變數。

site/assets/scss/_component-examples.scss

.custom-tooltip {
  --bs-tooltip-bg: var(--bd-violet-bg);
  --bs-tooltip-color: var(--bs-white);
}

html

<button type="button" class="btn btn-secondary"
        data-bs-toggle="tooltip" data-bs-placement="top"
        data-bs-custom-class="custom-tooltip"
        data-bs-title="This top tooltip is themed via CSS variables.">
  Custom tooltip
</button>

說明

將滑鼠游標懸停在以下按鈕上，即可看到四個工具提示方向：上、右、下和左。在 RTL 中使用 Bootstrap 時，方向會產生鏡像。

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" data-bs-title="Tooltip on top">
  Tooltip on top
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" data-bs-title="Tooltip on right">
  Tooltip on right
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" data-bs-title="Tooltip on bottom">
  Tooltip on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" data-bs-title="Tooltip on left">
  Tooltip on left
</button>

並加入自訂 HTML

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-html="true" data-bs-title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
  Tooltip with HTML
</button>

包含 SVG

CSS

變數

在 v5.2.0 中新增

作為 Bootstrap 不斷演進的 CSS 變數方法的一部分，工具提示現在使用 `tooltip` 上的區域 CSS 變數，以增強即時自訂。CSS 變數的值透過 Sass 設定，因此 Sass 自訂仍受支援。

scss/_tooltip.scss

--#{$prefix}tooltip-zindex: #{$zindex-tooltip};
--#{$prefix}tooltip-max-width: #{$tooltip-max-width};
--#{$prefix}tooltip-padding-x: #{$tooltip-padding-x};
--#{$prefix}tooltip-padding-y: #{$tooltip-padding-y};
--#{$prefix}tooltip-margin: #{$tooltip-margin};
@include rfs($tooltip-font-size, --#{$prefix}tooltip-font-size);
--#{$prefix}tooltip-color: #{$tooltip-color};
--#{$prefix}tooltip-bg: #{$tooltip-bg};
--#{$prefix}tooltip-border-radius: #{$tooltip-border-radius};
--#{$prefix}tooltip-opacity: #{$tooltip-opacity};
--#{$prefix}tooltip-arrow-width: #{$tooltip-arrow-width};
--#{$prefix}tooltip-arrow-height: #{$tooltip-arrow-height};

Sass 變數

scss/_variables.scss

$tooltip-font-size:                 $font-size-sm;
$tooltip-max-width:                 200px;
$tooltip-color:                     var(--#{$prefix}body-bg);
$tooltip-bg:                        var(--#{$prefix}emphasis-color);
$tooltip-border-radius:             var(--#{$prefix}border-radius);
$tooltip-opacity:                   .9;
$tooltip-padding-y:                 $spacer * .25;
$tooltip-padding-x:                 $spacer * .5;
$tooltip-margin:                    null; // TODO: remove this in v6

$tooltip-arrow-width:               .8rem;
$tooltip-arrow-height:              .4rem;
// fusv-disable
$tooltip-arrow-color:               null; // Deprecated in Bootstrap 5.2.0 for CSS variables
// fusv-enable

用法

工具提示外掛程式會依需求產生內容和標記，並且預設將工具提示置於其觸發元素之後。透過 JavaScript 觸發工具提示

const exampleEl = document.getElementById('example')
const tooltip = new bootstrap.Tooltip(exampleEl, options)

當父容器有 `overflow: auto` 或 `overflow: scroll` 時，工具提示會自動嘗試變更位置，但仍保持原始位置的定位。設定 boundary 選項（使用 `popperConfig` 選項的翻轉修改器）為任何 HTMLElement 以覆寫預設值 `'clippingParents'`，例如 `document.body`

const tooltip = new bootstrap.Tooltip('#example', {
  boundary: document.body // or document.querySelector('#boundary')
})

標記

工具提示所需的標記只是一個 `data` 屬性和您希望有工具提示的 HTML 元素上的 `title`。工具提示產生的標記相當簡單，儘管它確實需要一個位置（預設由外掛程式設定為 `top`）。

讓鍵盤和輔助技術使用者能存取工具提示，方法是只將工具提示新增到傳統上可由鍵盤對焦且具有互動性的 HTML 元素（例如連結或表單控制項）。雖然其他 HTML 元素可透過新增 tabindex="0" 來讓它們可對焦，但這可能會在非互動元素上為鍵盤使用者建立惱人和令人困惑的定位點，而且目前大多數輔助技術在這種情況下並不會宣告工具提示。此外，請勿僅依賴 hover 作為工具提示的觸發器，因為這將讓鍵盤使用者無法觸發工具提示。

<!-- HTML to write -->
<a href="#" data-bs-toggle="tooltip" data-bs-title="Some tooltip text!">Hover over me</a>

<!-- Generated markup by the plugin -->
<div class="tooltip bs-tooltip-auto" role="tooltip">
  <div class="tooltip-arrow"></div>
  <div class="tooltip-inner">
    Some tooltip text!
  </div>
</div>

已停用的元素

具有 disabled 屬性的元素並非互動性的，表示使用者無法對焦、將滑鼠游標懸停在它們上面，或按一下它們來觸發工具提示（或彈出視窗）。作為解決方法，您會希望從包裝器 <div> 或 <span> 觸發工具提示，理想情況下使用 tabindex="0" 讓它們可由鍵盤對焦。

html

<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" data-bs-title="Disabled tooltip">
  <button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>

選項

由於選項可透過資料屬性或 JavaScript 傳遞，您可以在 data-bs- 後面加上選項名稱，例如 data-bs-animation="{value}"。在透過資料屬性傳遞選項時，請務必將選項名稱的類型從「camelCase」變更為「kebab-case」。例如，請使用 data-bs-custom-class="beautifier"，而不是 data-bs-customClass="beautifier"。

從 Bootstrap 5.2.0 開始，所有元件都支援一個實驗性保留資料屬性 data-bs-config，它可以將簡單的元件組態作為 JSON 字串儲存。當一個元素具有 data-bs-config='{"delay":0, "title":123}' 和 data-bs-title="456" 屬性時，最後的 title 值將會是 456，而個別的資料屬性將會覆寫在 data-bs-config 中給定的值。此外，現有的資料屬性能夠儲存 JSON 值，例如 data-bs-delay='{"show":0,"hide":150}'。

最後的組態物件是 data-bs-config、data-bs- 和 js 物件 的合併結果，其中最新給定的鍵值會覆寫其他鍵值。

請注意，基於安全性考量，sanitize、sanitizeFn 和 allowList 選項無法使用資料屬性提供。

名稱	類型	預設值	說明
`allowList`	物件	預設值	包含允許屬性和標籤的物件。
`animation`	布林值	`true`	對提示工具套用 CSS 淡入淡出轉場。
`boundary`	字串、元素	`'clippingParents'`	提示工具的溢位約束邊界（僅適用於 Popper 的 preventOverflow 修改器）。預設為 `'clippingParents'`，並且可以接受一個 HTMLElement 參考（僅透過 JavaScript）。如需更多資訊，請參閱 Popper 的 detectOverflow 文件。
`container`	字串、元素、false	`false`	將提示工具附加到特定元素。範例：`container: 'body'`。此選項特別有用，因為它允許您將提示工具定位在文件流程中，靠近觸發元素 - 這將防止提示工具在視窗調整大小時飄離觸發元素。
`customClass`	字串、函式	`''`	當提示工具顯示時，新增類別。請注意，這些類別會新增在範本中指定的任何類別之外。若要新增多個類別，請用空格分隔：`'class-1 class-2'`。您也可以傳遞一個函式，該函式應傳回包含其他類別名稱的單一字串。
`延遲`	數字、物件	`0`	延遲顯示和隱藏提示工具（毫秒）—不適用於手動觸發類型。如果提供數字，則延遲會套用在隱藏/顯示上。物件結構為：`delay: { "show": 500, "hide": 100 }`。
`fallbackPlacements`	陣列	`['top', 'right', 'bottom', 'left']`	透過提供陣列中的配置清單（按優先順序排列）來定義備用配置。如需更多資訊，請參閱 Popper 的行為文件。
`html`	布林值	`false`	允許在提示工具中使用 HTML。如果為 true，提示工具的 `title` 中的 HTML 標籤會呈現在提示工具中。如果為 false，`innerText` 屬性會用於將內容插入 DOM 中。如果您擔心 XSS 攻擊，請使用文字。
`偏移`	陣列、字串、函式	`[0, 0]`	提示工具相對於其目標的偏移。您可以傳遞資料屬性中的字串，其值以逗號分隔，例如：`data-bs-offset="10,20"`。當使用函式來確定偏移時，會呼叫該函式，其第一個引數包含一個物件，其中包含 popper 配置、參考和 popper 矩形。觸發元素 DOM 節點會傳遞為第二個引數。該函式必須傳回包含兩個數字的陣列：滑動、距離。如需更多資訊，請參閱 Popper 的偏移文件。
`配置`	字串、函式	`'top'`	如何定位工具提示：自動、頂部、底部、左邊、右邊。當指定為 `auto` 時，它將動態重新調整工具提示的方向。當使用函數來決定配置時，它會以工具提示 DOM 節點作為第一個參數，觸發元素 DOM 節點作為第二個參數來呼叫。`this` 的內容設定為工具提示實例。
`popperConfig`	null、物件、函數	`null`	若要變更 Bootstrap 的預設 Popper 配置，請參閱 Popper 的配置。當使用函數建立 Popper 配置時，它會以包含 Bootstrap 的預設 Popper 配置的物件呼叫。它可以協助您使用並將預設值與您自己的配置合併。此函數必須傳回 Popper 的配置物件。
`sanitize`	布林值	`true`	啟用或停用消毒。如果啟用 `'template'`、`'content'` 和 `'title'` 選項將會被消毒。
`sanitizeFn`	null、函數	`null`	您可以在這裡提供您自己的消毒函數。如果您偏好使用專用函式庫來執行消毒，這會很有用。
`selector`	字串、false	`false`	如果提供選取器，工具提示物件將委派給指定的目標。實際上，這用於將工具提示也套用至動態新增的 DOM 元素（支援 `jQuery.on`）。請參閱此問題和一個有用的範例。注意：`title` 屬性不可用作選取器。
`template`	字串	`'<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'`	建立工具提示時要使用的基本 HTML。工具提示的 `title` 會注入到 `.tooltip-inner`。`.tooltip-arrow` 會變成工具提示的箭頭。最外層的包裝元素應具有 `.tooltip` 類別和 `role="tooltip"`。
`標題`	字串、元素、函式	`''`	工具提示標題。如果提供函式，會以 `this` 參考設定呼叫它，並將其設定為浮動提示所附加的元素。
`觸發器`	字串	`'hover focus'`	工具提示觸發方式：按一下、懸停、焦點、手動。你可以傳遞多個觸發器；用空白分隔它們。`'manual'` 表示工具提示會透過 `.tooltip('show')`、`.tooltip('hide')` 和 `.tooltip('toggle')` 方法以程式方式觸發；此值無法與任何其他觸發器結合。單獨的 `'hover'` 會導致無法透過鍵盤觸發的工具提示，而且僅應在提供傳達相同資訊給鍵盤使用者的其他方法時使用。

個別工具提示的資料屬性

個別工具提示的選項也可以透過使用資料屬性來指定，如上所述。

使用具有 `popperConfig` 的函式

const tooltip = new bootstrap.Tooltip(element, {
  popperConfig(defaultBsPopperConfig) {
    // const newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

方法

所有 API 方法都是非同步的，而且會開始轉換。它們會在轉換開始後立即傳回呼叫者，但在轉換結束之前。此外，會忽略對轉換中元件的方法呼叫。在我們的 JavaScript 文件中了解更多資訊。

方法	說明
`disable`	移除顯示元素工具提示的能力。只有在重新啟用工具提示後，才能顯示工具提示。
`dispose`	隱藏並銷毀元素的工具提示（移除儲存在 DOM 元素上的資料）。使用委派（使用 `selector` 選項建立）的工具提示無法在後代觸發元素上個別銷毀。
`enable`	讓元素的工具提示能夠顯示。工具提示預設為啟用。
`getInstance`	靜態方法，讓您可以取得與 DOM 元素關聯的工具提示實例，或是在尚未初始化的情況下建立新的實例。
`getOrCreateInstance`	靜態方法，讓您可以取得與 DOM 元素關聯的工具提示實例，或是在尚未初始化的情況下建立新的實例。
`hide`	隱藏元素的工具提示。在工具提示實際隱藏之前傳回呼叫者（即在 `hidden.bs.tooltip` 事件發生之前）。這被視為工具提示的「手動」觸發。
`setContent`	提供一種方式，讓您在初始化後變更工具提示的內容。
`show`	顯示元素的工具提示。在工具提示實際顯示之前傳回呼叫者（即在 `shown.bs.tooltip` 事件發生之前）。這被視為工具提示的「手動」觸發。標題長度為零的工具提示永遠不會顯示。
`toggle`	切換元素的工具提示。在工具提示實際顯示或隱藏之前傳回呼叫者（即在 `shown.bs.tooltip` 或 `hidden.bs.tooltip` 事件發生之前）。這被視為工具提示的「手動」觸發。
`toggleEnabled`	切換元素的工具提示是否能夠顯示或隱藏。
`update`	更新元素的工具提示位置。

const tooltip = bootstrap.Tooltip.getInstance('#example') // Returns a Bootstrap tooltip instance

// setContent example
tooltip.setContent({ '.tooltip-inner': 'another title' })

setContent 方法接受 object 參數，其中每個屬性金鑰都是工具提示範本中有效的 string 選擇器，而每個相關屬性值可以是 string | element | function | null

事件

事件	說明
`hide.bs.tooltip`	當呼叫 `hide` 實例方法時，會立即觸發此事件。
`hidden.bs.tooltip`	當工具提示已完成對使用者隱藏時，會觸發此事件（會等待 CSS 轉場完成）。
`inserted.bs.tooltip`	當工具提示範本已新增至 DOM 時，會在 `show.bs.tooltip` 事件後觸發此事件。
`show.bs.tooltip`	當呼叫 `show` 執行個體方法時，會立即觸發此事件。
`shown.bs.tooltip`	當工具提示已對使用者顯示時，會觸發此事件（會等待 CSS 轉場完成）。

const myTooltipEl = document.getElementById('myTooltip')
const tooltip = bootstrap.Tooltip.getOrCreateInstance(myTooltipEl)

myTooltipEl.addEventListener('hidden.bs.tooltip', () => {
  // do something...
})

tooltip.hide()

工具提示

概述

範例

啟用工具提示

連結上的工具提示

自訂工具提示

說明

CSS

變數

Sass 變數

用法

標記

已停用的元素

選項

個別工具提示的資料屬性

使用具有 popperConfig 的函式

方法

事件

使用具有 `popperConfig` 的函式