在 GitHub 上檢視

彈出視窗

文件和範例，用於將 Bootstrap 彈出視窗（例如在 iOS 中找到的）新增至您網站上的任何元素。

概觀

使用彈出視窗外掛程式時應注意的事項

  • 彈出視窗仰賴第三方程式庫 Popper 來定位。您必須在 bootstrap.js 之前包含 popper.min.js，或使用包含 Popper 的 bootstrap.bundle.min.js / bootstrap.bundle.js，才能讓彈出視窗運作！
  • 彈出框需要 工具提示外掛程式 作為相依性。
  • 如果您從原始碼建置我們的 JavaScript，它 需要 util.js。
  • 彈出框出於效能原因而採用加入式，因此您必須自行初始化它們。
  • 長度為零的 title 和 content 值永遠不會顯示彈出框。
  • 指定 container: 'body' 以避免在較複雜的元件（例如我們的輸入群組、按鈕群組等）中產生顯示問題。
  • 在隱藏的元素上觸發彈出框不會運作。
  • .disabled 或 disabled 元素的彈出框必須在包裝元素上觸發。
  • 當從跨多行的錨點觸發時，彈出框會置中於錨點的整體寬度之間。在您的 <a> 上使用 .text-nowrap 以避免這種行為。
  • 彈出框必須在對應的元素從 DOM 中移除之前隱藏。
  • 彈出框可以透過陰影 DOM 中的元素觸發。
預設情況下，此元件使用內建的內容消毒程式，它會移除任何未明確允許的 HTML 元素。請參閱我們的 JavaScript 文件中的消毒程式部分 以取得更多詳細資訊。
此元件的動畫效果取決於 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 元素（例如連結或表單控制項）。儘管可以透過新增 tabindex="0" 屬性讓任意的 HTML 元素（例如 <span>）可以對焦，但這會在非互動元素上新增可能會造成困擾和混淆的標籤停駐點，而且目前大多數輔助技術不會在這種情況下宣布提示框的內容。此外，請勿僅依賴 hover 作為提示框的觸發器，因為這會讓鍵盤使用者無法觸發它們。

雖然您可以使用 html 選項在提示框中插入豐富的結構化 HTML，但我們強烈建議您避免新增過多的內容。提示框目前運作的方式是，一旦顯示，它們的內容就會透過 aria-describedby 屬性與觸發元素連結。因此，提示框的全部內容會以一個冗長、不間斷的串流方式宣布給輔助技術使用者。

此外，雖然也可以在提示框中包含互動控制項（例如表單元素或連結）（透過將這些元素新增到 whiteList 或允許的屬性和標籤），但請注意，目前提示框不管理鍵盤對焦順序。當鍵盤使用者開啟提示框時，對焦會停留在觸發元素上，而且由於提示框通常不會立即在文件結構中緊接在觸發元素之後，因此無法保證向前移動/按下 TAB 會讓鍵盤使用者移動到提示框本身。簡而言之，僅將互動控制項新增到提示框很可能會讓這些控制項對鍵盤使用者和輔助技術使用者無法使用/無法觸及，或至少會造成不合理的整體對焦順序。在這些情況下，請考慮改用模式對話方塊。

選項

選項可以透過資料屬性或 JavaScript 傳遞。對於資料屬性，請將選項名稱附加到 data-，例如 data-animation=""。

請注意，基於安全性考量，sanitize、sanitizeFn 和 whiteList 選項無法使用資料屬性提供。
名稱 類型 預設值 說明
動畫 布林值 真 對彈出視窗套用 CSS 淡入淡出轉場
容器 字串 | 元素 | false false

將彈出視窗附加到特定元素。範例：container: 'body'。此選項特別實用，因為它允許您將彈出視窗定位在觸發元素附近的文檔流程中，這將防止彈出視窗在視窗調整大小時從觸發元素中浮出。
內容 字串 | 元素 | 函式 ''

如果沒有 data-content 屬性，預設內容值。

如果給定函式，它將使用其 this 參考設定為附加彈出視窗的元素來呼叫。
延遲 數字 | 物件 0

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

如果提供數字，則延遲會套用於隱藏/顯示

物件結構為：delay: { "show": 500, "hide": 100 }
html 布林值 false 將 HTML 插入彈出視窗。如果為 false，jQuery 的 text 方法將用於將內容插入 DOM。如果您擔心 XSS 攻擊，請使用文字。
放置 字串 | 函式 'right'

如何定位彈出視窗 - 自動 | 上方 | 下方 | 左方 | 右方。
當指定 auto 時，它將動態重新調整彈出視窗的方向。

當使用函式來確定放置時，它會以彈出視窗 DOM 節點作為其第一個引數，並以觸發元素 DOM 節點作為其第二個引數來呼叫。this 內容設定為彈出視窗實例。
選取器 字串 | false false 如果提供選取器，彈出視窗物件將委派給指定的目標。在實務上，這用於啟用動態 HTML 內容以新增彈出視窗。請參閱 此 和 一個有用的範例。
範本 字串 '<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 參考設定為附加彈出視窗的元素來呼叫。
觸發 字串 'click' 彈出視窗觸發方式 - 按一下 | 懸停 | 聚焦 | 手動。您可以傳遞多個觸發器；用空格分隔。手動不能與任何其他觸發器結合使用。
偏移 數字 | 字串 0 彈出視窗相對於其目標的偏移。如需更多資訊，請參閱 Popper 的 偏移文件。
備用位置 字串 | 陣列 '翻轉' 允許指定 Popper 在備用時將使用哪個位置。如需更多資訊，請參閱 Popper 的 行為文件
自訂類別 字串 | 函式 ''

在顯示彈出視窗時，將類別新增到彈出視窗。請注意，這些類別將新增到範本中指定的任何類別中。若要新增多個類別，請用空格分隔：'a b'。

您也可以傳遞一個函式，該函式應傳回包含其他類別名稱的單一字串。
邊界 字串 | 元素 'scrollParent' 彈出視窗的溢位約束邊界。接受 'viewport'、'window'、'scrollParent' 的值，或 HTMLElement 參考 (僅限 JavaScript)。如需更多資訊，請參閱 Popper 的 preventOverflow 文件。
清除 布林值 真 啟用或停用清除。如果啟用 '範本'、'內容' 和 '標題' 選項將會清除。請參閱 JavaScript 文件中的清除區段。
白名單 物件 預設值 包含允許的屬性和標籤的物件
清除函式 null | 函式 null 您可以在這裡提供自己的清除函式。如果您偏好使用專用函式庫來執行清除，這會很有用。
Popper 設定 null | 物件 null 若要變更 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')

切換元素的浮動提示。在浮動提示實際顯示或隱藏之前傳回呼叫方（即在 shown.bs.popover 或 hidden.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 執行個體方法時，此事件會立即觸發。
shown.bs.popover 當浮動提示對使用者顯示時，此事件會觸發（會等待 CSS 轉場完成）。
hide.bs.popover 當呼叫 hide 執行個體方法時，此事件會立即觸發。
hidden.bs.popover 當浮動提示完成對使用者隱藏時，此事件會觸發（會等待 CSS 轉場完成）。
inserted.bs.popover 當浮動提示範本新增至 DOM 時，此事件會在 show.bs.popover 事件後觸發。 
$('#myPopover').on('hidden.bs.popover', function () {
  // do something...
})