跳至主要內容 跳至文件導覽
View on GitHub

彈出提示框（Popovers）

為您網站上的任何元素加入 Bootstrap 彈出提示框的文件與範例，類似於 iOS 中的效果。

本頁內容

概覽（Overview）

使用彈出提示框外掛程式時需要了解的事項：

  • 彈出提示框依賴第三方函式庫 Popper 進行定位。您必須在 bootstrap.js 之前引入 popper.min.js，或使用包含 Popper 的 bootstrap.bundle.min.js。
  • 彈出提示框需要彈出提示框外掛程式作為依賴項。
  • 基於效能考量，彈出提示框是選擇性啟用的，所以您必須自己初始化它們。
  • 長度為零的 title 和 content 值永遠不會顯示彈出提示框。
  • 指定 container: 'body' 以避免在更複雜的元件（如我們的輸入群組、按鈕群組等）中出現渲染問題。
  • 在隱藏元素上觸發彈出提示框不會有效果。
  • .disabled 或 disabled 元素的彈出提示框必須在包裹元素上觸發。
  • 當從跨越多行的錨點觸發時，彈出提示框將在錨點的整體寬度之間置中。在您的 <a> 上使用 .text-nowrap 以避免此行為。
  • 在對應元素從 DOM 中移除之前，必須先隱藏彈出提示框。
  • 彈出提示框可以透過 shadow DOM 內部的元素觸發。

預設情況下，此元件使用內建的內容清理器，它會移除任何未明確允許的 HTML 元素。請參閱我們 JavaScript 文件中的清理器章節以獲取更多詳細資訊。

此元件的動畫效果取決於 prefers-reduced-motion 媒體查詢。請參閱我們無障礙文件中的減少動態效果章節。

繼續閱讀以透過一些範例了解彈出提示框的運作方式。

範例（Examples）

啟用彈出提示框（Enable popovers）

如上所述，您必須先初始化彈出提示框才能使用它們。初始化頁面上所有彈出提示框的一種方法是透過其 data-bs-toggle 屬性選擇它們，如下所示：

const popoverTriggerList = document.querySelectorAll('[data-bs-toggle="popover"]')
const popoverList = [...popoverTriggerList].map(popoverTriggerEl => new bootstrap.Popover(popoverTriggerEl))

即時示範（Live demo）

我們使用類似上述程式碼片段的 JavaScript 來渲染以下即時彈出提示框。標題透過 data-bs-title 設定，內文內容透過 data-bs-content 設定。

您可以在 HTML 中自由使用 title 或 data-bs-title。當使用 title 時，Popper 會在元素渲染時自動將其替換為 data-bs-title。

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

四個方向（Four directions）

有四個選項可用：top、right、bottom 和 left。在 RTL 模式下使用 Bootstrap 時，方向會鏡像。設定 data-bs-placement 來改變方向。

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

自訂 container（Custom container）

當父元素上的某些樣式與彈出提示框互相干擾時，您會想要指定自訂的 container，讓彈出提示框的 HTML 出現在該元素內。這在響應式表格、輸入群組等情況中很常見。

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

另一個您想要設定明確自訂 container 的情況是互動視窗內的彈出提示框，以確保彈出提示框本身附加到互動視窗。這對於包含互動元素的彈出提示框特別重要——互動視窗會捕捉焦點，所以除非彈出提示框是互動視窗的子元素，否則使用者將無法聚焦或啟用這些互動元素。

const popover = new bootstrap.Popover('.example-popover', {
  container: '.modal-body'
})

自訂彈出提示框（Custom popovers）

Added in v5.2.0

您可以使用 CSS 變數自訂彈出提示框的外觀。我們使用 data-bs-custom-class="custom-popover" 設定自訂類別來限定我們的自訂外觀範圍，並用它來覆寫一些區域 CSS 變數。

site/src/scss/_component-examples.scss 
.custom-popover {
  --bs-popover-max-width: 200px;
  --bs-popover-border-color: var(--bd-violet-bg);
  --bs-popover-header-bg: var(--bd-violet-bg);
  --bs-popover-header-color: var(--bs-white);
  --bs-popover-body-padding-x: 1rem;
  --bs-popover-body-padding-y: .5rem;
}
html 
<button type="button" class="btn btn-secondary"
        data-bs-toggle="popover" data-bs-placement="right"
        data-bs-custom-class="custom-popover"
        data-bs-title="Custom popover"
        data-bs-content="This popover is themed via CSS variables.">
  Custom popover
</button>

下次點擊時關閉（Dismiss on next click）

使用 focus 觸發器，在使用者下次點擊切換元素以外的元素時關閉彈出提示框。

