HTML：活文档标准
网页开发者版 — 最后更新于 2024年9月12日
网页开发者版 — 最后更新于 2024年9月12日
popover 属性所有当前引擎都支持。
所有 HTML 元素 都可以设置 popover 内容属性。当指定时，元素在显示之前不会被渲染，显示后将在其他页面内容之上渲染。
popover 属性是一个全局属性，允许作者灵活地确保弹出窗口功能可以应用于具有最相关语义的元素。
以下演示了如何在网站的全局导航中创建弹出窗口子导航链接列表。
< ul >
< li >
< a href = ... > All Products</ a >
< button popovertarget = sub-nav >
< img src = down-arrow.png alt = "Product pages" >
</ button >
< ul popover id = sub-nav >
< li >< a href = ... > Shirts</ a >
< li >< a href = ... > Shoes</ a >
< li >< a href = ... > Hats etc.</ a >
</ ul >
</ li >
<!-- other list items and links here -->
</ ul > 当在没有辅助功能语义的元素上使用 popover 时，例如 div 元素，作者应使用适当的 ARIA 属性来确保弹出窗口的可访问性。
以下显示了创建自定义菜单弹出窗口的基本标记，其中第一个菜单项在弹出窗口被调用时将获得键盘焦点，这是由于使用了 autofocus 属性。使用方向键导航菜单项和激活行为仍需要作者编写脚本。构建自定义菜单小部件的其他要求在 WAI-ARIA 规范 中定义。
< button popovertarget = m > Actions</ button >
< div role = menu id = m popover >
< button role = menuitem tabindex = -1 autofocus > Edit</ button >
< button role = menuitem tabindex = -1 > Hide</ button >
< button role = menuitem tabindex = -1 > Delete</ button >
</ div > 弹出窗口可用于渲染状态消息，确认用户执行的操作。以下演示了如何在 output 元素中显示弹出窗口。
< button id = submit > Submit</ button >
< p >< output >< span popover = manual ></ span ></ output ></ p >
< script >
const sBtn = document. getElementById( "submit" );
const outSpan = document. querySelector( "output [popover=manual]" );
let successMessage;
let errorMessage;
/* define logic for determining success of action
and determining the appropriate success or error
messages to use */
sBtn. addEventListener( "click" , ()=> {
if ( success ) {
outSpan. textContent = successMessage;
}
else {
outSpan. textContent = errorMessage;
}
outSpan. showPopover();
setTimeout( function () {
outSpan. hidePopover();
}, 10000 );
});
</ script > 将弹出窗口元素插入 output 元素通常会导致屏幕阅读器在它变得可见时宣布其内容。根据内容的复杂性或频率，这对于使用这些辅助技术的用户来说可能有用或令人讨厌。在使用 output 元素或其他 ARIA 实时区域时请记住这一点，以确保最佳的用户体验。
| 关键字 | 状态 | 简要描述 |
|---|---|---|
auto
| auto | 打开时关闭其他弹出窗口；具有 轻量级关闭 功能并响应 关闭请求。 |
| （空字符串） | ||
manual
| manual | 不关闭其他弹出窗口；不 轻量级关闭 也不响应 关闭请求。 |
该属性的 缺失值默认值 是 无弹出窗口 状态，其 无效值默认值 是 manual 状态。
所有当前引擎都支持。
popover IDL 属性必须 反映 popover 属性，仅限于已知值。
每个 HTML 元素 都有一个 弹出窗口可见性状态，最初为 ，具有以下潜在值
hidden
showing
Document 具有一个 弹出窗口指针按下目标，它是一个 HTML 元素 或 null，最初为 null。
每个 HTML 元素 都有一个 弹出窗口调用者，它是一个 HTML 元素 或 null，最初设置为 null。
每个 HTML 元素 都有一个 弹出窗口显示或隐藏，它是一个布尔值，最初设置为 false。
每个 HTML 元素 弹出窗口切换任务跟踪器，它是一个 切换任务跟踪器 或 null，最初为 null。
每个 HTML 元素 都有一个 弹出窗口关闭观察者，它是一个 关闭观察者 或 null，最初为 null。
以下 属性更改步骤，给定 element、localName、oldValue、value 和 namespace，用于所有 HTML 元素
如果 namespace 不为 null，则返回。
如果 localName 不是 popover，则返回。
如果 element 的 弹出窗口可见性状态 处于 显示状态 且 oldValue 和 value 处于不同的 状态，则运行给定 element、true、true 和 false 的 隐藏弹出窗口算法。
element.showPopover()所有当前引擎都支持。
popover 属性处于 auto 状态，则这也会关闭所有其他 auto 弹出窗口，除非它们是根据 最顶层弹出窗口祖先 算法的 element 的祖先。element.hidePopover()所有当前引擎都支持。
display: none 来隐藏弹出窗口 element。element.togglePopover()所有当前引擎都支持。
showPopover() 方法的步骤是运行给定 this、true 和 null 的 显示弹出窗口。
要 显示弹出窗口，给定一个 HTML 元素 element、一个布尔值 throwExceptions 和一个 HTML 元素 或 null invoker
如果给定 element、false、throwExceptions 和 null 运行 检查弹出窗口有效性 的结果为 false，则返回。
令 document 为 element 的 节点文档。
令 nestedShow 为 element 的 弹出窗口显示或隐藏。
将 element 的 弹出窗口显示或隐藏 设置为 true。
令 cleanupShowingFlag 为以下步骤
如果 nestedShow 为 false，则将 element 的 弹出窗口显示或隐藏 设置为 false。
如果 触发名为 beforetoggle 的事件，使用 ToggleEvent，并将 cancelable 属性初始化为 true，oldState 属性初始化为 "closed"，newState 属性初始化为 "open" 在 element 上的结果为 false，则运行 cleanupShowingFlag 并返回。
如果给定 element、false、throwExceptions 和 document 运行 检查弹出窗口有效性 的结果为 false，则运行 cleanupShowingFlag 并返回。
再次调用检查弹出窗口有效性 是因为触发 beforetoggle 事件可能会断开此元素的连接或更改其 popover 属性。
令 shouldRestoreFocus 为 false。
如果 element 的 popover 属性处于 auto 状态，则
令 originalType 为 element 的 popover 属性的值。
令 ancestor 为给定 element、invoker 和 true 运行 最顶层弹出窗口祖先 算法的结果。
如果 ancestor 为 null，则将 ancestor 设置为 document。
运行给定 ancestor、false 和 not nestedShow 的 隐藏所有弹出窗口直到。
如果 originalType 不等于 element 的 popover 属性的值，则
如果 throwExceptions 为 true，则抛出一个 "InvalidStateError" DOMException。
返回。
如果给定 element、false、throwExceptions 和 document 运行 检查弹出窗口有效性 的结果为 false，则运行 cleanupShowingFlag 并返回。
再次调用 检查弹出框有效性，因为上面运行 隐藏所有弹出框直到 可能触发了 beforetoggle 事件，并且事件处理程序可能已断开此元素的连接或更改了其 popover 属性。
如果在 document 上运行 最顶层自动弹出框 的结果为 null，则将 shouldRestoreFocus 设置为 true。
这确保仅为堆栈中的第一个弹出框将焦点返回到先前聚焦的元素。
将 element 的 弹出框关闭观察器 设置为给定 element 的 相关全局对象，使用 建立关闭观察器 的结果，其中
cancelAction 为返回 true。
closeAction 为给定 element、true、true 和 false 的 隐藏弹出框。
将 element 的 先前聚焦的元素 设置为 null。
给定 element 的 将元素添加到顶层。
将 element 的 弹出框调用者 设置为 invoker。
运行给定 element 的 弹出框聚焦步骤。
如果 shouldRestoreFocus 为 true 且 element 的 popover 属性不处于 无弹出框 状态，则将 element 的 先前聚焦的元素 设置为 originallyFocusedElement。
给定 element、"closed" 和 "open" 的 排队弹出框切换事件任务。
运行 cleanupShowingFlag。
给定一个元素 element、一个字符串 oldState 和一个字符串 newState 的 排队弹出框切换事件任务
如果 element 的 弹出框切换任务跟踪器 不为 null，则
将 oldState 设置为 element 的 弹出框切换任务跟踪器 的 旧状态。
从其 任务队列 中移除 element 的 弹出框切换任务跟踪器 的 任务。
将 element 的 弹出框切换任务跟踪器 设置为 null。
给定 DOM 操作任务源 和 element 的 排队元素任务 以运行以下步骤
在 element 上 触发一个名为 toggle 的事件，使用 ToggleEvent，将 oldState 属性初始化为 oldState，并将 newState 属性初始化为 newState。
将 element 的 弹出框切换任务跟踪器 设置为 null。
将 element 的 弹出框切换任务跟踪器 设置为一个结构体，其中 task 设置为刚刚排队的 task，old state 设置为 oldState。
hidePopover() 方法的步骤为
给定一个 HTML 元素 element、一个布尔值 focusPreviousElement、一个布尔值 fireEvents 和一个布尔值 throwExceptions 的 隐藏弹出框
如果给定 element、true、throwExceptions 和 null 运行 检查弹出框有效性 的结果为 false，则返回。
令 document 为 element 的 节点文档。
令 nestedHide 为 element 的 弹出框显示或隐藏。
将 element 的 弹出框显示或隐藏 设置为 true。
如果 nestedHide 为 true，则将 fireEvents 设置为 false。
令 cleanupSteps 为以下步骤
如果 document 的 显示的自动弹出框列表 的最后一项为 element，则 autoPopoverListContainsElement 为 true，否则为 false。
将 element 的 弹出框调用者 设置为 null。
如果 fireEvents 为 true
触发一个名为 beforetoggle 的事件，使用 ToggleEvent，将 oldState 属性初始化为 "open"，并将 newState 属性初始化为 "closed"，在 element 上触发。
如果 autoPopoverListContainsElement 为 true 且 document 的 显示的自动弹出框列表 的最后一项不为 element，则运行给定 element、focusPreviousElement 和 false 的 隐藏所有弹出框直到。
如果给定 element、true、throwExceptions 和 null 运行 检查弹出框有效性 的结果为 false，则运行 cleanupSteps 并返回。
检查弹出框有效性 再次被调用，因为触发 beforetoggle 事件可能已断开 element 的连接或更改了其 popover 属性。
给定 element 的 请求将元素从顶层移除。
否则，给定 element 的 立即将元素从顶层移除。
将 element 的 弹出框可见性状态 设置为 。
如果 fireEvents 为 true，则给定 element、"open" 和 "closed" 的 排队弹出框切换事件任务。
令 previouslyFocusedElement 为 element 的 先前聚焦的元素。
如果 previouslyFocusedElement 不为 null，则
运行 cleanupSteps。
togglePopover(force) 方法的步骤为
给定一个 HTML 元素 或 Document endpoint、一个布尔值 focusPreviousElement 和一个布尔值 fireEvents 的 隐藏所有弹出框直到
令 document 为 endpoint 的 节点文档。
令 closeAllOpenPopovers 为执行以下步骤的算法
令 popover 为 document 的 最顶层的自动弹出窗口。
当 popover 不为 null 时
运行给定 popover、focusPreviousElement、fireEvents 和 false 的 隐藏弹出窗口算法。
将 popover 设置为 document 的 最顶层的自动弹出窗口。
如果 endpoint 是一个 Document，则运行 closeAllOpenPopovers 并返回。
令 repeatingHide 为 false。
至少执行一次以下步骤
令 lastToHide 为 null。
令 foundEndpoint 为 false。
对于 document 的 显示的自动弹出窗口列表 中的每个 popover
如果 popover 是 endpoint，则将 foundEndpoint 设置为 true。
否则，如果 foundEndpoint 为 true，则将 lastToHide 设置为 popover 并 中断。
如果 foundEndpoint 为 false，则运行 closeAllOpenPopovers 并返回。
当 lastToHide 不为 null 且 lastToHide 的 弹出窗口可见性状态 为 显示 且 document 的 显示的自动弹出窗口列表 不为空时
运行给定 document 的 显示的自动弹出窗口列表 的最后一个元素、focusPreviousElement、fireEvents 和 false 的 隐藏弹出窗口算法。
如果 document 的 显示的自动弹出窗口列表 包含 endpoint 且 document 的 显示的自动弹出窗口列表 的最后一个元素不是 endpoint，则将 repeatingHide 设置为 true，否则为 false。
如果 repeatingHide 为 true，则将 fireEvents 设置为 false。
并持续执行这些步骤，直到 repeatingHide 为 true。
在某些情况下，隐藏所有弹出窗口直到算法 用于隐藏所有在某些事件发生时不会保持打开状态的弹出窗口。例如，在弹出窗口的轻触关闭期间，此算法确保我们仅关闭与用户点击的节点无关的弹出窗口。
要查找 最顶层的弹出窗口祖先，给定一个 节点 newPopoverOrTopLayerElement、一个 HTML 元素 或 null invoker 和一个布尔值 isPopover，执行以下步骤。它们返回一个 HTML 元素 或 null。
最顶层的弹出窗口祖先 算法将返回为提供的弹出窗口或顶层元素的最顶层（在 显示的自动弹出窗口列表 中最新的）祖先弹出窗口。弹出窗口可以通过多种方式相互关联，从而创建弹出窗口树。一个弹出窗口（称为“子”弹出窗口）可以拥有最顶层祖先弹出窗口（称为“父”弹出窗口）的两种路径
弹出窗口在节点树中相互嵌套。在这种情况下，后代弹出窗口是“子”弹出窗口，其最顶层祖先弹出窗口是“父”弹出窗口。
调用元素（例如，按钮）具有一个 popovertarget 属性，该属性指向一个弹出窗口。在这种情况下，弹出窗口是“子”弹出窗口，而调用元素所在的弹出窗口子树是“父”弹出窗口。调用程序必须位于弹出窗口中并引用一个打开的弹出窗口。
在上面形成的每种关系中，父弹出窗口必须严格早于 显示的自动弹出窗口列表 中的子弹出窗口，否则它不会形成有效的祖先关系。这消除了未显示的弹出窗口和自指针（例如，包含一个指向包含弹出窗口的调用元素的弹出窗口），并且它允许从（可能是循环的）连接图构建一个格式良好的树。仅考虑 自动 弹出窗口。
如果提供的元素是顶层元素，例如 对话框，它没有显示为弹出窗口，则 最顶层的弹出窗口祖先 将只在节点树中查找第一个弹出窗口。
如果 isPopover 为 true
否则
断言：invoker 为 null。
令 popoverPositions 为一个空的 有序映射。
令 index 为 0。
令 document 为 newPopoverOrTopLayerElement 的 节点文档。
对于 document 的 显示的自动弹出窗口列表 中的每个 popover
设置 popoverPositions[popover] 为 index。
将 index 加 1。
如果 isPopover 为 true，则 设置 popoverPositions[newPopoverOrTopLayerElement] 为 index。
将 index 加 1。
令 topmostPopoverAncestor 为 null。
令 checkAncestor 为执行以下步骤的算法，给定 candidate
如果 candidate 为 null，则返回。
令 candidateAncestor 为运行给定 candidate 的 最近的包含式打开弹出窗口 的结果。
如果 candidateAncestor 为 null，则返回。
令 candidatePosition 为 popoverPositions[candidateAncestor]。
如果 topmostPopoverAncestor 为 null 或 popoverPositions[topmostPopoverAncestor] 小于 candidatePosition，则将 topmostPopoverAncestor 设置为 candidateAncestor。
运行给定 newPopoverOrTopLayerElement 在 扁平树 中的父节点的 checkAncestor。
运行给定 invoker 的 checkAncestor。
返回 topmostPopoverAncestor。
要查找给定 节点 node 的 最近的包含式打开弹出窗口，执行以下步骤。它们返回一个 HTML 元素 或 null。
令 currentNode 为 node。
当 currentNode 不为 null 时
返回 null。
要查找给定 Document document 的 最顶层的自动弹出窗口，执行以下步骤。它们返回一个 HTML 元素 或 null。
如果 document 的 显示的自动弹出窗口列表 不为空，则返回 document 的 显示的自动弹出窗口列表 的最后一个元素。
返回 null。
要为 HTML 元素 subject 执行 弹出窗口聚焦步骤
如果 subject 是一个 对话框 元素，则运行给定 subject 的 对话框聚焦步骤 并返回。
如果 subject 具有 autofocus 属性，则令 control 为 subject。
否则，令 control 为给定“other”的 subject 的 自动聚焦委托。
如果 control 为 null，则返回。
运行给定 control 的 聚焦步骤。
清空 topDocument 的 自动聚焦候选。
将 topDocument 的 自动聚焦处理标志 设置为 true。
要为 HTML 元素 element 执行 检查弹出窗口有效性，给定一个布尔值 expectedToBeShowing、一个布尔值 throwExceptions 和一个 Document 或 null expectedDocument，执行以下步骤。它们抛出异常或返回一个布尔值。
如果 element 的 popover 属性处于 无弹出窗口 状态，则
如果 throwExceptions 为真，则抛出一个 "NotSupportedError" DOMException。
返回 false。
如果以下任何一个为真
expectedToBeShowing 为假且 element 的 弹出窗口可见性状态 不是 ，
则返回 false。
如果以下任何一个为真
element 未 连接；
expectedDocument 不为 null 且 element 的 节点文档 不是 expectedDocument；
element 是一个 对话框 元素，并且其 模态 标志设置为 true；或者
element 的 全屏标志 已设置，
则
如果 throwExceptions 为真，则抛出一个 "InvalidStateError" DOMException。
返回 false。
返回 true。
要获取 Document document 的 显示自动弹出窗口列表
令 popovers 为 « »。
对于每个 Element element 在 document 的 顶层 中：如果 element 的 popover 属性处于 自动状态 且 element 的 弹出窗口可见性状态 为 显示，则 追加 element 到 popovers。
返回 popovers。
按钮 可以具有以下内容属性
popovertarget
popovertargetaction
如果指定，则 popovertarget 属性值必须是具有 popover 属性的元素的 ID，该元素与具有 popovertarget 属性的 按钮 位于相同的 树 中。
The popovertargetaction 属性是一个 枚举属性，具有以下关键字和状态
| 关键字 | 状态 | 简要描述 |
|---|---|---|
toggle
| toggle | 显示或隐藏目标弹出窗口元素。 |
show
| show | 显示目标弹出窗口元素。 |
hide
| hide | 隐藏目标弹出窗口元素。 |
属性的 缺失值默认值 和 无效值默认值 均为 toggle 状态。
在可能的情况下，确保弹出窗口元素放置在其触发元素之后的 DOM 中。这样做将有助于确保弹出窗口以辅助技术（例如屏幕阅读器）用户的逻辑程序化阅读顺序显示。
以下显示了 popovertarget 属性与 popovertargetaction 属性结合使用以显示和关闭弹出窗口的方式
< button popovertarget = "foo" popovertargetaction = "show" >
Show a popover
</ button >
< article popover = "auto" id = "foo" >
This is a popover article!
< button popovertarget = "foo" popovertargetaction = "hide" > Close</ button >
</ article > 如果未指定 popovertargetaction 属性，则默认操作将是切换关联的弹出窗口。以下显示了仅在其调用按钮上指定 popovertarget 属性如何可以在其打开和关闭状态之间切换手动弹出窗口。手动弹出窗口不会响应 轻触关闭 或 关闭请求
< input type = "button" popovertarget = "foo" value = "Toggle the popover" >
< div popover = manual id = "foo" >
This is a popover!
</ div > HTMLButtonElement/popoverTargetElement
所有当前引擎都支持。
HTMLInputElement/popoverTargetElement
所有当前引擎都支持。
The popoverTargetElement IDL 属性必须 反映 popovertarget 属性。
HTMLButtonElement/popoverTargetAction
所有当前引擎都支持。
HTMLInputElement/popoverTargetAction
所有当前引擎都支持。
The popoverTargetAction IDL 属性必须 反映 popovertargetaction 属性，仅限于已知值。
要运行给定 Node node 的 弹出窗口目标属性激活行为
令 popover 为 node 的 弹出窗口目标元素。
如果 popover 为 null，则返回。
如果 node 的 popovertargetaction 属性处于 show 状态且 popover 的 弹出窗口可见性状态 为 显示，则返回。
如果 node 的 popovertargetaction 属性处于 hide 状态且 popover 的 弹出窗口可见性状态 为 ，则返回。
如果 popover 的 弹出窗口可见性状态 为 显示，则运行给定 popover、true、true 和 false 的 隐藏弹出窗口算法。
否则，如果 popover 的 弹出窗口可见性状态 为 并且运行给定 popover、false、false 和 null 的 检查弹出窗口有效性 的结果为真，则运行给定 popover、false 和 node 的 显示弹出窗口。
要获取给定 Node node 的 弹出窗口目标元素，请执行以下步骤。它们返回 HTML 元素 或 null。
如果 node 不是 按钮，则返回 null。
如果 node 已禁用，则返回 null。
令 popoverElement 为运行 node 的 获取 popovertarget 关联的元素 的结果。
如果 popoverElement 为 null，则返回 null。
返回 popoverElement。
"轻触关闭" 表示点击 popover 属性处于 auto 状态的弹出窗口外部将关闭弹出窗口。这除了此类弹出窗口如何响应 关闭请求 之外。
要 轻触关闭打开的弹出窗口，给定一个 Event event
令 target 为 event 的 目标。
令 document 为 target 的 节点文档。
令 topmostPopover 为运行给定 document 的 最顶层自动弹出窗口 的结果。
如果 topmostPopover 为 null，则返回。
如果 event 是 PointerEvent 且 event 的 type 为 "pointerdown"，则：将 document 的 弹出窗口 pointerdown 目标 设置为运行给定 target 的 最顶层点击的弹出窗口 的结果。
如果 event 是 PointerEvent 且 event 的 type 为 "pointerup"，则
令 ancestor 为运行给定 target 的 最顶层点击的弹出窗口 的结果。
如果 ancestor 为 document 的 弹出窗口 pointerdown 目标，则令 sameTarget 为真。
将 document 的 弹出窗口 pointerdown 目标 设置为 null。
如果 ancestor 为 null，则将 ancestor 设置为 document。
如果 sameTarget 为真，则运行给定 ancestor、false 和 true 的 隐藏所有弹出窗口直到。
轻触关闭打开的弹出窗口 将由 指针事件规范 在用户点击或触摸页面上的任何位置时调用。
要查找给定 Node node 的 最顶层点击的弹出窗口
令 clickedPopover 为运行给定 node 的 最近的包含打开的弹出窗口 的结果。
令 invokerPopover 为运行给定 node 的 调用者的最近的包含目标弹出窗口 的结果。
令getStackPosition为一个算法，它在给定一个HTML 元素popover时执行以下步骤。
如果运行getStackPosition并给定clickedPopover的结果大于运行getStackPosition并给定invokerPopover的结果，则返回clickedPopover。
返回invokerPopover。
要查找给定一个节点node的调用者最近的包含目标弹出窗口