View on GitHub

彈出提示框 (Popovers)

Bootstrap 彈出提示框的文件與範例，風格類似 iOS，可加在網頁上的任何元素上。

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

On this page

概觀

使用彈出提示框插件時應該了解的事情：

彈出提示框需依靠第三方函式庫 Popper 進行定位。您必須在 bootstrap.js 之前引入 popper.min.js 或是使用已經包含 Popper 的 bootstrap.bundle.min.js / bootstrap.bundle.js 讓彈出提示框運作。
彈出提示框需要工具提示插件作為依賴項目。
出於效能上的考量，彈出提示框是選擇性加入的，因此您必須自行初始化 。
title 和 content 值為空時，將永遠不會顯示彈出提示框。
強調 container: 'body' 以避免在更複雜的元件 (例如 Input 群組、 button 群組等等) 中出現渲染問題。
在隱藏的元素中，觸發彈出提示框是不會作用的。
.disabled 或 disabled 元素的彈出提示框必須在外層元素上觸發。
當在跨多行的錨點中觸發時，彈出提示框會定位於整體寬度的中間。在您的 <a> 元素上使用 .text-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 popoverTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
  return new bootstrap.Popover(popoverTriggerEl)
})

範例: 使用 `container` 選項

當您在父元素上有一些干擾彈出提示框的樣式時，您將需要指定一個自訂的 container ，以便讓彈出提示框的 HTML 顯示在該元素中。

var popover = new bootstrap.Popover(document.querySelector('.example-popover'), {
  container: 'body'
})

範例

<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="Popover title" data-bs-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>

四個方向

共有四個選項：top, right, bottom, 和 left 對齊。在 Bootstrap 的 RTL 中，方向會被鏡像。

<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="Top popover">
  Popover on top
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="right" data-bs-content="Right popover">
  Popover on right
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="bottom" data-bs-content="Bottom popover">
  Popover on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="left" data-bs-content="Left popover">
  Popover on left
</button>

下次點擊移除

使用 focus 觸發，當用戶點擊切換元素以外的其他元素時，會移除這個彈出提示框。

下次點擊移除必須使用特定標籤

為了跨瀏覽器與跨平台運用，您必須使用 <a> 標籤, 而不是 <button> 標籤，且必須包含 tabindex 屬性.

Dismissible popover

<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" title="Dismissible popover" data-bs-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>

var popover = new bootstrap.Popover(document.querySelector('.popover-dismiss'), {
  trigger: 'focus'
})

禁用元素

具有 disabled 屬性的元素是不能互動的，也就是說使用者無法 hover 或是點擊它們來觸發彈出提示框（或是工具提示框）。如果想要啟用，請從外層的 <div> 或 <span>觸發彈出提示框，最好使用 tabindex="0" 使鍵盤聚焦。

對於禁用的彈出提示框觸發，您可能傾向使用 data-bs-trigger="hover focus" 來直接為用戶提供視覺回饋，因為用戶預期不會去點擊禁用的元素。

<span class="d-inline-block" tabindex="0" data-bs-toggle="popover" data-bs-trigger="hover focus" data-bs-content="Disabled popover">
  <button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>

Sass

Variables

$popover-font-size:                 $font-size-sm;
$popover-bg:                        $white;
$popover-max-width:                 276px;
$popover-border-width:              $border-width;
$popover-border-color:              rgba($black, .2);
$popover-border-radius:             $border-radius-lg;
$popover-inner-border-radius:       subtract($popover-border-radius, $popover-border-width);
$popover-box-shadow:                $box-shadow;

$popover-header-bg:                 shade-color($popover-bg, 6%);
$popover-header-color:              $headings-color;
$popover-header-padding-y:          .5rem;
$popover-header-padding-x:          $spacer;

$popover-body-color:                $body-color;
$popover-body-padding-y:            $spacer;
$popover-body-padding-x:            $spacer;

$popover-arrow-width:               1rem;
$popover-arrow-height:              .5rem;
$popover-arrow-color:               $popover-bg;

$popover-arrow-outer-color:         fade-in($popover-border-color, .05);

用法

使用 JavaScript 啟用彈出提示框

var exampleEl = document.getElementById('example')
var popover = new bootstrap.Popover(exampleEl, options)

