工具提示框（Tooltips）

使用 CSS 和 JavaScript 為您的網站元素加入自訂 Bootstrap 工具提示框的文件與範例，使用 CSS3 動畫和 data-bs 屬性來儲存本地標題。

本頁內容

概覽（Overview）

使用工具提示框外掛程式時需要了解的事項：

工具提示框依賴第三方函式庫 Popper 進行定位。您必須在 bootstrap.js 之前引入 popper.min.js，或使用包含 Popper 的 bootstrap.bundle.min.js。
基於效能考量，工具提示框是選擇性啟用的，所以您必須自己初始化它們。
標題長度為零的工具提示框永遠不會顯示。
指定 container: 'body' 以避免在更複雜的元件中（如我們的輸入群組、按鈕群組等）出現渲染問題。
在隱藏元素上觸發工具提示框將不會運作。
.disabled 或 disabled 元素的工具提示框必須在包裹元素上觸發。
當從跨越多行的超連結觸發時，工具提示框將置中。在您的 <a> 上使用 white-space: nowrap; 來避免此行為。
在將對應元素從 DOM 中移除之前，必須先隱藏工具提示框。
工具提示框可以透過 shadow DOM 內的元素觸發。

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

預設情況下，此元件使用內建的內容清理器，它會移除任何未明確允許的 HTML 元素。請參閱我們 JavaScript 文件中的清理器章節以獲取更多詳細資訊。

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

範例（Examples）

啟用工具提示框（Enable tooltips）

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

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

連結上的工具提示框（Tooltips on links）

將滑鼠懸停在下面的連結上以查看工具提示框：

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。

自訂工具提示框（Custom tooltips）

Added in v5.2.0

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

site/src/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>

方向（Directions）

將滑鼠懸停在下面的按鈕上以查看四個工具提示框方向：上、右、下和左。在 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

變數（Variables）

Added in 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 變數（Sass variables）

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

使用方式（Usage）

工具提示框外掛程式會依需求產生內容和標記，並且預設將工具提示框放置在觸發元素之後。透過 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')
})

標記（Markup）

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

讓工具提示框對鍵盤和輔助技術使用者保持無障礙，只將它們加入到傳統上可透過鍵盤聚焦和互動的 HTML 元素（例如連結或表單控制項）。雖然可以透過加入 tabindex="0" 使其他 HTML 元素可聚焦，但這可能會對鍵盤使用者在非互動元素上建立惱人且令人困惑的 Tab 停靠點，並且大多數輔助技術目前在這種情況下不會宣告工具提示框。此外，不要僅依賴 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 elements）

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

選項（Options）

由於選項可以透過 data 屬性或 JavaScript 傳遞，您可以將選項名稱附加到 data-bs-，例如 data-bs-animation="{value}"。透過 data 屬性傳遞選項時，請確保將選項名稱的大小寫類型從「camelCase」更改為「kebab-case」。例如，使用 data-bs-custom-class="beautifier" 而不是 data-bs-customClass="beautifier"。

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

最終的配置物件是 data-bs-config、data-bs- 和 js object 的合併結果，其中最後給定的鍵值對會覆寫其他的。

請注意，基於安全原因，sanitize、sanitizeFn 和 allowList 選項無法使用 data 屬性提供。

