工具提示框 (Tooltips)

Bootstrap 的工具提示框文件與範例,工具提示框使用 CSS3 作為動畫顯示及資了屬性作為標題儲存。

六角學院 六角學院

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

立即上課去

概觀

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

  • 工具提示框依靠第三方函式庫 Popper.js 進行定位。 在 Bootstrap 工具提示框工作之前,您必須包含 popper.min.js,或者使用 bootstrap.bundle.min.js / bootstrap.bundle.js,這已經包含 Popper.js 可以直接運作。
  • 如果自行編譯 JS,記得 requires util.js
  • 工具提示框因為校能原因所以是選擇加入,所以 您必須自己將他們初始化
  • 零長度 titlecontent 值將永遠不會顯示一個工具提示框。
  • 指定 container: 'body' 以避免在更複雜的元件(如我們的輸入群組,按鈕群組等)中呈現問題。
  • 隱藏元素的工具提示框是不會成功的。
  • .disableddisabled 元素工具提示框的觸發必須在外層元素上。
  • 當從跨越多行的超連結觸發時,工具提示框將被居中。在你的 <a> 上使用 white-space: nowrap; 來避免這種行為。
  • 必須先隱藏工具提示框,然後才能從 DOM 中刪除相應的元素。

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

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

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

$(function () {
  $('[data-toggle="tooltip"]').tooltip()
})

範例

滑鼠 hover 以下連結上以查看工具提示框

Tight pants next level keffiyeh you probably haven't heard of them. Photo booth beard raw denim letterpress vegan messenger bag stumptown. Farm-to-table seitan, mcsweeney's fixie sustainable quinoa 8-bit american apparel have a terry richardson vinyl chambray. Beard stumptown, cardigans banh mi lomo thundercats. Tofu biodiesel williamsburg marfa, four loko mcsweeney's cleanse vegan chambray. A really ironic artisan whatever keytar, scenester farm-to-table banksy Austin twitter handle freegan cred raw denim single-origin coffee viral.

靜態演示

有四個選項可供選擇:頂部、右側、底部和左側對齊。

互動演示

將滑鼠 hover 以下按鈕上以查看他們的工具提示框。

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

添加自訂的 HTML:

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

用法

工具提示框插件根據需要生成內容和標記,預設情況下它們在觸發元素之後放置工具提示框。

透過 JavaScript 啟用彈出工具提示框。

$('#example').tooltip(options)

標記

工具提示框所需的標記只是一個 data 屬性,和您希望擁有一個工具提示框 HTML 元素上的 title。 生成工具提示框的標記是相當簡單的,儘管它需要一個位置(預設情況下,他的位置是 top)。

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

您只應為傳統上鍵盤 focus 和互動式(如連結或表單控制元件)的 HTML 元素添加工具提示框。 雖然任意的 HTML 元素(如<span>)可以透過添加 tabindex="0" 屬性來調整 focus ,但這會為鍵盤使用者的非互動式元素增加可能造成困惑的定位點。 此外,大多數輔助技術目前還沒有加入這種情況下的工具提示框。

<!-- HTML to write -->
<a href="#" data-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="arrow"></div>
  <div class="tooltip-inner">
    Some tooltip text!
  </div>
</div>

選項

可以透過資料屬性或 JavaScript 傳遞選項。對於資料屬性,將選項名稱附加到 data-,如 data-animation=""

名稱 類型 預設值 描述
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,則將使用 jQuery的 text 方法將內容插入到 DOM 中。如果您擔心 XSS 攻擊,請使用文字。

placement string | function 'top'

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

當函數用於確定位置時,將使用工具提示框 DOM 節點作為其第一個參數並將觸發元素 DOM 節點作為其第二個參數來調用。 this 將被設為彈出提示框實例。

selector string | false false 如果提供了選擇器,工具提示框將被委派給指定的目標。實際上,這用於動態 HTML 來擴增工具提示物件。 請參閱一個訊息範例
template string '<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>'

創建工具提示框時使用的基本 HTML

工具提示框的 title 將被注入到 .tooltip-inner 中。

.arrow 將成為工具提示框的箭頭。

最外層的包裝元素應該有 .tooltip

title string | element | function ''

如果 title 屬性不存在,則為預設標題值。

如果給出一個函數,它將被調用,其 this 引用設置為工具提示框附加到的元素。

trigger string 'hover focus' 如何觸發工具提示框 - click | hover | focus | manual。 您可以傳遞多個觸發器;將它們與空格分開。`manual` 不能與任何其他觸發器組合。
offset number | string 0 工具提示框相對於其目標的偏移。更多信息,請參閱 Popper.js 的 偏移文檔
fallbackPlacement string | array 'flip' 指定工具提示框將在調回時使用哪個位置。 有關更多信息,請參閱 Popper.js 的 行為文檔

單個工具提示框的資料屬性

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

方法

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.

$().tooltip(options)

將一個工具提示框控制加到元素集合。

.tooltip('show')

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

$('#element').tooltip('show')

.tooltip('hide')

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

$('#element').tooltip('hide')

.tooltip('toggle')

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

$('#element').tooltip('toggle')

.tooltip('dispose')

Hides and destroys an element’s tooltip. Tooltips that use delegation (which are created using the selector option) cannot be individually destroyed on descendant trigger elements.

隱藏和破壞元素的工具提示框。 使用委託 the selector option) 工具提示框不能在後代觸發元素上單獨銷毀。

$('#element').tooltip('dispose')

.tooltip('enable')

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

$('#element').tooltip('enable')

.tooltip('disable')

Removes the ability for an element’s tooltip to be shown. The tooltip will only be able to be shown if it is re-enabled.

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

$('#element').tooltip('disable')

.tooltip('toggleEnabled')

Toggles the ability for an element’s tooltip to be shown or hidden.

$('#element').tooltip('toggleEnabled')

.tooltip('update')

切換要顯示或隱藏元素的工具提示框的功能。

$('#element').tooltip('update')

Events

</tr> </thead> </table>
$('#myTooltip').on('hidden.bs.tooltip', function () {
  // do something…
})
事件類型/th> 描述
show.bs.tooltip 當調用 show 實例方法時,此事件會立即觸發。
shown.bs.tooltip 當工具提示框顯示後,會觸發此事件(待CSS轉換完成)。
hide.bs.tooltip 當調用 hide 實例方法時,會立即觸發此事件。
hidden.bs.tooltip 當工具提示框對隱藏後,會觸發此事件(待CSS轉換完成)。
inserted.bs.tooltip 將工具提示框範本加到 DOM 後,會在 show.bs.tooltip 事件後觸發此事件。