工具提示（Tooltips）
如何透過CSS與Javascript添加自定義Bootstrap工具提示的文件與示例。其中CSS3用于動(dòng)畫，data-bs-attributes用于用于本地標(biāo)題的儲(chǔ)存。
概述
使用工具提示插件時(shí)應(yīng)注意的事項(xiàng)：
- 工具提示依賴于第三方庫Popper進(jìn)行定位。您必須在bootstrap.js之前包含popper.min.js，或者使用bootstrap.bundle.min.js/bootstrap.bundle.js，其中包含popper，這樣工具提示才能工作！
- 由于性能原因，工具提示是可選的，因此您必須自己初始化它們。
- 標(biāo)題長度為零的工具提示永遠(yuǎn)不會(huì)顯示。
- 指定container:'body'以避免在更復(fù)雜的組件（如輸入組、按鈕組等）中呈現(xiàn)問題。
- 在隱藏元素上觸發(fā)工具提示將不起作用。
- .disabled或disabled元素的工具提示必須在包裝器元素上觸發(fā)。
- 當(dāng)從跨多行的超鏈接觸發(fā)時(shí)，工具提示將居中顯示。使用空白：nowrap；以避免這種行為。
- 在從DOM中刪除相應(yīng)的元素之前，必須隱藏工具提示。
- 由于陰影DOM中的元素，可以觸發(fā)工具提示。
明白了嗎？太好了，讓我們用一些例子來看看它們是如何工作的。
示例：在各處用工具提示
初始化頁面上所有工具提示的一種方法是通過數(shù)據(jù)屬性選擇它們：
var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
return new bootstrap.Tooltip(tooltipTriggerEl)
})
示例
將鼠標(biāo)懸停在以下鏈接上可查看工具提示：
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.
將鼠標(biāo)懸停在下面的按鈕上可以看到四個(gè)工具提示方向：頂部、右側(cè)、底部和左側(cè)。在RTL中使用 Bootstrap時(shí)，方向是鏡像的。
<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;
用法
工具提示插件按需生成內(nèi)容和標(biāo)記，默認(rèn)情況下，將工具提示放在觸發(fā)器元素之后。
通過JavaScript觸發(fā)工具提示：
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)
溢出自動(dòng)和滾動(dòng)
當(dāng)父容器發(fā)生溢出時(shí)，工具提示位置嘗試自動(dòng)更改：自動(dòng)或溢出：像.table一樣滾動(dòng)，但仍保持原始位置的位置。若要解析，請(qǐng)將邊界選項(xiàng)設(shè)置為除默認(rèn)值“scrollParent”以外的任何值，例如“window”：
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
boundary: 'window'
})
標(biāo)記
工具提示所需的標(biāo)記只是您希望具有工具提示的HTML元素的數(shù)據(jù)屬性和標(biāo)題。工具提示的生成標(biāo)記相當(dāng)簡單，盡管它確實(shí)需要一個(gè)位置（默認(rèn)情況下，由插件設(shè)置為top）。
使工具提示適用于鍵盤和輔助技術(shù)使用者
您應(yīng)該只為傳統(tǒng)上可被鍵盤focus以及可互動(dòng)（如連接或表單控制元件）的HTML元素添加工具提示。雖然任意的HTML元素（如span）可以透過添加tabindex=“0”屬性使其可以被focus，但這會(huì)為鍵盤使用者的非互動(dòng)式元素增加可能造成困惑的定位點(diǎn)。且大多數(shù)的輔助技術(shù)目前還不會(huì)推播這種工具提示。此外，不要單純依賴hover作為工具提示的觸發(fā)器，因?yàn)檫@將讓你的工具提示框無法被鍵盤使用者觸發(fā)。
<!-- 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屬性的元素不是交互式的，這意味著用戶不能聚焦、懸停或單擊它們來觸發(fā)工具提示（或popover）。作為一種解決方法，您需要從包裝器div或span觸發(fā)工具提示，最好使用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>選項(xiàng)
選項(xiàng)可以通過數(shù)據(jù)屬性或JavaScript傳遞。對(duì)于數(shù)據(jù)屬性，將選項(xiàng)名稱附加到data-bs-，如data-bs-animation=""中所示。在傳遞數(shù)據(jù)屬性時(shí)，請(qǐng)確保將選項(xiàng)名稱的case類型從camelCase更改為kebab case。例如：不要使用數(shù)據(jù)data-bs-customClass="beautifier"，而是使用數(shù)據(jù) data-bs-custom-class="beautifier"。
| Name | Type | Default | Description |
|---|---|---|---|
animation |
boolean | true |
對(duì)工具提示應(yīng)用CSS淡入淡出過渡 |
container |
string | element | false | false |
將工具提示附加到特定元素。示例：container:'body'。此選項(xiàng)特別有用，因?yàn)樗试S您將工具提示放置在觸發(fā)元素附近的文檔流中—這將防止工具提示在調(diào)整窗口大小期間從觸發(fā)元素中浮動(dòng)。 |
delay |
number | object | 0 |
延遲顯示和隱藏工具提示（ms）-不適用于手動(dòng)觸發(fā)器類型 如果提供了數(shù)字，則對(duì)隱藏/顯示都應(yīng)用延遲 對(duì)象結(jié)構(gòu)是：delay:{“show”：500，“hide”：100} |
html |
boolean | false |
允許在工具提示中使用HTML。 如果為true，則工具提示標(biāo)題中的HTML標(biāo)記將呈現(xiàn)在工具提示中。如果為false，innerText屬性將用于將內(nèi)容插入DOM。 如果您擔(dān)心XSS攻擊，請(qǐng)使用文本。 |
placement |
string | function | 'top' |
如何定位工具提示-自動(dòng)|頂部|底部|左側(cè)|右側(cè)。當(dāng)指定auto時(shí)，它將動(dòng)態(tài)地重定向工具提示。 函數(shù)用于確定位置時(shí)，調(diào)用它時(shí)，工具提示DOM節(jié)點(diǎn)作為第一個(gè)參數(shù)，觸發(fā)元素DOM節(jié)點(diǎn)作為第二個(gè)參數(shù)。此上下文設(shè)置為工具提示實(shí)例。 |
selector |
string | false | false |
如果提供了選擇器，則工具提示對(duì)象將委派給指定的目標(biāo)。實(shí)際上，它還用于將工具提示應(yīng)用于動(dòng)態(tài)添加的DOM元素（jQuery.on support）。請(qǐng)看這個(gè)和一個(gè)信息豐富的例子。 this and an informative example. |
template |
string |
'<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'
|
創(chuàng)建工具提示時(shí)要使用的基本HTML。 工具提示的標(biāo)題將被注入.tooltip內(nèi)部。 工具提示箭頭將成為工具提示的箭頭。 最外層的包裝器元素應(yīng)該具有.tooltip類和role=“tooltip”。 |
title |
string | element | function | '' |
如果標(biāo)題屬性不存在，則為默認(rèn)標(biāo)題值。 如果給定了一個(gè)函數(shù)，將調(diào)用該函數(shù)，并將其this引用設(shè)置為工具提示所附加到的元素。 |
trigger |
string | 'hover focus' |
如何觸發(fā)工具提示-單擊“懸停”“聚焦”“手動(dòng)”。您可以傳遞多個(gè)觸發(fā)器；用空格隔開。 “manual”表示工具提示將通過.tooltip（'show'）、.tooltip（'hide'）和.tooltip（'toggle'）方法以編程方式觸發(fā)；此值不能與任何其他觸發(fā)器組合。 “懸停”本身將導(dǎo)致無法通過鍵盤觸發(fā)的工具提示，并且僅當(dāng)存在用于向鍵盤用戶傳遞相同信息的替代方法時(shí)才應(yīng)使用。 |
fallbackPlacements |
array | ['top', 'right', 'bottom', 'left'] |
通過提供數(shù)組中的放置列表（按優(yōu)先順序）來定義后備放置。有關(guān)更多信息，請(qǐng)參閱波普爾的行為文檔 behavior docs |
boundary |
string | element | 'clippingParents' |
工具提示的溢出約束邊界。默認(rèn)情況下，它是'clippingParents'，可以接受HTMLElement引用（僅限于JavaScript）。有關(guān)更多信息，請(qǐng)參閱波普爾的文件。 preventOverflow docs. |
customClass |
string | function | '' |
在顯示工具提示時(shí)向其添加類。請(qǐng)注意，這些類將添加到模板中指定的任何類之外。要添加多個(gè)類，請(qǐng)用空格分隔它們：“class-1 class-2”。 還可以傳遞一個(gè)函數(shù)，該函數(shù)應(yīng)返回一個(gè)包含其他類名的字符串。 |
sanitize |
boolean | true |
啟用或禁用消毒。如果激活，“模板”和“標(biāo)題”選項(xiàng)將被清除。請(qǐng)參閱我們的JavaScript文檔中的消毒劑部分。 |
allowList |
object | Default value | 包含允許的屬性和標(biāo)記的對(duì)象 |
sanitizeFn |
null | function | null |
在這里您可以提供自己的消毒功能。如果您喜歡使用專用的庫來執(zhí)行清理，這將非常有用。 |
offset |
array | string | function | [0, 0] |
工具提示相對(duì)于其目標(biāo)的偏移量。您可以用逗號(hào)分隔的值在數(shù)據(jù)屬性中傳遞字符串，例如：data bs offset=“10,20” 當(dāng)一個(gè)函數(shù)用于確定偏移量時(shí)，調(diào)用它的第一個(gè)參數(shù)是包含popper放置、引用和popper rects的對(duì)象。觸發(fā)元素DOM node作為第二個(gè)參數(shù)傳遞。函數(shù)必須返回一個(gè)包含兩個(gè)數(shù)字的數(shù)組：[滑動(dòng)，距離]。 F有關(guān)更多信息，請(qǐng)參閱offset docs. |
popperConfig |
null | object | function | null |
T要更改引導(dǎo)的默認(rèn)Popper配置，請(qǐng)參閱Popper的配置。 . 當(dāng)一個(gè)函數(shù)被用來創(chuàng)建Popper配置時(shí)，它被一個(gè)包含引導(dǎo)的默認(rèn)Popper配置的對(duì)象調(diào)用。它可以幫助您使用默認(rèn)配置并將其與您自己的配置合并。函數(shù)必須返回Popper的配置對(duì)象。 |
單個(gè)工具提示的數(shù)據(jù)屬性
也可以通過使用數(shù)據(jù)屬性來指定單個(gè)工具提示的選項(xiàng)，如上所述。
Using function with popperConfig
var tooltip = new bootstrap.Tooltip(element, {
popperConfig: function (defaultBsPopperConfig) {
// var newPopperConfig = {...}
// use defaultBsPopperConfig if needed...
// return newPopperConfig
}
})
方法
異步方法和轉(zhuǎn)換
所有API方法都是異步的，并開始轉(zhuǎn)換。轉(zhuǎn)換一開始就返回到調(diào)用方，但在轉(zhuǎn)換結(jié)束之前返回。此外，對(duì)轉(zhuǎn)換組件的方法調(diào)用將被忽略。 有關(guān)更多信息，請(qǐng)參閱我們的JavaScript文檔。
顯示
顯示元素的工具提示。在工具提示實(shí)際顯示之前（即，在show.bs.tooltip事件發(fā)生之前）返回調(diào)用方。這被認(rèn)為是工具提示的“手動(dòng)”觸發(fā)。標(biāo)題長度為零的工具提示永遠(yuǎn)不會(huì)顯示。
tooltip.show()
隱藏
隱藏元素的工具提示。在工具提示實(shí)際隱藏之前（即在hidden.bs.tooltip事件發(fā)生之前）返回調(diào)用方。這被認(rèn)為是工具提示的“手動(dòng)”觸發(fā)。
tooltip.hide()
切換
切換元素的工具提示。在工具提示實(shí)際顯示或隱藏之前（即，在Showed.bs.tooltip或hidden.bs.tooltip事件發(fā)生之前）返回調(diào)用方。這被認(rèn)為是工具提示的“手動(dòng)”觸發(fā)。
tooltip.toggle()
注銷
隱藏和銷毀元素的工具提示（刪除DOM元素上存儲(chǔ)的數(shù)據(jù)）。使用委派（使用選擇器選項(xiàng)創(chuàng)建）的工具提示不能在子觸發(fā)器元素上單獨(dú)銷毀。
tooltip.dispose()
啟用
使元素的工具提示能夠顯示。默認(rèn)情況下啟用工具提示。
tooltip.enable()
禁用
取消顯示元素工具提示的功能。工具提示只有在重新啟用時(shí)才能顯示。
tooltip.disable()
啟用切換
切換顯示或隱藏元素工具提示的功能。
tooltip.toggleEnabled()
更新
更新元素工具提示的位置。
tooltip.update()
獲取實(shí)例
靜態(tài)方法，該方法允許您獲取與DOM元素關(guān)聯(lián)的工具提示實(shí)例
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
事件
| Event type | Description |
|---|---|
show.bs.tooltip |
當(dāng)調(diào)用show實(shí)例方法時(shí)，此事件會(huì)立即觸發(fā)。 |
shown.bs.tooltip |
當(dāng)工具提示顯示后，會(huì)觸發(fā)此事件（待CSS轉(zhuǎn)換完成）。 |
hide.bs.tooltip |
當(dāng)調(diào)用hide實(shí)例方法時(shí)，會(huì)立即觸發(fā)此事件。 |
hidden.bs.tooltip |
當(dāng)工具提示隱藏后，會(huì)觸發(fā)此事件（待CSS轉(zhuǎn)換完成）。 |
inserted.bs.tooltip |
將工具提示模板加到DOM后，會(huì)在show.bs.tooltip事件后觸發(fā)此事件。 |
var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)
myTooltipEl.addEventListener('hidden.bs.tooltip', function () {
// do something...
})
tooltip.hide()