讓彈出提示框對鍵盤與輔助技術的用戶有效

要讓鍵盤用戶啟用您的彈出提示框，您應該只將它們添加到傳統可被鍵盤 focus 和互動的 HTML 元素（像是連結或是表單元件）。雖然任意的 HTML 元素（像是 <span> ）都可以透過加上 tabindex="0" 屬性來 focus，但這會讓鍵盤用戶對這些無法互動的元素感到討厭和疑惑，並且大多的輔助技術都不會在這種情況下讀取彈出提示框的內容。另外，請不要僅使用 hover 來觸發您的彈出提示框，因為鍵盤用戶無法觸發它們。

雖然您可插入豐富、有結構的 html 選項到彈出提示框中，但我們強烈建議您避免增加過多的內容。它們目前的運作方式是一旦顯示，它的內容將會觸發綁定到 aria-describedby 屬性。基於此結果，彈出提示框的所有內容將會被輔助技術如流水般的全部讀出。

此外，儘管彈出提示框中可以包含互動元件（例如：表單元素或是連結） (透過增加這些元素到 allowList 所允許的屬性和標籤)，但請注意，當前彈出提示框不會管理鍵盤 focus 順序。當鍵盤用戶打開彈出提示框，focus 仍會停留在觸發的元素上，且因為彈出視窗並不會立即跟著 document 結構被觸發，因此無法保證鍵盤用戶能使用向前/點擊 TAB 來移動到彈出提示框中。簡而言之，隨意將互動元件加入到彈出提示框可能會使這些元件無法被鍵盤用戶或輔助技術者讀取或使用，或者使 foucs 順序不合邏輯。在這樣的情況下，請考慮優先使用 modal dialog。

選項

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

基於安全性的原因， data 屬性不提供 sanitize, sanitizeFn 和 allowList 選項。

名稱	類型	預設	描述
`animation`	boolean	`true`	將 CSS 淡入/淡出效果用於彈出提示框
`container`	string \| element \| false	`false`	將彈出提示框加到特定元素。例如： `container: 'body'`. 該選項特別有用，因為它允許您將彈出視窗定位在觸發元素附近的文字內容 - 這將防止在畫面調整大小期間彈出視窗遠離觸發元素。
`content`	string \| element \| function	`''`	如果 `data-bs-content` 屬性不存在，則為預設內容值。如果使用函數，它的 `this` 將會指向彈出提示框。
`delay`	number \| object	`0`	延遲顯示和隱藏彈出提示框 (ms) - 不適用於手動觸發如果有提供數值，延遲則會同時被應用在隱藏/顯示物件結構： `delay: { "show": 500, "hide": 100 }`
`html`	boolean	`false`	將 HTML 插入到彈出提示框。如果是 false，`innerText` 屬性會被用於插入內容到 DOM。如果您擔心 XSS 攻擊，請使用文字。
`placement`	string \| function	`'right'`	如何定位彈出提示框 - auto \| top \| bottom \| left \| right. 指定 `auto` 時，將動態重新定位彈出提示框。當函式用於定位時，將使用彈出提示框 DOM 節點作為其第一個參數並將觸發元素 DOM 節點作為其第二個參數來調用。 `this` 將被設為彈出提示框實例。
`selector`	string \| false	`false`	如果提供了選擇器，彈出提示框將被指到特定目標。實際上，這會讓動態 HTML 能夠擴增彈出提示框。請參閱此和一個範例訊息。
`template`	string	`'<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'`	創建彈出提示框時使用的基本 HTML 彈出提示框的 `title` 將被注入到 `.popover-header`中。彈出提示框的 `content` 將被注入到 `.popover-body`中。 `.popover-arrow` 將成為彈出提示框的箭頭。最外層的元素必須有 `.popover` 這個 class 名稱。
`title`	string \| element \| function	`''`	如果 `title` 屬性不存在，所預設的標題值。如果函式存在，它將被調用，其 `this` 指向的是具有彈出提示框元素。
`trigger`	string	`'click'`	如何觸發動態提示框 - click \| hover \| focus \| manual 。您可以使用多個觸發器，並將它們用空格來分開。 `manual` 不能與任何其他觸發器一起組合使用。
`boundary`	string \| element	`'clippingParents'`	彈出提示框的 overflow constraint boundary (僅適用於 Popper 的 preventOverflow modifier)。在預設情況下，它是 `'clippingParents'` 並且可以接受 HTMLElement 引用 (僅通過 JavaScript)。有關更多訊息，請參閱 Popper 的 detectOverflow 文件。
`customClass`	string \| function	`''`	您也可以使用函式傳遞，單引號內包含這些額外的 class 名稱。
`sanitize`	boolean	`true`	啟用或禁用 sanitization。如果觸發 `'template'`，`'content'` 和 `'title'` 選項將被清理。請參閱我們的 JavaScript 文檔中 sanitizer section。
`allowList`	object	Default value	包含允許屬性和標籤的物件。
`sanitizeFn`	null \| function	`null`	在這裡你可以自訂清除函式。如果您更喜歡使用專用的函式庫來執行清除操作，這將會很有用。
`offset`	array \| string \| function	`[0, 8]`	彈出提示框相對於其目標的偏移量。你可以使用逗號分隔在 data 屬性中傳遞字串，例如：`data-bs-offset="10,20"` 當一個函數被用來決定偏移量時，它會被一個包含 popper 位置、引用和 popper rects 的對象作為他的第一個參數調用。觸發元素 DOM 節點作為第二個參數傳遞。該函數必須回傳一個包含兩個數字的陣列：`[skidding, distance]`. 更多詳細資訊，請參閱 Popper 的 offset 文件。
`popperConfig`	null \| object \| function	`null`	要更改 Bootstrap 的預設 Popper 配置，請參閱 Popper 的 configuration。當一個函數用於創建 Popper 配置時，它會被一個包含 Bootstrap 的預設 Popper configuration 調用。它可以幫助你使用預設配置並將其與你自己的配置合併。該函數必須為 Popper 回傳一個 configuration object。

