1. Web
  2. Web API
  3. HTMLElement
  4. togglePopover()

HTMLElement: togglePopover() 方法

Baseline 2024 *
新推出

自 ⁨2024 年 4 月⁩ 起，此功能可在最新的裝置和瀏覽器版本中執行。此功能可能不適用於較舊的裝置或瀏覽器。

* 此特性的某些部分可能存在不同級別的支援。

HTMLElement 介面的 togglePopover() 方法可以在隱藏和顯示狀態之間切換 popover 元素（即具有有效的 popover 屬性的元素）。

當在帶有 popover 屬性的元素上呼叫 togglePopover() 時：

  1. 會觸發一個 beforetoggle 事件。
  2. Popover 在隱藏和顯示之間切換。
    1. 如果最初是顯示的，它將切換為隱藏。
    2. 如果最初是隱藏的，它將切換為顯示。
  3. 會觸發一個 toggle 事件。

語法

js
togglePopover()
togglePopover(force)
togglePopover(options)

引數

一個布林值 (force) 或一個 options 物件

force 可選

一個布林值，它使 togglePopover() 的行為類似於 showPopover() 或 hidePopover()，不同之處在於，如果 popover 已經處於目標狀態，它不會丟擲異常。

  • 如果設定為 true，則會在 popover 最初隱藏時顯示它。如果最初是顯示的，則不執行任何操作。
  • 如果設定為 false，則會在 popover 最初顯示時將其隱藏。如果最初是隱藏的，則不執行任何操作。
options 可選

一個可能包含以下屬性的物件：

force 可選

一個布林值；請參閱上面的 force 說明。

source 可選

一個 HTMLElement 引用；以程式設計方式定義與切換操作關聯的 popover 的呼叫者，即其控制元件元素。使用 source 選項建立 popover 及其呼叫者之間的關係有兩個有益的效果：

  • 瀏覽器會將 popover 放置在顯示時的鍵盤焦點導航順序中的邏輯位置。這使得 popover 對鍵盤使用者更加可訪問（另請參閱 Popover 可訪問性功能）。
  • 瀏覽器在兩者之間建立了一個隱式錨點引用，使得使用 CSS 錨點定位 來相對於其控制元件定位彈出視窗非常方便。有關更多詳細資訊，請參閱 彈出錨點定位。

返回值

如果呼叫後彈出視窗已開啟，則為 true，否則為 false。

在舊版瀏覽器中可能會返回 None（undefined）（請參閱 瀏覽器相容性）。

示例

請參閱 Popover API 示例登陸頁，以訪問 MDN popover 示例的完整集合。

簡單的自動彈出

這是 Toggle Help UI Popover 示例 的一個略微修改的版本。該示例透過按鍵盤上的特定鍵（當示例視窗具有焦點時）來切換 popover 的開啟和關閉。

下面顯示了該示例的 HTML。第一個元素定義瞭如何呼叫彈出視窗的說明，這在我們這裡是必需的，因為彈出視窗預設是隱藏的。

html
<p id="instructions">
  Press "h" to toggle a help screen (select example window first).
</p>

然後我們定義一個 <div> 元素，它就是彈出視窗。實際內容無關緊要，但請注意，我們需要 popover 屬性才能使 <div> 成為 popover，以便它預設隱藏（或者我們可以在 JavaScript 中設定此元素）。

html
<div id="mypopover" popover>
  <h2>Help!</h2>

  <p>You can use the following commands to control the app</p>

  <ul>
    <li>Press <ins>C</ins> to order cheese</li>
    <li>Press <ins>T</ins> to order tofu</li>
    <li>Press <ins>B</ins> to order bacon</li>
  </ul>
</div>

下面顯示了該示例的 JavaScript。首先，我們檢查是否支援 popover，如果不支援，我們就隱藏 popover div，這樣它就不會內聯顯示。

js
const instructions = document.getElementById("instructions");
const popover = document.getElementById("mypopover");

if (!Object.hasOwn(HTMLElement.prototype, "popover")) {
  popover.innerText = "";
  instructions.innerText = "Popovers not supported";
}

如果支援 popover，我們新增一個偵聽器來處理按下的 h 鍵，並使用它來觸發開啟彈出視窗。我們還記錄了呼叫後彈出視窗是開啟還是關閉，但僅當返回 true 或 false 時。

js
if (Object.hasOwn(HTMLElement.prototype, "popover")) {
  document.addEventListener("keydown", (event) => {
    if (event.key === "h") {
      const popupOpened = popover.togglePopover();

      // Check if popover is opened or closed on supporting browsers
      if (popupOpened !== undefined) {
        instructions.innerText +=
          popupOpened === true ? `\nOpened` : `\nClosed`;
      }
    }
  });
}

您可以使用下面的即時示例進行測試。

規範

規範
HTML
# dom-togglepopover

瀏覽器相容性

另見

幫助改進 MDN

瞭解如何貢獻

此頁面最後修改於 ，由 MDN 貢獻者 修改。

在 GitHub 上檢視此頁面 • 報告此內容的錯誤
© . Content available under a Creative Commons license.