提示框

文件和範例，用於將 Bootstrap 提示框（例如在 iOS 中找到的提示框）新增到您網站上的任何元素。

在此頁面上

概觀

使用提示框外掛程式時要知道的事項

提示框依賴第三方程式庫 Popper 來定位。您必須在 bootstrap.js 之前包含 popper.min.js，或使用包含 Popper 的 bootstrap.bundle.min.js。
提示框需要提示框外掛程式作為依賴項。
基於效能考量，Popovers 採用選擇加入的方式，因此您必須自行初始化。
長度為 0 的 title 和 content 值永遠不會顯示 popover。
指定 container: 'body' 以避免在較複雜的元件（例如我們的輸入群組、按鈕群組等）中發生渲染問題。
對隱藏元素觸發 popover 無效。
針對 .disabled 或 disabled 元素的 popover 必須在包裝元素上觸發。
從跨多行的錨點觸發 popover 時，popover 會置中於錨點的整體寬度之間。在您的 <a> 上使用 .text-nowrap 以避免此行為。
必須在對應元素從 DOM 中移除之前隱藏 popover。
可以透過陰影 DOM 內的元素觸發 popover。

預設情況下，此元件使用內建的內容消毒程式，它會移除任何未明確允許的 HTML 元素。請參閱我們的 JavaScript 文件中的消毒程式區段以取得更多詳細資訊。

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

繼續閱讀以查看 popover 如何搭配一些範例運作。

範例

啟用 popover

如上所述，您必須在使用浮動提示之前先初始化它們。初始化頁面上所有浮動提示的一種方法是透過其 data-bs-toggle 屬性選取它們，如下所示

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

線上示範

我們使用類似於上述程式碼片段的 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>

四個方向

有四個選項可用：上方、右方、下方和左方。在 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`

當父元素上有一些樣式會干擾浮動提示時，您會想要指定一個自訂 container，以便浮動提示的 HTML 出現在該元素內部。這在回應式表格、輸入群組等中很常見。

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

您會想要設定一個明確的自訂 container 的另一個情況是對話框中的浮動提示，以確保浮動提示本身附加到對話框。這對於包含互動元素的浮動提示特別重要，對話框會鎖定焦點，因此除非浮動提示是對話框的子元素，否則使用者將無法聚焦或啟動這些互動元素。

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

自訂浮動提示

在 v5.2.0 中新增

你可以使用 CSS 變數自訂彈出視窗的外觀。我們設定一個自訂類別，其 `data-bs-custom-class="custom-popover"` 範圍為自訂外觀，並使用它來覆寫一些本機 CSS 變數。

site/assets/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>

下次按一下時關閉

使用 `focus` 觸發器，在使用者下次按一下切換元素以外的元素時關閉彈出視窗。

下次按一下時關閉需要特定的 HTML，才能有適當的跨瀏覽器和跨平台行為。你只能使用 `` 元素，不能使用 `

可關閉的彈出視窗

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` 屬性的元素不會互動，表示使用者無法將游標移到它們上面或按一下它們，以觸發彈出視窗（或工具提示）。作為解決方法，你會想要從包裝 `<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

變數

在 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 變數

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;

使用方式

透過 JavaScript 啟用浮動提示

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

讓鍵盤和輔助技術使用者可以存取浮動提示，方法是只將浮動提示新增到傳統上可以透過鍵盤對焦且具有互動性的 HTML 元素（例如連結或表單控制項）。雖然其他 HTML 元素可以透過新增 tabindex="0" 來讓它們可以對焦，但這會在非互動元素上為鍵盤使用者建立惱人和令人困惑的定位點，而且目前大多數輔助技術在這種情況下不會宣布浮動提示。此外，不要只依賴 hover 作為浮動提示的觸發器，因為這會讓鍵盤使用者無法觸發浮動提示。

避免在浮動提示中使用 html 選項新增過多內容。一旦浮動提示顯示，其內容就會透過 aria-describedby 屬性與觸發元素連結，導致輔助技術使用者會將浮動提示的所有內容宣布為一個冗長且不間斷的串流。

