彈出提示框（Popovers）

Bootstrap彈出提示框的文件與示例，風(fēng)格類似iOS，可加在網(wǎng)頁上的任何元素上。

On this page

概述

使用popover插件時需要注意的事項：

Popovers依靠第三方庫Popper進行定位。您必須在bootstrap.js之前包含popper.min.js，或者使用bootstrap.bundle.min.js/bootstrap.bundle.js，其中包含popper，這樣popover才能工作！
Popovers需要工具提示插件作為依賴項。
由于性能原因，popover是選擇加入的，所以您必須自己初始化它們。
長度為零的標(biāo)題和內(nèi)容值永遠(yuǎn)不會顯示popover。
指定container:'body'以避免在更復(fù)雜的組件（如輸入組、按鈕組等）中呈現(xiàn)問題。
觸發(fā)隱藏元素上的彈出窗口將不起作用。
必須在包裝器元素上觸發(fā).disabled或disabled元素的彈出窗口。
當(dāng)從環(huán)繞多行的錨點觸發(fā)時，彈出窗口將在錨點的總寬度之間居中。在a上使用.text-nowrap可避免此行為。
必須先隱藏popover，然后才能從DOM中刪除相應(yīng)的元素。
由陰影DOM中的元素，可以觸發(fā)彈出窗口。

默認(rèn)情況下，此組件使用內(nèi)置的內(nèi)容清理器，該清理器將刪除任何不明確允許的HTML元素。有關(guān)更多詳細(xì)信息，請參閱JavaScript文檔中的“消毒液”部分

此組件的動畫效果取決于“首選簡化運動媒體”查詢。請參閱我們的可訪問性文檔的簡化運動部分。

繼續(xù)閱讀一些例子，看看popover是如何工作的。

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

初始化頁面上所有popover的一種方法是通過其data-bs-toggle屬性選擇它們：

var popoverTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
return new bootstrap.Popover(popoverTriggerEl)
})

示例：使用容器選項

當(dāng)父元素上的某些樣式干擾popover時，您需要指定一個自定義容器，以便popover的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>

四個方向

我們的選擇是可用的：頂部，右側(cè)，底部，左對齊。在RTL中使用引導(dǎo)時，方向是鏡像的。

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

再一次單擊時關(guān)閉

在用戶下一次單擊不同于toggle元素的元素時，使用focus觸發(fā)器取消彈出窗口。

下一次單擊時解除所需的特定標(biāo)記

要實現(xiàn)正確的跨瀏覽器和跨平臺行為，必須使用a標(biāo)記，而不是button標(biāo)記，并且還必須包含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屬性的元素不是交互式的，這意味著用戶不能懸停或單擊它們來觸發(fā)popover（或工具提示）。作為一種解決方法，您需要從包裝器div或span觸發(fā)popover，最好使用tabindex=“0”使鍵盤可聚焦。

對于禁用的popover觸發(fā)器，您也可能更喜歡data-bs-trigger="hover focus"，這樣popover會顯示為對用戶的即時視覺反饋，因為用戶可能不希望單擊禁用的元素。

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

讓彈出提示框?qū)︽I盤與輔助技術(shù)的用戶有效

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

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

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

選項

選項可以通過數(shù)據(jù)屬性或JavaScript傳遞。對于數(shù)據(jù)屬性，將選項名稱附加到data-bs-，如data-bs-animation=“”中所示。在傳遞數(shù)據(jù)屬性時，請確保將選項名稱的case類型從camelCase更改為kebab-case。例如：不要使用數(shù)據(jù)data-bs-customClass="beautifier"，而是使用數(shù)據(jù)data-bs-custom-class="beautifier"。

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

