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 伪类