Skip to main content Skip to docs navigation
View on GitHub

工具提示框 (Tooltips)

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

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 / 4;
$tooltip-padding-x:                 $spacer / 2;
$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-sensitive 一樣，但仍會保持原始放置的位置。為了解決此問題，請將 boundary 選項更改為預設(對於使用 popperConfig 選項的flip修飾)設置為任何 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)

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

您應該只為傳統上可被鍵盤 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 的元素是不能產生互動的，這意味用戶不能使用 focus, hover 或點擊，觸發 (彈出) 工具提示。解決方法是從 <div> 或 <span> 等包裝元素觸發工具提示，且設定 tabindex="0" 使其可以被鍵盤 focus，並在禁用的元素上設定 pointer-events。

<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 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' 表示工具提示將會透過 .tooltip('show'), .tooltip('hide') 和 .tooltip('toggle') 等方法，用編程的方式觸發，這個值不能與任何其他觸發器組合使用

'hover' 將導致鍵盤無法觸發工具提示，且應該只有當「可以向鍵盤用戶傳遞相同訊息的替代方案」存在時，才可以被使用。
fallbackPlacements array ['top', 'right', 'bottom', 'left'] Define fallback placements by providing a list of placements in array (in order of preference). For more information refer to Popper's behavior docs
boundary string | element 'clippingParents' Overflow constraint boundary of the tooltip (applies only to Popper's preventOverflow modifier). By default it's 'clippingParents' and can accept an HTMLElement reference (via JavaScript only). For more information refer to Popper's detectOverflow docs.
customClass string | function ''

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

您也可以傳遞一個函式，該函式應該回傳一個單一的字串，包含要添加的類別名稱。
sanitize boolean true Enable or disable the sanitization. If activated 'template' and 'title' options will be sanitized. See the sanitizer section in our JavaScript documentation.
allowList object 預設值 包含允許屬性與標記的物件
sanitizeFn null | function null 你可以在這裡提供自己的 sanitize 函式。如果你更喜歡用專用的函式庫來進行清理，這將會很有用。
offset array | string | function [0, 0]

Offset of the tooltip relative to its target. You can pass a string in data attributes with comma separated values like: data-bs-offset="10,20"

When a function is used to determine the offset, it is called with an object containing the popper placement, the reference, and popper rects as its first argument. The triggering element DOM node is passed as the second argument. The function must return an array with two numbers: [skidding, distance].

For more information refer to Popper's offset docs.
popperConfig null | object | function null

To change Bootstrap's default Popper config, see Popper's configuration.

When a function is used to create the Popper configuration, it's called with an object that contains the Bootstrap's default Popper configuration. It helps you use and merge the default with your own configuration. The function must return a configuration object for Popper.

單個工具提示的資料屬性

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

Using function with popperConfig

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

Methods

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

事件

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()