in English

約夏克布丁

將 Bootstrap 彈出框（如 iOS 中的彈出框）添加到您網站上的任何元素的文檔和示例。

在本頁面

概述

使用 popover 插件時要知道的事情：

Popovers 依賴 3rd 方庫Popper進行定位。您必須在 bootstrap.js 之前包含popper.min.js或使用bootstrap.bundle.min.js/bootstrap.bundle.js其中包含 Popper 才能使彈出框工作！
彈出框需要工具提示插件作為依賴項。
出於性能原因，彈出框是可選的，因此您必須自己初始化它們。
零長度title和content值永遠不會顯示彈出框。
指定container: 'body'以避免在更複雜的組件（如我們的輸入組、按鈕組等）中出現渲染問題。
在隱藏元素上觸發彈出框將不起作用。
.disabledor元素的彈出框disabled必須在包裝元素上觸發。
當從跨越多行的錨點觸發時，彈出框將在錨點的整體寬度之間居中。.text-nowrap在你的 s 上使用<a>以避免這種行為。
在從 DOM 中刪除其相應元素之前，必須隱藏彈出框。
可以通過 shadow DOM 中的元素觸發彈出框。

默認情況下，該組件使用內置的內容清理器，它會去除任何未明確允許的 HTML 元素。有關更多詳細信息，請參閱我們的 JavaScript 文檔中的 sanitizer 部分。

該組件的動畫效果依賴於 prefers-reduced-motion媒體查詢。請參閱我們可訪問性文檔的減少運動部分。

繼續閱讀以了解彈出框如何與一些示例一起使用。

示例：在任何地方啟用彈出框

初始化頁面上所有彈出框的一種方法是通過它們的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>

四個方向

有四個選項可用：上對齊、右對齊、下對齊和左對齊。在 RTL 中使用 Bootstrap 時會鏡像方向。

<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屬性。

可關閉的彈出框

<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屬性的元素不是交互式的，這意味著用戶無法懸停或單擊它們來觸發彈出框（或工具提示）。作為一種解決方法，您需要從包裝器觸發彈出框，<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>

薩斯

變量

$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)

使彈出框適用於鍵盤和輔助技術用戶

要允許鍵盤用戶激活您的彈出框，您應該只將它們添加到傳統上可通過鍵盤聚焦和交互的 HTML 元素（例如鍊接或表單控件）。儘管可以通過添加屬性使任意 HTML 元素（例如<span>s）成為焦點tabindex="0"，但這會為鍵盤用戶在非交互式元素上添加可能令人討厭和令人困惑的製表位，並且大多數輔助技術目前不會在這種情況下宣布彈出框的內容. 此外，不要僅僅依靠hover作為彈出框的觸發器，因為這將使鍵盤用戶無法觸發它們。

雖然您可以使用該選項在彈出窗口中插入豐富的結構化 HTML html，但我們強烈建議您避免添加過多的內容。彈出框當前的工作方式是，一旦顯示，它們的內容就會與具有aria-describedby屬性的觸發器元素相關聯。因此，彈出框的全部內容將作為一個不間斷的長流向輔助技術用戶公佈。

此外，雖然還可以在彈出框中包含交互式控件（例如表單元素或鏈接）（通過將這些元素添加到allowList允許的屬性和標籤中），但請注意，當前彈出框不管理鍵盤焦點順序。當鍵盤用戶打開一個彈出框時，焦點仍然在觸發元素上，並且由於彈出框通常不會立即跟隨文檔結構中的觸發器，因此無法保證向前/按下TAB會將鍵盤用戶移動到彈出框本身。簡而言之，簡單地將交互式控件添加到彈出框可能會使鍵盤用戶和輔助技術用戶無法訪問/無法使用這些控件，或者至少會導致不合邏輯的整體焦點順序。在這些情況下，請考慮改用模態對話框。

選項

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

請注意，出於安全原因 sanitize，不能使用數據屬性提供 sanitizeFn、和選項。allowList