Name	Type	Default	Description
`animation`	boolean	`true`	對popover應(yīng)用CSS淡入淡出過渡
`container`	string \| element \| false	`false`	將popover附加到特定元素。示例：container:'body'。此選項特別有用，因為它允許您將popover放在觸發(fā)元素附近的文檔流中，這將防止popover在調(diào)整窗口大小時從觸發(fā)元素中浮動。
`content`	string \| element \| function	`''`	如果數(shù)據(jù)內(nèi)容屬性不存在，則為默認(rèn)內(nèi)容值。如果給定一個函數(shù)，它將被調(diào)用，其this引用設(shè)置為popover所附加到的元素。
`delay`	number \| object	`0`	延遲顯示和隱藏popover（ms）-不適用于手動觸發(fā)器類型如果提供了數(shù)字，則對隱藏/顯示都應(yīng)用延遲對象結(jié)構(gòu)是：`delay: { "show": 500, "hide": 100 }`
`html`	boolean	`false`	在popover中插入HTML。如果為false，innerText屬性將用于將內(nèi)容插入DOM。如果您擔(dān)心XSS攻擊，請使用文本。
`placement`	string \| function	`'right'`	如何定位popover-自動\|頂部\|底部\|左側(cè)\|右側(cè)？當(dāng)指定auto時，它將動態(tài)地重新定向popover。當(dāng)一個函數(shù)用于確定位置時，調(diào)用它時，popover DOM節(jié)點是它的第一個參數(shù)，觸發(fā)元素DOM節(jié)點是它的第二個參數(shù)。此上下文設(shè)置為popover實例。
`selector`	string \| false	`false`	如果提供了選擇器，popover對象將被委托給指定的目標(biāo)。實際上，這是用來使動態(tài)HTML內(nèi)容添加popover的。請看這個和一個信息豐富的例子。
`template`	string	`'<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'`	創(chuàng)建popover時要使用的基本HTML。 opover的標(biāo)題將被注入到.popover頭中。彈出提示框的content將被注入到.popover-body中。 `.popover-arrow` 將成為彈出提示框的箭頭。最外層的元素必須有.popover這個class。
`title`	string \| element \| function	`''`	如果標(biāo)題屬性不存在，則為默認(rèn)標(biāo)題值。如果給定一個函數(shù)，它將被調(diào)用，其this引用設(shè)置為popover所附加到的元素。
`trigger`	string	`'click'`	如何觸發(fā)彈出窗口-單擊\|懸停\|聚焦\|手動。您可以傳遞多個觸發(fā)器；用空格隔開。手動不能與任何其他觸發(fā)器組合。
`fallbackPlacements`	array	`['top', 'right', 'bottom', 'left']`	通過提供數(shù)組中的放置列表（按優(yōu)先順序）定義回退位置。有關(guān)更多信息，請參閱波普爾的行為文檔
`boundary`	string \| element	`'clippingParents'`	opover的溢出約束邊界。默認(rèn)情況下，它是'clippingParents'，可以接受HTMLElement引用（僅限于JavaScript）。有關(guān)更多信息，請參閱波普爾的文件。
`customClass`	string \| function	`''`	在彈出窗口顯示時向其添加類。請注意，這些類將添加到模板中指定的任何類之外。要添加多個類，請用空格分隔它們：“class-1 class-2”。還可以傳遞一個函數(shù)，該函數(shù)應(yīng)返回一個包含其他類名的字符串。
`sanitize`	boolean	`true`	啟用或禁用消毒。如果激活“模板”，“內(nèi)容”和“標(biāo)題”選項將被清除。請參閱我們的JavaScript文檔中的消毒劑部分。
`allowList`	object	Default value	包含允許的屬性和標(biāo)記的對象
`sanitizeFn`	null \| function	`null`	在這里，您可以提供您自己的消毒功能。如果您喜歡使用專用的庫來執(zhí)行清理，這將非常有用。
`offset`	array \| string \| function	`[0, 8]`	popover相對于其目標(biāo)的偏移量。您可以用逗號分隔的值在數(shù)據(jù)屬性中傳遞字符串，例如：data bs offset=“10,20” 當(dāng)一個函數(shù)用于確定偏移量時，調(diào)用它的第一個參數(shù)是包含popper放置、引用和popper rects的對象。觸發(fā)元素DOM node作為第二個參數(shù)傳遞。函數(shù)必須返回一個包含兩個數(shù)字的數(shù)組：[滑動，距離]。 `[滑動, 距離]`. 有關(guān)更多信息，請參閱波普爾的抵銷單。 offset docs.
`popperConfig`	null \| object \| function	`null`	要更改引導(dǎo)的默認(rèn)Popper配置，請參閱Popper的配置。 . 當(dāng)一個函數(shù)被用來創(chuàng)建Popper配置時，它被一個包含引導(dǎo)的默認(rèn)Popper配置的對象調(diào)用。它可以幫助您使用默認(rèn)配置并將其與您自己的配置合并。函數(shù)必須返回Popper的配置對象。

單個popover的數(shù)據(jù)屬性

也可以通過使用數(shù)據(jù)屬性來指定各個popover的選項，如上所述。

將函數(shù)與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.

顯示

顯示元素的popover。在實際顯示popover之前（即在show.bs.popover事件發(fā)生之前）返回調(diào)用方。這被認(rèn)為是popover的“手動”觸發(fā)。標(biāo)題和內(nèi)容均為零長度的彈出窗口永遠(yuǎn)不會顯示。

myPopover.show()

隱藏

隱藏元素的彈出提示框。在彈出提示框?qū)嶋H被隱藏之前返回給調(diào)用者（也就是在hidden.bs.popover事件發(fā)生之前。）彈出提示框會被認(rèn)為是“manual”觸發(fā)。

myPopover.hide()

切換

切換元素的彈出提示框。在彈出提示框?qū)嶋H被顯示或隱藏之前返回給調(diào)用者（也就是在shown.bs.popover或hidden.bs.popover事件發(fā)生之前。）彈出提示框會被認(rèn)為是“manual”觸發(fā)。

myPopover.toggle()

銷毀

隱藏和銷毀一個元素的彈出提示框（將移除在DOM元素上儲存的數(shù)據(jù)。）被委派的彈出提示框（使用the selector option創(chuàng)建）不能在后代觸發(fā)元素上單獨銷毀。

myPopover.dispose()

可用

使元素的彈出提示框能夠顯示。彈出提示框預(yù)設(shè)啟用顯示。

myPopover.enable()

禁用

取消顯示元素的popover的功能。只有重新啟用時才能顯示popover。

myPopover.disable()

切換可用

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

myPopover.toggleEnabled()

更新

更新彈出提示框的位置。

myPopover.update()

獲取實例

允許您取得DOM元素上彈出提示框?qū)嶓w的靜態(tài)方法。

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

事件

Event type	Description
show.bs.popover	當(dāng)調(diào)用show實例方法時，此事件會立即觸發(fā)。
shown.bs.popover	當(dāng)彈出提示框啟用并為使用者可見時，此事件會立即觸發(fā)。（待CSS轉(zhuǎn)換完成）。
hide.bs.popover	調(diào)用hide實例方法后，將立即觸發(fā)此事件。
hidden.bs.popover	當(dāng)彈出提示框啟用并為不可見時，此事件會立即觸發(fā)。（待CSS轉(zhuǎn)換完成）。
inserted.bs.popover	當(dāng)將彈出提示框加到DOM時，此事件在show.bs.popover后觸發(fā)。

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