下次點擊時關閉需要特定的 HTML 才能確保跨瀏覽器和跨平台的正確行為。 您只能使用 <a> 元素，而不是 <button>，並且必須包含 tabindex。

Dismissible popover
html 
<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" data-bs-title="Dismissible popover" data-bs-content="And here’s some amazing content. It’s very engaging. Right?">Dismissible popover</a>
const popover = new bootstrap.Popover('.popover-dismiss', {
  trigger: 'focus'
})

停用的元素（Disabled elements）

具有 disabled 屬性的元素不是互動式的，這意味著使用者無法將滑鼠懸停或點擊它們來觸發彈出提示框（或工具提示框）。作為替代方案，您會想要從包裹的 <div> 或 <span> 觸發彈出提示框，最好使用 tabindex="0" 使其可透過鍵盤聚焦。

對於停用的彈出提示框觸發器，您可能也更喜歡使用 data-bs-trigger="hover focus"，這樣彈出提示框就會作為即時視覺回饋出現給您的使用者，因為他們可能不期望點擊停用的元素。

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

CSS

變數（Variables）

Added in v5.2.0

作為 Bootstrap 持續演進的 CSS 變數方法的一部分，彈出提示框現在在 .popover 上使用區域 CSS 變數，以增強即時自訂能力。CSS 變數的值透過 Sass 設定，因此仍然支援 Sass 自訂。