浮動提示不會管理鍵盤對焦順序，而且它們在 DOM 中的配置可能是隨機的，因此在新增互動元素（例如表單或連結）時要小心，因為這可能會導致不合理的對焦順序，或讓鍵盤使用者完全無法存取浮動提示內容。在必須使用這些元素的情況下，請考慮改用模式對話框。

選項

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

從 Bootstrap 5.2.0 開始，所有元件都支援一個實驗性的保留資料屬性 data-bs-config，它可以將簡單的元件組態儲存在 JSON 字串中。當一個元素具有 data-bs-config='{"delay":0, "title":123}' 和 data-bs-title="456" 屬性時，最後的 title 值將會是 456，而個別的資料屬性將會覆寫 data-bs-config 上給定的值。此外，現有的資料屬性能夠儲存 JSON 值，例如 data-bs-delay='{"show":0,"hide":150}'。

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

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

名稱	類型	預設值	說明
`allowList`	物件	預設值	包含允許的屬性和標籤的物件。
`animation`	布林值	`true`	對提示框套用 CSS 漸變轉場。
`boundary`	字串、元素	`'clippingParents'`	提示框的溢位約束邊界（僅適用於 Popper 的 preventOverflow 修改器）。預設為 `'clippingParents'`，並且可以接受一個 HTMLElement 參考（僅透過 JavaScript）。有關更多資訊，請參閱 Popper 的 detectOverflow 文件。
`container`	字串、元素、false	`false`	將彈出視窗附加到特定元素。範例：`container: 'body'`。此選項特別有用，因為它允許您將彈出視窗定位在觸發元素附近的文檔流程中，這將防止彈出視窗在視窗調整大小時遠離觸發元素。
`content`	字串、元素、函式	`''`	彈出視窗的文字內容。如果給定函式，它將以其 `this` 參考設定為附加彈出視窗的元素來呼叫。
`customClass`	字串、函式	`''`	在彈出視窗顯示時新增類別。請注意，這些類別將新增到範本中指定的任何類別中。若要新增多個類別，請用空格分隔它們：`'class-1 class-2'`。您也可以傳遞一個函式，該函式應傳回包含其他類別名稱的單一字串。
`delay`	數字、物件	`0`	延遲顯示和隱藏彈出視窗（毫秒）—不適用於手動觸發類型。如果提供數字，則延遲會套用於隱藏/顯示。物件結構為：`delay: { "show": 500, "hide": 100 }`。
`fallbackPlacements`	字串、陣列	`['top', 'right', 'bottom', 'left']`	透過在陣列中提供放置清單（依優先順序）來定義備用放置。有關更多資訊，請參閱 Popper 的行為文件。
`html`	布林值	`false`	允許在彈出視窗中使用 HTML。如果為 true，彈出視窗 `title` 中的 HTML 標籤將呈現在彈出視窗中。如果為 false，`innerText` 屬性將用於將內容插入 DOM。如果您擔心 XSS 攻擊，請使用文字。
`offset`	數字、字串、函式	`[0, 0]`	彈出視窗相對於其目標的偏移量。您可以傳遞資料屬性中的字串，並以逗號分隔值，例如：`data-bs-offset="10,20"`。當使用函式來確定偏移量時，它會以包含彈出視窗放置、參考和彈出視窗矩形作為其第一個引數的物件來呼叫。觸發元素 DOM 節點傳遞為第二個引數。函式必須傳回包含兩個數字的陣列：skidding、distance。有關更多資訊，請參閱 Popper 的 offset 文件。
`放置`	字串、函式	`'top'`	如何定位浮動提示：auto、top、bottom、left、right。當指定 `auto` 時，它會動態重新調整浮動提示的方向。當使用函數來決定放置時，會以浮動提示 DOM 節點作為第一個參數，並以觸發元素 DOM 節點作為第二個參數來呼叫它。`this` 的內容設定為浮動提示執行個體。
`popperConfig`	null、物件、函數	`null`	若要變更 Bootstrap 的預設 Popper 設定，請參閱 Popper 的設定。當使用函數建立 Popper 設定時，會呼叫包含 Bootstrap 預設 Popper 設定的物件。它有助於您使用並將預設設定與您自己的設定合併。函數必須傳回 Popper 的設定物件。
`sanitize`	布林值	`true`	啟用或停用 sanitization。如果啟用 `'template'`、`'content'` 和 `'title'` 選項將會被 sanitization。
`sanitizeFn`	null、函數	`null`	您可以在這裡提供您自己的 sanitization 函數。如果您偏好使用專門的函式庫來執行 sanitization，這會很有用。
`selector`	字串、false	`false`	如果提供 selector，浮動提示物件將會委派到指定的目標。實際上，這用於將浮動提示套用至動態新增的 DOM 元素（支援 `jQuery.on`）。請參閱此議題和一個有用的範例。注意：`title` 屬性不得用作 selector。
`template`	字串	`'<div class="popover" role="tooltip"><div class="popover-arrow"></div><div class="popover-inner"></div></div>'`	建立彈出視窗時要使用的基本 HTML。彈出視窗的 `title` 會注入到 `.popover-inner`。`.popover-arrow` 會變成彈出視窗的箭頭。最外層的包裝元素應具有 `.popover` 類別和 `role="tooltip"`。
`標題`	字串、元素、函式	`''`	彈出視窗標題。如果給定函式，它會呼叫，其 `this` 參照設定為彈出視窗附加到的元素。
`觸發器`	字串	`'hover focus'`	彈出視窗觸發方式：按一下、游標移入、焦點、手動。您可以傳遞多個觸發器；用空格分隔。`'manual'` 表示彈出視窗會透過 `.popover('show')`、`.popover('hide')` 和 `.popover('toggle')` 方法以程式化方式觸發；此值無法與任何其他觸發器結合。單獨使用 `'hover'` 會導致無法透過鍵盤觸發彈出視窗，且僅應在存在傳達相同資訊給鍵盤使用者的其他方法時使用。

