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.