in English

工具提示

使用 CSS3 動畫和 data-bs-attributes 本地標題存儲的 CSS 和 JavaScript 添加自定義引導工具提示的文檔和示例。

在本頁面

概述

使用工具提示插件時要知道的事情：

工具提示依賴 3rd 方庫Popper進行定位。您必須在 bootstrap.js 之前包含popper.min.js或使用包含 Popper 的bootstrap.bundle.min.js/以使工具提示起作用！bootstrap.bundle.js
出於性能原因，工具提示是可選的，因此您必須自己初始化它們。
從不顯示具有零長度標題的工具提示。
指定container: 'body'以避免在更複雜的組件（如我們的輸入組、按鈕組等）中出現渲染問題。
在隱藏元素上觸發工具提示將不起作用。
.disabled或元素的工具提示disabled必須在包裝元素上觸發。
當從跨越多行的超鏈接觸發時，工具提示將居中。white-space: nowrap;在你的 s 上使用<a>以避免這種行為。
在從 DOM 中刪除相應元素之前，必須隱藏工具提示。
由於影子 DOM 中的元素，可以觸發工具提示。

默認情況下，該組件使用內置的內容清理器，它會去除任何未明確允許的 HTML 元素。有關更多詳細信息，請參閱我們的 JavaScript 文檔中的 sanitizer 部分。

該組件的動畫效果依賴於 prefers-reduced-motion媒體查詢。請參閱我們可訪問性文檔的減少運動部分。

明白了嗎？太好了，讓我們通過一些示例來看看它們是如何工作的。

示例：隨處啟用工具提示

初始化頁面上所有工具提示的一種方法是通過它們的data-bs-toggle屬性來選擇它們：

var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
  return new bootstrap.Tooltip(tooltipTriggerEl)
})

例子

將鼠標懸停在下面的鏈接上以查看工具提示：

將鼠標懸停在下面的按鈕上可查看四個工具提示方向：頂部、右側、底部和左側。在 RTL 中使用 Bootstrap 時會鏡像方向。

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

並添加了自定義 HTML：

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

使用 SVG：

薩斯

變量

$tooltip-font-size:                 $font-size-sm;
$tooltip-max-width:                 200px;
$tooltip-color:                     $white;
$tooltip-bg:                        $black;
$tooltip-border-radius:             $border-radius;
$tooltip-opacity:                   .9;
$tooltip-padding-y:                 $spacer * .25;
$tooltip-padding-x:                 $spacer * .5;
$tooltip-margin:                    0;

$tooltip-arrow-width:               .8rem;
$tooltip-arrow-height:              .4rem;
$tooltip-arrow-color:               $tooltip-bg;

用法

工具提示插件按需生成內容和標記，默認情況下將工具提示放置在其觸發元素之後。

通過 JavaScript 觸發工具提示：

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

溢出`auto`和`scroll`

當父容器有overflow: auto或overflow: scroll喜歡我們的時，工具提示位置會嘗試自動更改.table-responsive，但仍保持原始位置的定位。要解決此問題，請將boundary選項（使用popperConfig選項的翻轉修飾符）設置為任何 HTMLElement 以覆蓋默認值'clippingParents'，例如document.body：

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

標記

工具提示所需的標記只是一個data屬性，並且title在您希望擁有工具提示的 HTML 元素上。生成的工具提示標記相當簡單，儘管它確實需要一個位置（默認情況下，top由插件設置）。

使工具提示適用於鍵盤和輔助技術用戶

您應該只將工具提示添加到傳統上可通過鍵盤聚焦和交互的 HTML 元素（例如鍊接或表單控件）。儘管可以通過添加屬性使任意 HTML 元素（例如<span>s）成為焦點tabindex="0"，但這會為鍵盤用戶在非交互式元素上添加可能令人討厭和令人困惑的製表位，並且目前大多數輔助技術不會在這種情況下公佈工具提示。此外，不要僅僅依靠hover作為工具提示的觸發器，因為這會使鍵盤用戶無法觸發工具提示。

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

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

禁用元素