scss/_popover.scss 
--#{$prefix}popover-zindex: #{$zindex-popover};
--#{$prefix}popover-max-width: #{$popover-max-width};
@include rfs($popover-font-size, --#{$prefix}popover-font-size);
--#{$prefix}popover-bg: #{$popover-bg};
--#{$prefix}popover-border-width: #{$popover-border-width};
--#{$prefix}popover-border-color: #{$popover-border-color};
--#{$prefix}popover-border-radius: #{$popover-border-radius};
--#{$prefix}popover-inner-border-radius: #{$popover-inner-border-radius};
--#{$prefix}popover-box-shadow: #{$popover-box-shadow};
--#{$prefix}popover-header-padding-x: #{$popover-header-padding-x};
--#{$prefix}popover-header-padding-y: #{$popover-header-padding-y};
@include rfs($popover-header-font-size, --#{$prefix}popover-header-font-size);
--#{$prefix}popover-header-color: #{$popover-header-color};
--#{$prefix}popover-header-bg: #{$popover-header-bg};
--#{$prefix}popover-body-padding-x: #{$popover-body-padding-x};
--#{$prefix}popover-body-padding-y: #{$popover-body-padding-y};
--#{$prefix}popover-body-color: #{$popover-body-color};
--#{$prefix}popover-arrow-width: #{$popover-arrow-width};
--#{$prefix}popover-arrow-height: #{$popover-arrow-height};
--#{$prefix}popover-arrow-border: var(--#{$prefix}popover-border-color);

Sass 變數（Sass variables）

scss/_variables.scss 
$popover-font-size:                 $font-size-sm;
$popover-bg:                        var(--#{$prefix}body-bg);
$popover-max-width:                 276px;
$popover-border-width:              var(--#{$prefix}border-width);
$popover-border-color:              var(--#{$prefix}border-color-translucent);
$popover-border-radius:             var(--#{$prefix}border-radius-lg);
$popover-inner-border-radius:       calc(#{$popover-border-radius} - #{$popover-border-width}); // stylelint-disable-line function-disallowed-list
$popover-box-shadow:                var(--#{$prefix}box-shadow);

$popover-header-font-size:          $font-size-base;
$popover-header-bg:                 var(--#{$prefix}secondary-bg);
$popover-header-color:              $headings-color;
$popover-header-padding-y:          .5rem;
$popover-header-padding-x:          $spacer;

$popover-body-color:                var(--#{$prefix}body-color);
$popover-body-padding-y:            $spacer;
$popover-body-padding-x:            $spacer;

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

使用方式（Usage）

透過 JavaScript 啟用彈出提示框：

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

保持彈出提示框對鍵盤和輔助技術使用者的可存取性，只將它們加入到傳統上可透過鍵盤聚焦且具互動性的 HTML 元素（如連結或表單控制項）。雖然可以透過加入 tabindex="0" 使其他 HTML 元素可聚焦，但這可能會在非互動元素上為鍵盤使用者造成煩人且令人困惑的 Tab 停靠點，而且大多數輔助技術目前在這種情況下不會宣告彈出提示框。此外，不要僅依賴 hover 作為彈出提示框的觸發器，因為這會使鍵盤使用者無法觸發它們。

避免使用 html 選項在彈出提示框中加入過多內容。一旦彈出提示框顯示，其內容會透過 aria-describedby 屬性與觸發元素綁定，導致所有彈出提示框的內容被宣告給輔助技術使用者時成為一長串不間斷的內容流。

彈出提示框不管理鍵盤焦點順序，且它們在 DOM 中的位置可能是隨機的，所以在加入互動元素（如表單或連結）時要小心，因為這可能導致不合邏輯的焦點順序，或使彈出提示框內容本身對鍵盤使用者完全無法存取。在您必須使用這些元素的情況下，請考慮改用互動視窗。

選項（Options）

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

從 Bootstrap 5.2.0 開始，所有元件都支援實驗性的保留 data 屬性 data-bs-config，可以將簡單的元件配置作為 JSON 字串存放。當元素同時具有 data-bs-config='{"delay":0, "title":123}' 和 data-bs-title="456" 屬性時，最終的 title 值將是 456，個別的 data 屬性將覆寫 data-bs-config 中給定的值。此外，現有的 data 屬性也能夠存放 JSON 值，例如 data-bs-delay='{"show":0,"hide":150}'。

最終的配置物件是 data-bs-config、data-bs- 和 js object 的合併結果，其中最後給定的鍵值對會覆寫其他的。

請注意，基於安全性原因，sanitize、sanitizeFn 和 allowList 選項無法使用 data 屬性提供。

名稱類型預設值說明
allowListobject預設值包含允許的標籤和屬性的物件。未明確允許的將被內容清理器移除。
加入此列表時請謹慎。 請參閱 OWASP 的跨網站腳本預防備忘單以獲取更多資訊。
animation布林值true對彈出提示框套用 CSS 淡入過渡效果。
boundary字串、元素'clippingParents'彈出提示框的溢位約束邊界（僅適用於 Popper 的 preventOverflow 修飾器）。預設值為 'clippingParents'，可接受 HTMLElement 參照（僅限透過 JavaScript）。更多資訊請參閱 Popper 的 detectOverflow 文件。
container字串、元素、falsefalse將彈出提示框附加到特定元素。例如：container: 'body'。此選項特別有用，因為它允許您將彈出提示框定位在文件流中靠近觸發元素的位置——這將防止彈出提示框在視窗調整大小時飄離觸發元素。
content字串、元素、函式''彈出提示框的文字內容。如果提供函式，它將以 this 參照設為彈出提示框附加到的元素來呼叫。
customClass字串、函式''在彈出提示框顯示時加入類別。請注意，這些類別將加入到範本中指定的任何類別之外。要加入多個類別，請用空格分隔：'class-1 class-2'。您也可以傳遞一個應傳回包含額外類別名稱的單一字串的函式。
delay數字、物件0顯示和隱藏彈出提示框的延遲（毫秒）——不適用於手動觸發類型。如果提供數字，延遲將同時套用於隱藏/顯示。物件結構為：delay: { "show": 500, "hide": 100 }。
fallbackPlacements字串、陣列['top', 'right', 'bottom', 'left']透過在陣列中提供位置列表（按優先順序）來定義備用位置。更多資訊請參閱 Popper 的 behavior 文件。
html布林值false允許彈出提示框中的 HTML。如果為 true，彈出提示框 title 中的 HTML 標籤將在彈出提示框中呈現。如果為 false，將使用 innerText 屬性將內容插入 DOM。處理使用者產生的輸入時，優先使用文字以防止 XSS 攻擊。
offset數字、字串、函式[0, 8]彈出提示框相對於其目標的偏移。您可以在 data 屬性中傳遞以逗號分隔值的字串，如：data-bs-offset="10,20"。當使用函式確定偏移時，它會以包含 popper 位置、參照和 popper 矩形的物件作為第一個引數來呼叫。觸發元素 DOM 節點作為第二個引數傳遞。函式必須傳回包含兩個數字的陣列：skidding、distance。更多資訊請參閱 Popper 的 offset 文件。
placement字串、函式'right'如何定位彈出提示框：auto、top、bottom、left、right。當指定 auto 時，它會動態重新調整彈出提示框的方向。當使用函式確定位置時，它會以彈出提示框 DOM 節點作為第一個引數、觸發元素 DOM 節點作為第二個引數來呼叫。this 上下文設為彈出提示框實例。
popperConfignull、物件、函式null要更改 Bootstrap 的預設 Popper 設定，請參閱 Popper 的設定。當使用函式建立 Popper 設定時，它會以包含 Bootstrap 預設 Popper 設定的物件來呼叫。這有助於您使用並合併預設設定與您自己的設定。函式必須傳回 Popper 的設定物件。
sanitize布林值true啟用內容清理。如果為 true，template、content 和 title 選項將被清理。
停用內容清理時請謹慎。 請參閱 OWASP 的跨網站腳本預防備忘單以獲取更多資訊。僅因停用內容清理而造成的漏洞不在 Bootstrap 安全模型的範圍內。
sanitizeFnnull、函式null提供替代的內容清理函式。如果您偏好使用專門的函式庫來執行清理，這會很有用。
selector字串、falsefalse如果提供選擇器，彈出提示框物件將委派到指定的目標。實際上，這用於也將彈出提示框套用到動態加入的 DOM 元素（支援 jQuery.on）。請參閱此議題和一個資訊豐富的範例。注意：title 屬性不得用作選擇器。
template字串'<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 類別和 role="tooltip"。
title字串、元素、函式''彈出提示框標題。如果提供函式，它將以 this 參照設為彈出提示框附加到的元素來呼叫。
trigger字串'click'如何觸發彈出提示框：click、hover、focus、manual。您可以傳遞多個觸發器；用空格分隔它們。'manual' 表示彈出提示框將透過 .popover('show')、.popover('hide') 和 .popover('toggle') 方法以程式方式觸發；此值不能與任何其他觸發器組合。單獨使用 'hover' 將導致無法透過鍵盤觸發的彈出提示框，只有在存在為鍵盤使用者傳達相同資訊的替代方法時才應使用。

個別彈出提示框的 data 屬性

個別彈出提示框的選項也可以透過使用 data 屬性來指定，如上所述。

使用函式與 popperConfig 

const popover = new bootstrap.Popover(element, {
  popperConfig(defaultBsPopperConfig) {
    // const newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

方法（Methods）

所有 API 方法都是非同步的，並會啟動一個過渡效果。 它們會在過渡開始後立即回傳給呼叫者，但在過渡結束之前。此外，對正在過渡中的元件進行方法呼叫將被忽略。在我們的 JavaScript 文件中了解更多。

方法說明
disable移除元素的彈出提示框顯示能力。只有在重新啟用後，彈出提示框才能顯示。
dispose隱藏並銷毀元素的彈出提示框（移除儲存在 DOM 元素上的資料）。使用委派的彈出提示框（使用selector 選項建立的）無法在後代觸發元素上單獨銷毀。
enable使元素的彈出提示框具有顯示能力。彈出提示框預設為啟用。
getInstance_靜態_方法，允許您取得與 DOM 元素關聯的彈出提示框實例。
getOrCreateInstance_靜態_方法，允許您取得與 DOM 元素關聯的彈出提示框實例，如果未初始化則建立一個新的。
hide隱藏元素的彈出提示框。在彈出提示框實際隱藏之前傳回給呼叫者（即在 hidden.bs.popover 事件發生之前）。這被視為彈出提示框的「手動」觸發。
setContent提供一種在初始化後更改彈出提示框內容的方法。
show顯示元素的彈出提示框。在彈出提示框實際顯示之前傳回給呼叫者（即在 shown.bs.popover 事件發生之前）。這被視為彈出提示框的「手動」觸發。標題和內容長度都為零的彈出提示框永遠不會顯示。
toggle切換元素的彈出提示框。在彈出提示框實際顯示或隱藏之前傳回給呼叫者（即在 shown.bs.popover 或 hidden.bs.popover 事件發生之前）。這被視為彈出提示框的「手動」觸發。
toggleEnabled切換元素的彈出提示框顯示或隱藏能力。
update更新元素的彈出提示框位置。
// getOrCreateInstance example
const popover = bootstrap.Popover.getOrCreateInstance('#example') // Returns a Bootstrap popover instance

// setContent example
popover.setContent({
  '.popover-header': 'another title',
  '.popover-body': 'another content'
})

setContent 方法接受一個 object 引數，其中每個屬性鍵是彈出提示框範本中的有效 string 選擇器，每個相關的屬性值可以是 string | element | function | null

事件（Events）

事件說明
hide.bs.popover當呼叫 hide 實例方法時立即觸發此事件。
hidden.bs.popover當彈出提示框對使用者完成隱藏時觸發此事件（會等待 CSS 過渡完成）。
inserted.bs.popover當彈出提示框範本加入到 DOM 後，在 show.bs.popover 事件之後觸發此事件。
show.bs.popover當呼叫 show 實例方法時立即觸發此事件。
shown.bs.popover當彈出提示框對使用者可見時觸發此事件（會等待 CSS 過渡完成）。
const myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', () => {
  // do something...
})