Skip to main content Skip to docs navigation
View on GitHub

工具提示框 (Tooltips)

如何透過 CSS 與 Javascript 添加自定義 Bootstrap 工具提示的文件與範例。其中 CSS3 用於動畫，data-bs-attributes 用於用於本地標題的儲存。

六角學院的 Bootstrap 5 課程上線囉，立即與萬人一同學習最專業、最深入的 Bootstrap 5 課程。

立即上課去
On this page

概觀

使用工具提示插件時應瞭解的事情如下：

  • 工具提示依靠第三方函式庫 Popper 以進行定位。你必須在 bootstrap.js 之前加入 popper.min.js，或是使用包含 Popper 的 bootstrap.bundle.min.js / bootstrap.bundle.js 讓工具提示可以運作。
  • 出於效能原因工具提示是選擇性加入的，因此你必須自己將它們初始化
  • 標題長度為零的工具提示將不會被顯示。
  • 指定 container: 'body' 以避免在更複雜的元件 (像是 input 群組、按鈕群組等) 中出現渲染問題。
  • 隱藏元素上的工具提示將不會被觸發。
  • .disabled 或 disabled 元素的工具提示必須在外層元素上被觸發。
  • 被跨越多行的超連結觸發時，工具提示框將居中。在你的 <a> 連結上使用 white-space: nowrap; 來避免這種行為。
  • 必須先隱藏工具提示框，然後才能從 DOM 中刪除相應的元素。
  • 基於 shadow DOM 中的元素，工具提示框可以被觸發。
By default, this component uses the built-in content sanitizer, which strips out any HTML elements that are not explicitly allowed. See the sanitizer section in our JavaScript documentation for more details.
該元件的動畫效果取決於 prefers-reduced-motion media queries。請參考 reduced motion section of our accessibility documentation

都明白了？太好了，讓我們透過一些例子看他們是如何運作的。

範例：在任何地方啟用工具提示

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

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

範例

滑鼠移入以下連結，查看工具提示:

Placeholder text to demonstrate some inline links with tooltips. This is now just filler, no killer. Content placed here just to mimic the presence of real text. 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 these tooltips on links can work in practice, once you use them on your own site or project.

將滑鼠移入以下按鈕，查看工具提示的四個方向：頂部、右側、底部和左側對齊。當使用 Bootstrap 的 RTL，這些方向會被鏡像。

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

Sass

Variables

$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

Tooltip position attempts to automatically change when a parent container has overflow: auto or overflow: scroll like our .table-responsive, but still keeps the original placement’s positioning. To resolve this, set the boundary option (for the flip modifier using the popperConfig option) to any HTMLElement to override the default value, 'clippingParents', such as document.body:

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

標記

工具提示所需的標記只是一個 data 屬性和 title，放置在您希望產生提示的 HTML 元素上。工具提示的生成標記非常簡單，雖然它需要被定位 (默認會被插件設定為 top)

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

您應該只為傳統上可被鍵盤 focus 以及可互動（如連結或表單控制元件）的 HTML 元素添加工具提示。 雖然任意的 HTML 元素（如 <span>）可以透過添加 tabindex="0" 屬性使其可以被 focus ，但這會為鍵盤使用者的非互動式元素增加可能造成困惑的定位點。且大多數的輔助技術目前還不會推播這種工具提示。此外，不要單純依賴 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 屬性的元素是不能互動的，也就是說使用者無法 hover 或是點擊它們來觸發工具提示框（或是彈出提示框）。如果想要啟用，請從外層的 <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>

選項

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

請注意，出於安全性的原因 sanitize, sanitizeFn, 和 allowList 選項不能透過資料屬性提供。
名稱 類型 預設 描述
animation boolean true 將 CSS 漸變轉換套用到工具提示
container string | element | false false

將工具提示加到特定元素。例如：container: 'body'。該選項特別有用，因為它允許您將工具提示定位觸發元素附近的文檔流上 - 這將防止在畫面調整大小期間，彈出的工具提示遠離觸發元素。
delay number | object 0

顯示和隱藏彈出提示框的延遲（ms） - 不適用於手動觸發類型

如果提供了一個數字，則延遲將同時應用於隱藏/顯示

物件結構為: delay: { "show": 500, "hide": 100 }
html boolean false

允許工具提示中包含 HTML。

如果為 true，title 中的 HTML 標註將被渲染於工具提示中。如果為 false，則 innerText 屬性會被用來將內容插入 DOM 中

如果您擔心 XSS 攻擊，請使用 text。
placement string | function 'top'

如何定位工具提示 - auto | top | bottom | left | right.
當 auto 被指定時，將動態重新定位工具提示框。