具有該disabled屬性的元素不是交互式的，這意味著用戶無法聚焦、懸停或單擊它們來觸發工具提示（或彈出框）。作為一種解決方法，您需要從包裝器中觸發工具提示，<div>或者<span>理想情況下使用tabindex="0".

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

選項

選項可以通過數據屬性或 JavaScript 傳遞。對於數據屬性，將選項名稱附加到中data-bs-，如data-bs-animation="". 通過數據屬性傳遞選項時，請確保將選項名稱的大小寫類型從 camelCase 更改為 kebab-case。例如，不要使用，而是data-bs-customClass="beautifier"使用data-bs-custom-class="beautifier"。

請注意，出於安全原因 sanitize，不能使用數據屬性提供 sanitizeFn、和選項。allowList

姓名	類型	默認	描述
`animation`	布爾值	`true`	對工具提示應用 CSS 淡入淡出過渡
`container`	字符串 \| 元素 \| 錯誤的	`false`	將工具提示附加到特定元素。示例：`container: 'body'`。此選項特別有用，因為它允許您將工具提示定位在文檔流中靠近觸發元素的位置 - 這將防止工具提示在窗口調整大小期間從觸發元素浮動。
`delay`	號碼 \| 目的	`0`	延遲顯示和隱藏工具提示 (ms) - 不適用於手動觸發類型如果提供了一個數字，延遲將應用於隱藏/顯示對象結構為：`delay: { "show": 500, "hide": 100 }`
`html`	布爾值	`false`	在工具提示中允許 HTML。如果為 true，則工具提示中的 HTML 標記`title`將在工具提示中呈現。如果為 false，`innerText`屬性將用於將內容插入 DOM。如果您擔心 XSS 攻擊，請使用文本。
`placement`	字符串 \| 功能	`'top'`	如何定位工具提示 - 自動 \| 頂部 \| 底部 \| 離開 \| 正確的。指定時`auto`，它將動態地重新定向工具提示。當一個函數用於確定位置時，它會以工具提示 DOM 節點作為其第一個參數，觸發元素 DOM 節點作為其第二個參數來調用。`this`上下文設置為工具提示實例。
`selector`	字符串 \| 錯誤的	`false`	如果提供了選擇器，則工具提示對象將被委託給指定的目標。在實踐中，這也用於將工具提示應用於動態添加的 DOM 元素（`jQuery.on`支持）。請參閱this和一個內容豐富的示例。
`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"`.
`title`	字符串 \| 元素 \| 功能	`''`	`title`如果屬性不存在，則默認標題值。如果給定了一個函數，它將被調用，並將其`this`引用設置為工具提示附加到的元素。
`trigger`	細繩	`'hover focus'`	工具提示是如何觸發的 - 點擊 \| 懸停 \| 焦點 \| 手動的。您可以傳遞多個觸發器；用空格分隔它們。 `'manual'`指示工具提示將通過`.show()`,`.hide()`和`.toggle()`方法以編程方式觸發；此值不能與任何其他觸發器組合。 `'hover'`其本身將導致無法通過鍵盤觸發的工具提示，並且僅應在存在為鍵盤用戶傳達相同信息的替代方法時使用。
`fallbackPlacements`	大批	`['top', 'right', 'bottom', 'left']`	通過提供數組中的展示位置列表（按優先順序）來定義後備展示位置。有關更多信息，請參閱 Popper 的行為文檔
`boundary`	字符串 \| 元素	`'clippingParents'`	工具提示的溢出約束邊界（僅適用於 Popper 的 preventOverflow 修飾符）。默認情況下，它`'clippingParents'`可以接受 HTMLElement 引用（僅通過 JavaScript）。有關更多信息，請參閱 Popper 的detectOverflow 文檔。
`customClass`	字符串 \| 功能	`''`	顯示時將類添加到工具提示。請注意，除了模板中指定的任何類之外，還將添加這些類。要添加多個類，請用空格分隔它們：`'class-1 class-2'`. 您還可以傳遞一個函數，該函數應返回包含其他類名的單個字符串。
`sanitize`	布爾值	`true`	啟用或禁用清理。如果激活`'template'`並且`'title'`選項將被清理。請參閱我們的 JavaScript 文檔中的消毒劑部分。
`allowList`	目的	默認值	包含允許的屬性和標籤的對象
`sanitizeFn`	空 \| 功能	`null`	在這裡，您可以提供自己的消毒功能。如果您更喜歡使用專用庫來執行清理，這會很有用。
`offset`	數組 \| 字符串 \| 功能	`[0, 0]`	工具提示相對於其目標的偏移量。您可以使用逗號分隔值在數據屬性中傳遞字符串，例如：`data-bs-offset="10,20"` 當一個函數用於確定偏移量時，調用它時會使用一個包含 popper 放置、引用和 popper rects 作為其第一個參數的對象。觸發元素 DOM 節點作為第二個參數傳遞。該函數必須返回一個包含兩個數字的數組：.`[skidding, distance]` 有關更多信息，請參閱 Popper 的偏移量文檔。
`popperConfig`	空 \| 對象 \| 功能	`null`	要更改 Bootstrap 的默認 Popper 配置，請參閱Popper 的配置。當一個函數用於創建 Popper 配置時，它會被一個包含 Bootstrap 的默認 Popper 配置的對象調用。它可以幫助您使用默認設置並將其與您自己的配置合併。該函數必須為 Popper 返回一個配置對象。