名稱	類型	預設值	說明
`allowList`	object	預設值	包含允許標籤和屬性的物件。未明確允許的將被內容清理器移除。加入此列表時請謹慎行事。請參閱 OWASP 的跨網站腳本攻擊預防小抄以獲取更多資訊。
`animation`	boolean	`true`	對工具提示框套用 CSS 淡出過渡效果。
`boundary`	string, element	`'clippingParents'`	工具提示框的溢位限制邊界（僅適用於 Popper 的 preventOverflow 修飾器）。預設為 `'clippingParents'`，可接受 HTMLElement 參考（僅透過 JavaScript）。更多資訊請參閱 Popper 的 detectOverflow 文件。
`container`	string, element, false	`false`	將工具提示框附加到特定元素。範例：`container: 'body'`。此選項特別有用，因為它允許您將工具提示框定位在文件流中靠近觸發元素的位置，這將防止工具提示框在視窗調整大小時飄離觸發元素。
`customClass`	string, function	`''`	在顯示工具提示框時加入類別。請注意，這些類別將加入到範本中指定的任何類別之外。要加入多個類別，請用空格分隔：`'class-1 class-2'`。您也可以傳遞一個應回傳包含額外類別名稱的單一字串的函式。
`delay`	number, object	`0`	顯示和隱藏工具提示框的延遲（毫秒）—不適用於手動觸發類型。如果提供數字，延遲將同時套用於隱藏/顯示。物件結構為：`delay: { "show": 500, "hide": 100 }`。
`fallbackPlacements`	array	`['top', 'right', 'bottom', 'left']`	透過在陣列中提供位置列表（按優先順序）來定義備用位置。更多資訊請參閱 Popper 的行為文件。
`html`	boolean	`false`	允許工具提示框中的 HTML。如果為 true，工具提示框 `title` 中的 HTML 標籤將在工具提示框中渲染。如果為 false，將使用 `innerText` 屬性將內容插入 DOM。處理使用者產生的輸入時，建議使用文字以防止 XSS 攻擊。
`offset`	array, string, function	`[0, 6]`	工具提示框相對於其目標的偏移。您可以在 data 屬性中傳遞以逗號分隔的值字串，如：`data-bs-offset="10,20"`。當使用函式來決定偏移時，它會以包含 popper 位置、參考和 popper 矩形的物件作為第一個參數呼叫。觸發元素 DOM 節點作為第二個參數傳遞。函式必須回傳包含兩個數字的陣列：skidding、distance。更多資訊請參閱 Popper 的偏移文件。
`placement`	string, function	`'top'`	如何定位工具提示框：auto、top、bottom、left、right。當指定 `auto` 時，它將動態重新定向工具提示框。當使用函式來決定位置時，它會以工具提示框 DOM 節點作為第一個參數，觸發元素 DOM 節點作為第二個參數呼叫。`this` 上下文設定為工具提示框實例。
`popperConfig`	null, object, function	`null`	要變更 Bootstrap 的預設 Popper 配置，請參閱 Popper 的配置。當使用函式建立 Popper 配置時，它會以包含 Bootstrap 預設 Popper 配置的物件呼叫。它幫助您使用並合併預設配置與您自己的配置。函式必須回傳 Popper 的配置物件。
`sanitize`	boolean	`true`	啟用內容清理。如果為 true，`template`、`content` 和 `title` 選項將被清理。停用內容清理時請謹慎行事。請參閱 OWASP 的跨網站腳本攻擊預防小抄以獲取更多資訊。僅因停用內容清理而導致的漏洞不在 Bootstrap 安全模型的範圍內。
`sanitizeFn`	null, function	`null`	提供替代的內容清理函式。如果您偏好使用專用函式庫來執行清理，這會很有用。
`selector`	string, false	`false`	如果提供選擇器，工具提示框物件將委派給指定的目標。實際上，這用於也將工具提示框套用到動態加入的 DOM 元素（`jQuery.on` 支援）。請參閱此議題和一個資訊豐富的範例。注意：`title` 屬性不能用作選擇器。
`template`	string	`'<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"`。
`title`	string, element, function	`''`	工具提示框標題。如果給定函式，它將以 `this` 參考設定為彈出提示框附加到的元素來呼叫。
`trigger`	string	`'hover focus'`	如何觸發工具提示框：click、hover、focus、manual。您可以傳遞多個觸發器；用空格分隔它們。`'manual'` 表示工具提示框將透過 `.tooltip('show')`、`.tooltip('hide')` 和 `.tooltip('toggle')` 方法以程式方式觸發；此值不能與任何其他觸發器組合。單獨使用 `'hover'` 將導致無法透過鍵盤觸發的工具提示框，僅應在存在為鍵盤使用者傳達相同資訊的替代方法時使用。

個別工具提示框的 Data 屬性

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

使用函式與 `popperConfig`

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

方法（Methods）

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

事件（Events）

事件	說明
`hide.bs.tooltip`	當呼叫 `hide` 實例方法時，此事件會立即觸發。
`hidden.bs.tooltip`	當工具提示框完成對使用者隱藏時（將等待 CSS 過渡完成），此事件會觸發。
`inserted.bs.tooltip`	此事件在 `show.bs.tooltip` 事件之後、當工具提示框範本已加入 DOM 時觸發。
`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()

工具提示框（Tooltips）

概覽（Overview）

範例（Examples）

啟用工具提示框（Enable tooltips）

連結上的工具提示框（Tooltips on links）

自訂工具提示框（Custom tooltips）

方向（Directions）

CSS

變數（Variables）

Sass 變數（Sass variables）

使用方式（Usage）

標記（Markup）

停用元素（Disabled elements）

選項（Options）

個別工具提示框的 Data 屬性

使用函式與 popperConfig

方法（Methods）

事件（Events）

使用函式與 `popperConfig`