當函式被用於確定位置時，它將使用工具提示的 DOM 節點作為其第一個參數，並將觸發元素的 DOM 節點作為第二個參數來進行調用。 this 將指向工具提示的實例。
selector string | false false 如果提供了選擇器，工具提示將被委派給指定的目標。實際上，這也用於讓工具提示得以動態的添加 DOM 元素 (jQuery.on 的輔助)。 請參閱 這個 和 an informative example。
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 ''

如果 title 屬性不存在之預設值

如果函式被使用，它將根據 this 所參考到的，也是工具提示所指向的元素來進行調用。
trigger string 'hover focus'

如何觸發工具提示框 - click | hover | focus | manual。你可以傳遞多個觸發器；用空格分隔他們

'manual' 表示工具提示框將通過 .show()、.hide() 和 .toggle() 方法以程式觸發；此值不能與任何其他觸發器組合。

'hover' 本身將導致工具提示框無法通過鍵盤觸發，並且只有在存在為鍵盤使用者傳達相同訊息的替代方法時才應使用。
fallbackPlacements array ['top', 'right', 'bottom', 'left'] 藉由提供陣列中的位置列表（按優先順序）定義預設位置。關於更多資訊，請參閱 Popper 的 behavior 文件。
boundary string | element 'clippingParents' 工具提示框的 overflow constraint boundary (僅適用於 Popper 的 preventOverflow modifier)。在預設情況下，它是 'clippingParents' 並且可以接受 HTMLElement 引用 (僅通過 JavaScript)。有關更多訊息，請參閱 Popper 的 detectOverflow 文件。
customClass string | function ''

在工具提示顯示的時候添加類別。請注意，除了任何在模板內指定的類別以外，這些類別也會被添加上去。用間隔如 'class-1 class-2' 來加入多個類別。

您也可以傳遞一個函式，該函式應該回傳一個單一的字串，包含要添加的類別名稱。
sanitize boolean true 啟用或禁用 sanitization。如果觸發 'template' 和 'title' 選項將被清理。請參閱 我們的 JavaScript 文檔中 sanitizer section。
allowList object 預設值 包含允許屬性與標記的物件
sanitizeFn null | function null 你可以在這裡提供自己的 sanitize 函式。如果你更喜歡用專用的函式庫來進行清理，這將會很有用。
offset array | string | function [0, 0]

工具提示框相對於其目標的偏移量。你可以使用逗號分隔在 data 屬性中傳遞字串，例如：data-bs-offset="10,20"

當一個函數被用來決定偏移量時，它會被一個包含 popper 位置、引用和 popper rects 的對象作為他的第一個參數調用。觸發元素 DOM 節點作為第二個參數傳遞。該函數必須回傳一個包含兩個數字的陣列：[skidding, distance].

更多詳細資訊，請參閱 Popper 的 offset 文件。
popperConfig null | object | function null

要更改 Bootstrap 的預設 Popper 配置，請參閱 Popper's configuration。

當一個函數用於創建 Popper 配置時，它會被一個包含 Bootstrap 的預設 Popper configuration 調用。它可以幫助你使用預設配置並將其與你自己的配置合併。該函數必須為 Popper 回傳一個 configuration object。.

單個工具提示的資料屬性

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

Using function with popperConfig

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

方法

Asynchronous methods and transitions

All API methods are asynchronous and start a transition. They return to the caller as soon as the transition is started but before it ends. In addition, a method call on a transitioning component will be ignored.

See our JavaScript documentation for more information.

展示

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

tooltip.show()

隱藏

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

tooltip.hide()

切換

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

tooltip.toggle()

移除

隱藏和破壞一個元素的工具提示。(移除 DOM 元素上儲存的資料)。使用 delegation (由 selector 選項 創建) 的工具提示不能在後代觸發元素上單獨被銷毀。

tooltip.dispose()

啟用

給一個元素的工具提示顯示的功能。預設情況下啟用工具提示。

tooltip.enable()

禁用

刪除一個元素其工具提示的顯示功能。只有在重新啟用後，才能顯示工具提示框。

tooltip.disable()

啟用切換

切換一個元素之工具提示的顯示或隱藏功能。

tooltip.toggleEnabled()

更新

更新一個元素之工具提示的定位。

tooltip.update()

getInstance

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

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

getOrCreateInstance

靜態 方法，允許你獲取與 DOM 元素相關的 tooltip 實例，或者在未初始化的情況下創建一個新實例。

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

事件

Event type Description
show.bs.tooltip 當調用 show 實例方法時，此事件會立即觸發。
shown.bs.tooltip 當工具提示顯示後，會觸發此事件（待 CSS 轉換完成）。
hide.bs.tooltip 當調用 hide 實例方法時，會立即觸發此事件。
hidden.bs.tooltip 當工具提示隱藏後，會觸發此事件（待 CSS 轉換完成）。
inserted.bs.tooltip 將工具提示範本加到 DOM 後，會在 show.bs.tooltip 事件後觸發此事件。 
var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)

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

tooltip.hide()