單個工具提示的數據屬性

如上所述，可以通過使用數據屬性來指定單個工具提示的選項。

使用函數`popperConfig`

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

方法

異步方法和轉換

所有 API 方法都是異步的並開始一個轉換。他們在轉換開始但在結束之前立即返回給調用者。此外，過渡組件上的方法調用將被忽略。

有關更多信息，請參閱我們的 JavaScript 文檔。

節目

顯示元素的工具提示。在工具提示實際顯示之前（即在事件發生之前）返回給調用者。shown.bs.tooltip這被認為是工具提示的“手動”觸發。從不顯示具有零長度標題的工具提示。

tooltip.show()

隱藏

隱藏元素的工具提示。在工具提示實際上被隱藏之前（即在事件發生之前）返回給調用者。hidden.bs.tooltip這被認為是工具提示的“手動”觸發。

tooltip.hide()

切換

切換元素的工具提示。在工具提示實際顯示或隱藏之前（即在or事件發生之前）返回給調用者。這被認為是工具提示的“手動”觸發。shown.bs.tooltiphidden.bs.tooltip

tooltip.toggle()

處置

隱藏和銷毀元素的工具提示（刪除 DOM 元素上存儲的數據）。使用委託（使用選項創建）的selector工具提示不能在後代觸發器元素上單獨銷毀。

tooltip.dispose()

使能夠

使元素的工具提示能夠顯示。默認情況下啟用工具提示。

tooltip.enable()

禁用

移除顯示元素工具提示的能力。工具提示只有在重新啟用後才能顯示。

tooltip.disable()

切換啟用

切換顯示或隱藏元素工具提示的能力。

tooltip.toggleEnabled()

更新

更新元素工具提示的位置。

tooltip.update()

獲取實例

允許您獲取與 DOM 元素關聯的工具提示實例的靜態方法

var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance

獲取或創建實例

靜態方法，允許您獲取與 DOM 元素關聯的工具提示實例，或創建一個新的實例以防它未初始化

var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance

活動

事件類型	描述
`show.bs.tooltip`	`show`調用實例方法時立即觸發此事件。
`shown.bs.tooltip`	當工具提示對用戶可見時觸發此事件（將等待 CSS 轉換完成）。
`hide.bs.tooltip`	`hide`調用實例方法時立即觸發此事件。
`hidden.bs.tooltip`	當工具提示完成對用戶隱藏時觸發此事件（將等待 CSS 轉換完成）。
`inserted.bs.tooltip`	此事件`show.bs.tooltip`在工具提示模板添加到 DOM 的事件之後觸發。

var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)

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

tooltip.hide()