個別彈出視窗的資料屬性

個別彈出視窗的選項也可以透過使用資料屬性來指定，如上所述。

與 `popperConfig` 一起使用函式

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

方法

所有 API 方法都是非同步的，而且會開始轉換。它們會在轉換開始後立即傳回呼叫者，但在轉換結束之前。此外，會略過轉換中元件的方法呼叫。在我們的 JavaScript 文件中了解更多資訊。

方法	說明
`停用`	移除元素彈出視窗顯示功能。只有在重新啟用時，彈出視窗才能顯示。
`處置`	隱藏並銷毀元素彈出視窗（移除儲存在 DOM 元素的資料）。使用委派（使用 `selector` 選項建立）的彈出視窗無法在後代觸發元素中個別銷毀。
`啟用`	讓元素彈出視窗具有顯示功能。預設啟用彈出視窗。
`getInstance`	靜態方法，可取得與 DOM 元素關聯的彈出視窗執行個體。
`getOrCreateInstance`	靜態方法，可取得與 DOM 元素關聯的彈出視窗執行個體，或在尚未初始化的情況下建立新的執行個體。
`隱藏`	隱藏元素彈出視窗。在彈出視窗實際隱藏之前傳回呼叫方（即在 `hidden.bs.popover` 事件發生之前）。這被視為彈出視窗的「手動」觸發。
`setContent`	提供一種方式，可在初始化後變更彈出視窗的內容。
`顯示`	顯示元素彈出視窗。在彈出視窗實際顯示之前傳回呼叫方（即在 `shown.bs.popover` 事件發生之前）。這被視為彈出視窗的「手動」觸發。標題和內容皆為零長度的彈出視窗永遠不會顯示。
`切換`	切換元素彈出視窗。在彈出視窗實際顯示或隱藏之前傳回呼叫方（即在 `shown.bs.popover` 或 `hidden.bs.popover` 事件發生之前）。這被視為彈出視窗的「手動」觸發。
`toggleEnabled`	切換顯示或隱藏元素彈出視窗的功能。
`更新`	更新元素浮動提示的位置。

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

事件

事件	說明
`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...
})

提示框

概觀

範例

啟用 popover

線上示範

四個方向

自訂 container

自訂浮動提示

下次按一下時關閉

已停用的元素

CSS

變數

Sass 變數

使用方式

選項

個別彈出視窗的資料屬性

與 popperConfig 一起使用函式

方法

事件

自訂 `container`

與 `popperConfig` 一起使用函式