Popover API

概念與用法

在 Web 上，一種非常常見的模式是在其他內容之上顯示內容，以吸引使用者注意特定的重要資訊或需要採取的操作。這些內容可以有不同的名稱——覆蓋層、彈出視窗、浮出控制元件、對話方塊等。在整個文件中，我們將它們稱為彈出框（popovers）。總的來說，它們可以是：

• 模態（modal），這意味著當顯示彈出框時，頁面的其餘部分將無法互動，直到彈出框以某種方式被操作（例如，做出一個重要選擇）。
• 非模態（non-modal），這意味著在顯示彈出框時，頁面的其餘部分仍然可以進行互動。

使用 Popover API 建立的彈出框始終是非模態的。如果您想建立模態彈出框，<dialog> 元素是正確的選擇。兩者之間有很大的重疊——例如，您可能希望建立一個持久的彈出框，但透過 HTML 控制它。您可以將 <dialog> 元素變成一個彈出框（<dialog popover> 是完全有效的），如果您想將彈出框控制與對話方塊語義結合起來。

Popover API 的典型用例包括使用者互動式元素，如操作選單、自定義“Toast”通知、表單元素建議、內容選擇器或教學 UI。

您可以透過兩種不同的方式建立彈出框：

• 透過一組新的 HTML 屬性。使用以下程式碼可以建立一個帶有切換按鈕的簡單彈出框：

  html

  <button popovertarget="mypopover">Toggle the popover</button>
  <div id="mypopover" popover>Popover content</div>
  

• 透過 JavaScript API。例如，HTMLElement.togglePopover() 可用於在顯示和隱藏之間切換彈出框。

還有新的事件可以響應彈出框的切換，以及用於輔助樣式化彈出框的 CSS 特性。所有新特性都列在下面。

有關使用此 API 的詳細指南，請參閱 使用 Popover API。

HTML 屬性

popover

一個全域性屬性，可將元素變成彈出框元素；接受一個彈出框狀態（"auto"、"hint" 或 "manual"）作為其值。

popovertarget

將 <button> 或 <input> 元素變成彈出框控制元件按鈕；接受要控制的彈出框元素的 ID 作為其值。

popovertargetaction

指定要對由控制元件 <button> 或 <input> 控制的彈出框元素執行的操作（"hide"、"show" 或 "toggle"）。

CSS 特性

::backdrop

::backdrop 偽元素是一個全屏元素，直接放置在彈出框元素後面，允許在需要時（例如將其模糊化）為彈出框後面的頁面內容新增效果。

:popover-open

:popover-open 偽類僅在彈出框元素處於顯示狀態時匹配它——可用於在彈出框顯示時為其設定樣式。

介面

ToggleEvent

表示一個事件，在彈出框元素的狀態在顯示和隱藏之間切換時通知使用者。它是 beforetoggle 和 toggle 事件的事件物件，當彈出框的狀態改變時，這些事件會在彈出框上觸發。

其他介面的擴充套件

例項屬性

HTMLElement.popover

透過 JavaScript 獲取和設定元素的彈出框狀態（"auto"、"hint" 或 "manual"），並可用於功能檢測。反映了 popover 全域性 HTML 屬性的值。

HTMLButtonElement.popoverTargetElement 和 HTMLInputElement.popoverTargetElement

獲取和設定由控制元件按鈕控制的彈出框元素。是 popovertarget HTML 屬性的 JavaScript 等效項。

HTMLButtonElement.popoverTargetAction 和 HTMLInputElement.popoverTargetAction

獲取和設定由控制元件按鈕控制的彈出框元素上執行的操作（"hide"、"show" 或 "toggle"）。反映了 popovertargetaction HTML 屬性的值。

例項方法

HTMLElement.hidePopover()

透過將其從頂層移除並應用 display: none 樣式來隱藏彈出框元素。

HTMLElement.showPopover()

透過將其新增到頂層來顯示彈出框元素。

HTMLElement.togglePopover()

在顯示和隱藏狀態之間切換彈出框元素。

事件

HTMLElement.beforetoggle 事件

在彈出框元素的狀態在顯示和隱藏之間切換之前觸發（反之亦然）。可用於阻止彈出框開啟，或更新需要由彈出框狀態觸發的其他元素。

HTMLElement.toggle 事件

在彈出框元素的狀態在顯示和隱藏之間切換之後觸發（反之亦然）。

示例

有關 MDN 彈出框示例的完整集合，請參閱我們的 Popover API 示例登陸頁。

規範

瀏覽器相容性

api.HTMLElement.popover

api.HTMLElement.beforetoggle_event.popover_elements

api.HTMLElement.toggle_event.popover_elements

另見

• popover HTML 全域性屬性
• popovertarget HTML 屬性
• popovertargetaction HTML 屬性
• ::backdrop CSS 偽元素
• :popover-open CSS 偽類