姓名	類型	默認	描述
`animation`	布爾值	`true`	對彈出框應用 CSS 淡入淡出過渡
`container`	字符串 \| 元素 \| 錯誤的	`false`	將彈出框附加到特定元素。示例：`container: 'body'`。此選項特別有用，因為它允許您將彈出框定位在靠近觸發元素的文檔流中 - 這將防止彈出框在窗口調整大小期間從觸發元素浮動。
`content`	字符串 \| 元素 \| 功能	`''`	`data-bs-content`如果屬性不存在，則默認內容值。如果給定了一個函數，它將被調用，並將其`this`引用設置為彈出框附加到的元素。
`delay`	號碼 \| 目的	`0`	延遲顯示和隱藏彈出框（毫秒） - 不適用於手動觸發類型如果提供了一個數字，延遲將應用於隱藏/顯示對象結構為：`delay: { "show": 500, "hide": 100 }`
`html`	布爾值	`false`	將 HTML 插入彈出框。如果為 false，`innerText`屬性將用於將內容插入 DOM。如果您擔心 XSS 攻擊，請使用文本。
`placement`	字符串 \| 功能	`'right'`	如何定位彈出框 - 自動 \| 頂部 \| 底部 \| 離開 \| 正確的。指定時`auto`，它將動態地重新定向彈出框。當一個函數用於確定位置時，它會以彈出框 DOM 節點作為其第一個參數，觸發元素 DOM 節點作為其第二個參數來調用。`this`上下文設置為彈出框實例。
`selector`	字符串 \| 錯誤的	`false`	如果提供了選擇器，彈出框對象將被委託給指定的目標。在實踐中，這用於啟用動態 HTML 內容以添加彈出框。請參閱this和一個內容豐富的示例。
`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`類。
`title`	字符串 \| 元素 \| 功能	`''`	`title`如果屬性不存在，則默認標題值。如果給定了一個函數，它將被調用，並將其`this`引用設置為彈出框附加到的元素。
`trigger`	細繩	`'click'`	彈出框是如何觸發的 - 點擊 \| 懸停 \| 焦點 \| 手動的。您可以傳遞多個觸發器；用空格分隔它們。`manual`不能與任何其他觸發器結合使用。
`fallbackPlacements`	大批	`['top', 'right', 'bottom', 'left']`	通過提供數組中的展示位置列表（按優先順序）來定義後備展示位置。有關更多信息，請參閱 Popper 的行為文檔
`boundary`	字符串 \| 元素	`'clippingParents'`	popover 的溢出約束邊界（僅適用於 Popper 的 preventOverflow 修飾符）。默認情況下，它`'clippingParents'`可以接受 HTMLElement 引用（僅通過 JavaScript）。有關更多信息，請參閱 Popper 的detectOverflow 文檔。
`customClass`	字符串 \| 功能	`''`	顯示時將類添加到彈出框。請注意，除了模板中指定的任何類之外，還將添加這些類。要添加多個類，請用空格分隔它們：`'class-1 class-2'`. 您還可以傳遞一個函數，該函數應返回包含其他類名的單個字符串。
`sanitize`	布爾值	`true`	啟用或禁用清理。如果激活`'template'`，選項將被清理`'content'`。`'title'`請參閱我們的 JavaScript 文檔中的消毒劑部分。
`allowList`	目的	默認值	包含允許的屬性和標籤的對象
`sanitizeFn`	空 \| 功能	`null`	在這裡，您可以提供自己的消毒功能。如果您更喜歡使用專用庫來執行清理，這會很有用。
`offset`	數組 \| 字符串 \| 功能	`[0, 8]`	彈出框相對於其目標的偏移量。您可以使用逗號分隔值在數據屬性中傳遞字符串，例如：`data-bs-offset="10,20"` 當一個函數用於確定偏移量時，調用它時會使用一個包含 popper 放置、引用和 popper rects 作為其第一個參數的對象。觸發元素 DOM 節點作為第二個參數傳遞。該函數必須返回一個包含兩個數字的數組：.`[skidding, distance]` 有關更多信息，請參閱 Popper 的偏移量文檔。
`popperConfig`	空 \| 對象 \| 功能	`null`	要更改 Bootstrap 的默認 Popper 配置，請參閱Popper 的配置。當一個函數用於創建 Popper 配置時，它會被一個包含 Bootstrap 的默認 Popper 配置的對象調用。它可以幫助您使用默認設置並將其與您自己的配置合併。該函數必須為 Popper 返回一個配置對象。

單個彈出框的數據屬性

如上所述，可以通過使用數據屬性來指定單個彈出框的選項。

使用函數`popperConfig`

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

方法

異步方法和轉換

所有 API 方法都是異步的並開始一個轉換。他們在轉換開始但在結束之前立即返回給調用者。此外，過渡組件上的方法調用將被忽略。

有關更多信息，請參閱我們的 JavaScript 文檔。

節目

顯示元素的彈出框。在彈出框實際顯示之前（即在事件發生之前）返回給調用者。shown.bs.popover這被認為是彈出框的“手動”觸發。標題和內容都為零長度的彈出框永遠不會顯示。

myPopover.show()

隱藏

隱藏元素的彈出框。在彈出框實際上被隱藏之前（即在事件發生之前）返回給調用者。hidden.bs.popover這被認為是彈出框的“手動”觸發。

myPopover.hide()

切換

切換元素的彈出框。在彈出框實際顯示或隱藏之前（即在or事件發生之前）返回給調用者。這被認為是彈出框的“手動”觸發。shown.bs.popoverhidden.bs.popover

myPopover.toggle()

處置

隱藏和銷毀元素的彈出框（刪除 DOM 元素上存儲的數據）。使用委託（使用選項創建）的selector彈出框不能在後代觸發器元素上單獨銷毀。

myPopover.dispose()

使能夠

使元素的彈出框能夠顯示。彈出框默認啟用。

myPopover.enable()

禁用

移除顯示元素彈出框的能力。只有重新啟用彈出框才能顯示。

myPopover.disable()

切換啟用

切換元素的彈出框是否顯示或隱藏。

myPopover.toggleEnabled()

更新

更新元素彈出框的位置。

myPopover.update()

獲取實例

允許您獲取與 DOM 元素關聯的彈出框實例的靜態方法

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

獲取或創建實例

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

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

活動

事件類型	描述
show.bs.popover	`show`調用實例方法時立即觸發此事件。
顯示的.bs.popover	當彈出框對用戶可見時觸發此事件（將等待 CSS 轉換完成）。
hide.bs.popover	`hide`調用實例方法時立即觸發此事件。
hidden.bs.popover	當彈出窗口完成對用戶隱藏時觸發此事件（將等待 CSS 轉換完成）。
插入的.bs.popover	該事件`show.bs.popover`在彈出框模板添加到 DOM 後觸發。

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