in English

工具提示

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

在本頁面

概述

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

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

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

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

該組件的動畫效果依賴於 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>

隨意使用 title或 data-bs-title在您的 HTML 中使用。使用時 title，Popper 會自動替換 data-bs-title為元素渲染時。

自定義工具提示

在 v5.2.0 中添加

您可以使用CSS 變量自定義工具提示的外觀。我們設置了一個自定義類data-bs-custom-class="custom-tooltip"來限定我們的自定義外觀並使用它來覆蓋本地 CSS 變量。

.custom-tooltip {
  --bs-tooltip-bg: var(--bs-primary);
}

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 變量方法的一部分，工具提示現在使用本地 CSS 變量.tooltip來增強實時自定義。CSS 變量的值是通過 Sass 設置的，因此仍然支持 Sass 自定義。

  --#{$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 變量

$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:                    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)

溢出`auto`和`scroll`

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

const tooltip = new bootstrap.Tooltip('#example', {
  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" data-bs-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".

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並且單獨的數據屬性將覆蓋給定的值 on data-bs-config。此外，現有數據屬性能夠容納 JSON 值，例如data-bs-delay='{"show":0,"hide":150}'.

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

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

工具提示

概述

例子

啟用工具提示

鏈接上的工具提示

自定義工具提示

方向

CSS

變量

Sass 變量

用法

溢出auto和scroll

標記

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

禁用元素

選項

單個工具提示的數據屬性

使用函數popperConfig

方法

異步方法和轉換

活動

溢出`auto`和`scroll`

使用函數`popperConfig`