in English

約夏克布丁

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

概述

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

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

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

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

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

$(function () {
  $('[data-toggle="popover"]').popover()
})

示例：使用container選項

當父元素上的某些樣式會干擾彈出框時，您需要指定自定義樣式，container以便彈出框的 HTML 出現在該元素中。

$(function () {
  $('.example-popover').popover({
    container: 'body'
  })
})

例子

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

四個方向

有四個選項可用：上對齊、右對齊、下對齊和左對齊。

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="top" data-content="Top popover">
  Popover on top
</button>
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="right" data-content="Right popover">
  Popover on right
</button>
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="Bottom popover">
  Popover on bottom
</button>
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="left" data-content="Left popover">
  Popover on left
</button>

下次點擊關閉

使用focus觸發器在用戶下次單擊與切換元素不同的元素時關閉彈出框。

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

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

可關閉的彈出框 
<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-toggle="popover" data-trigger="focus" title="Dismissible popover" data-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>
$('.popover-dismiss').popover({
  trigger: 'focus'
})

禁用元素

具有該disabled屬性的元素不是交互式的，這意味著用戶無法懸停或單擊它們來觸發彈出框（或工具提示）。作為一種解決方法，您需要從包裝器中觸發彈出框，<div>或者<span>覆蓋pointer-events禁用元素上的 。

對於禁用的彈出框觸發器，您可能還希望data-trigger="hover"彈出框顯示為用戶的即時視覺反饋，因為他們可能不希望單擊禁用的元素。

<span class="d-inline-block" data-toggle="popover" data-content="Disabled popover">
  <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>

用法

通過 JavaScript 啟用彈出框：

$('#example').popover(options)
GPU 加速

由於 GPU 加速和修改的系統 DPI，彈出框有時在 Windows 10 設備上顯得模糊。v4 中的解決方法是根據需要在彈出窗口上禁用 GPU 加速。

建議修復：

Popper.Defaults.modifiers.computeStyle.gpuAcceleration = !(window.devicePixelRatio < 1.5 && /Win/.test(navigator.platform))

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

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

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

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

選項

選項可以通過數據屬性或 JavaScript 傳遞。對於數據屬性，將選項名稱附加到 中data-，如data-animation="".

請注意，出於安全原因 sanitize， 不能使用數據屬性提供 sanitizeFn和 選項。whiteList
姓名 類型 默認 描述
動畫 布爾值 真的 對彈出框應用 CSS 淡入淡出過渡
容器 字符串 | 元素 | 錯誤的 錯誤的

將彈出框附加到特定元素。示例：container: 'body'。此選項特別有用，因為它允許您將彈出框定位在靠近觸發元素的文檔流中 - 這將防止彈出框在窗口調整大小期間從觸發元素浮動。
內容 字符串 | 元素 | 功能 ''

data-content如果屬性不存在，則默認內容值。

如果給定了一個函數，它將被調用，並將其this引用設置為彈出框附加到的元素。
延遲 號碼 | 目的 0

延遲顯示和隱藏彈出框（毫秒） - 不適用於手動觸發類型

如果提供了一個數字，延遲將應用於隱藏/顯示

對象結構為：delay: { "show": 500, "hide": 100 }
html 布爾值 錯誤的 將 HTML 插入彈出框。如果為 false，jQuery 的text方法將用於將內容插入 DOM。如果您擔心 XSS 攻擊，請使用文本。
放置 字符串 | 功能 '正確的'

如何定位彈出框 - 自動 | 頂部 | 底部 | 離開 | 正確的。
指定時auto，它將動態地重新定向彈出框。

當一個函數用於確定位置時，它會以彈出框 DOM 節點作為其第一個參數，觸發元素 DOM 節點作為其第二個參數來調用。this上下文設置為彈出框實例。
選擇器 字符串 | 錯誤的 錯誤的 如果提供了選擇器，彈出框對象將被委託給指定的目標。在實踐中，這用於啟用動態 HTML 內容以添加彈出框。請參閱this和一個內容豐富的示例。
模板 細繩 '<div class="popover" role="tooltip"><div class="arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'

創建彈出框時要使用的基本 HTML。

彈出框title將被注入到.popover-header.

彈出框content將被注入到.popover-body.

.arrow將成為彈出框的箭頭。

最外層的包裝元素應該有.popover類。
標題 字符串 | 元素 | 功能 ''

title如果屬性不存在，則默認標題值。

如果給定了一個函數，它將被調用，並將其this引用設置為彈出框附加到的元素。
扳機 細繩 '點擊' popover是如何觸發的——點擊| 懸停 | 焦點 | 手動的。您可以傳遞多個觸發器；用空格分隔它們。manual不能與任何其他觸發器結合使用。
抵消 號碼 | 細繩 0 彈出框相對於其目標的偏移量。有關更多信息，請參閱 Popper 的偏移量文檔。
後備放置 字符串 | 大批 '翻動' 允許指定 Popper 將在回退時使用的位置。有關更多信息，請參閱 Popper 的行為文檔
自定義類 字符串 | 功能 ''

顯示時將類添加到彈出框。請注意，除了模板中指定的任何類之外，還將添加這些類。要添加多個類，請用空格分隔它們：'a b'.

您還可以傳遞一個函數，該函數應返回包含其他類名的單個字符串。
邊界 字符串 | 元素 '滾動父' 彈出框的溢出約束邊界。接受 、 、 或 HTMLElement 引用的值'viewport'（'window'僅限'scrollParent'JavaScript）。有關更多信息，請參閱 Popper 的preventOverflow 文檔。
消毒 布爾值 真的 啟用或禁用清理。如果激活'template'，選項將被清理'content'。'title'請參閱我們的 JavaScript 文檔中的消毒劑部分。
白名單 目的 默認值 包含允許的屬性和標籤的對象
sanitizeFn 空 | 功能 無效的 在這裡，您可以提供自己的消毒功能。如果您更喜歡使用專用庫來執行清理，這會很有用。
popperConfig 空 | 目的 無效的 要更改 Bootstrap 的默認 Popper 配置，請參閱Popper 的配置

單個彈出框的數據屬性

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

方法

異步方法和轉換

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

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

$().popover(options)

初始化元素集合的彈出框。

.popover('show')

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

$('#element').popover('show')

.popover('hide')

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

$('#element').popover('hide')

.popover('toggle')

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

$('#element').popover('toggle')

.popover('dispose')

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

$('#element').popover('dispose')

.popover('enable')

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

$('#element').popover('enable')

.popover('disable')

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

$('#element').popover('disable')

.popover('toggleEnabled')

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

$('#element').popover('toggleEnabled')

.popover('update')

更新元素彈出框的位置。

$('#element').popover('update')

活動

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