單一彈出提示框的 Data 屬性

如上所述，可以透過 Data 屬性來指定各個彈出提示框的選項。

Using function with `popperConfig`

var popover = new bootstrap.Popover(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.

show

顯示元素的彈出提示框。 在彈出提示框實際顯示之前返回給調用者 (也就是在 shown.bs.popover 事件發生之前。) 彈出提示框會被認為是 “manual” 觸發。title 和 content 皆為空的彈出提示框將永遠不會顯示。

myPopover.show()

hide

隱藏元素的彈出提示框。 在彈出提示框實際被隱藏之前返回給調用者 (也就是在 hidden.bs.popover 事件發生之前。) 彈出提示框會被認為是 “manual” 觸發。

myPopover.hide()

toggle

切換元素的彈出提示框。在彈出提示框實際被顯示或隱藏之前返回給調用者 (也就是在 shown.bs.popover 或 hidden.bs.popover 事件發生之前。) 彈出提示框會被認為是 “manual” 觸發。

myPopover.toggle()

dispose

隱藏和銷毀一個元素的彈出提示框 (將移除在 DOM 元素上儲存的資料。) 被委派的彈出提示框 (使用 the selector option 創建) 不能在後代觸發元素上單獨銷毀。

myPopover.dispose()

enable

使元素的彈出提示框能夠顯示。 彈出提示框預設啟用顯示

myPopover.enable()

disable

刪除顯示元素彈出框的功能。僅在彈出提示框重新啟用時，才能顯示該彈出提示框。

myPopover.disable()

toggleEnabled

切換顯示或隱藏彈出提示框功能。

myPopover.toggleEnabled()

update

更新彈出提示框的位置。

myPopover.update()

getInstance

允許您取得 DOM 元素上彈出提示框實體的靜態方法。

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

getOrCreateInstance

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

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

事件

事件類型	描述
show.bs.popover	當調用 `show` 實例方法時，此事件會立即觸發。
shown.bs.popover	當彈出提示框啟用並為使用者可見時，此事件會立即觸發。(待 CSS 轉換完成)。
hide.bs.popover	當調用 `hide`
hidden.bs.popover	當彈出提示框啟用並為不可見時，此事件會立即觸發。(待 CSS 轉換完成)。
inserted.bs.popover	當將彈出提示框加到 DOM 時，此事件在 `show.bs.popover` 後觸發。

var myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', function () {
  // do something...
})