跳到主要內容 跳到文檔導航
Check
in English

約夏克布丁

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

在本頁面

概述

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

  • Popovers 依賴第三方庫Popper進行定位。您必須在之前包含popper.min.jsbootstrap.js，或者使用bootstrap.bundle.min.js包含 Popper 的一個。
  • 彈出框需要彈出框插件作為依賴項。
  • 出於性能原因，彈出框是可選的，因此您必須自己初始化它們。
  • 零長度title和content值永遠不會顯示彈出框。
  • 指定container: 'body'以避免在更複雜的組件（如我們的輸入組、按鈕組等）中出現渲染問題。
  • 在隱藏元素上觸發彈出框將不起作用。
  • .disabledor元素的彈出框disabled必須在包裝元素上觸發。
  • 當從跨越多行的錨點觸發時，彈出框將在錨點的整體寬度之間居中。.text-nowrap在你的 s 上使用<a>以避免這種行為。
  • 在從 DOM 中刪除其相應元素之前，必須隱藏彈出框。
  • 可以通過 shadow DOM 中的元素觸發彈出框。
默認情況下，該組件使用內置的內容清理器，它會去除任何未明確允許的 HTML 元素。有關更多詳細信息 ，請參閱 我們的 JavaScript 文檔中的 sanitizer 部分。
該組件的動畫效果依賴於 prefers-reduced-motion媒體查詢。請參閱 我們可訪問性文檔的減少運動部分。

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

例子

啟用彈出框

如上所述，您必須先初始化彈出框，然後才能使用它們。初始化頁面上所有彈出框的一種方法是通過它們的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。

隨意使用 title或 data-bs-title在您的 HTML 中使用。使用時 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 變量。

.custom-popover {
  --bs-popover-max-width: 200px;
  --bs-popover-border-color: var(--bs-primary);
  --bs-popover-header-bg: var(--bs-primary);
  --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觸發器在用戶下次單擊與切換元素不同的元素時關閉彈出框。

下次單擊時關閉所需的特定標記

對於正確的跨瀏覽器和跨平台行為，您必須使用<a>標籤，而不是<button>標籤，並且您還必須包含一個tabindex屬性。

可關閉的彈出框
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 變量方法的一部分，彈出框現在使用本地 CSS 變量.popover來增強實時自定義。CSS 變量的值是通過 Sass 設置的，因此仍然支持 Sass 自定義。

  --#{$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 變量

$popover-font-size:                 $font-size-sm;
$popover-bg:                        $white;
$popover-max-width:                 276px;
$popover-border-width:              $border-width;
$popover-border-color:              var(--#{$prefix}border-color-translucent);
$popover-border-radius:             $border-radius-lg;
$popover-inner-border-radius:       subtract($popover-border-radius, $popover-border-width);
$popover-box-shadow:                $box-shadow;

$popover-header-font-size:          $font-size-base;
$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;

用法

通過 JavaScript 啟用彈出框：

const exampleEl = document.getElementById('example')
const 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="{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並且單獨的數據屬性將覆蓋給定的值 on data-bs-config。此外，現有數據屬性能夠容納 JSON 值，例如data-bs-delay='{"show":0,"hide":150}'.

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

方法 描述
disable 移除顯示元素彈出框的能力。只有重新啟用彈出框才能顯示。
dispose 隱藏和銷毀元素的彈出框（刪除 DOM 元素上存儲的數據）。使用委託（使用選項創建）的selector彈出框不能在後代觸發器元素上單獨銷毀。
enable 使元素的彈出框能夠顯示。彈出框默認啟用。
getInstance 允許您獲取與 DOM 元素關聯的彈出框實例的靜態方法。
getOrCreateInstance 靜態方法，允許您獲取與 DOM 元素關聯的 popover 實例，或創建一個新的實例以防它未初始化。
hide 隱藏元素的彈出框。在彈出框實際上被隱藏之前（即在事件發生之前）返回給調用者。hidden.bs.popover這被認為是彈出框的“手動”觸發。
setContent 提供一種在初始化後更改彈出框內容的方法。
show 顯示元素的彈出框。在彈出框實際顯示之前（即在事件發生之前）返回給調用者。shown.bs.popover這被認為是彈出框的“手動”觸發。標題和內容都為零長度的彈出框永遠不會顯示。
toggle 切換元素的彈出框。在彈出框實際顯示或隱藏之前（即在or事件發生之前）返回給調用者。這被認為是彈出框的“手動”觸發。shown.bs.popoverhidden.bs.popover
toggleEnabled 切換元素的彈出框是否顯示或隱藏。
update 更新元素彈出框的位置。 
// getOrCreateInstance example
const popover = bootstrap.Popover.getOrCreateInstance('#example') // Returns a Bootstrap popover instance

// setContent example
myPopover.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 該事件show.bs.popover在彈出框模板添加到 DOM 後觸發。
show.bs.popover show調用實例方法時立即觸發此事件。
shown.bs.popover 當彈出框對用戶可見時觸發此事件（將等待 CSS 轉換完成）。 
const myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', () => {
  // do something...
})