动态标准 - 最后更新 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 | 不关闭其他弹出窗口;不进行 轻量级关闭 或响应 关闭请求。 |
属性的 缺失值默认值 是 无弹出 状态,其 无效值默认值 是 手动 状态。
所有当前引擎都支持。
popover
IDL 属性必须 反映 popover 属性,仅限于已知值。
每个 HTML 元素 都有一个 弹出可见性状态,最初为 ,具有以下潜在值
隐藏
显示
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
属性处于 自动 状态,则这也会关闭所有其他 自动 弹出窗口,除非它们是 element 的祖先,根据 最顶层弹出祖先 算法。element.hidePopover()
display: none
来隐藏它。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
属性处于 自动 状态,则
令 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 的情况下运行 检查 popover 有效性 的结果为 false,则运行 cleanupShowingFlag 并返回。
检查 popover 有效性 再次被调用,因为上面运行 隐藏所有 popover 直到 可能触发了 beforetoggle
事件,并且事件处理程序可能已断开此元素的连接或更改了其 popover
属性。
如果在 document 上运行 最顶层的自动 popover 的结果为 null,则将 shouldRestoreFocus 设置为 true。
这确保仅在堆栈中的第一个 popover 中将焦点返回到之前聚焦的元素。
将 element 的 popover 关闭观察器 设置为在给定 element 的 相关全局对象 的情况下 建立关闭观察器 的结果,其中
取消操作 是返回 true。
关闭操作 是在给定 element、true、true 和 false 的情况下 隐藏 popover。
将 element 的 之前聚焦的元素 设置为 null。
将元素添加到顶层,给定 element。
将 element 的 popover 可见性状态 设置为 显示。
将 element 的 popover 调用者 设置为 invoker。
运行 popover 聚焦步骤,给定 element。
如果 shouldRestoreFocus 为 true 且 element 的 popover
属性不在 无 popover 状态中,则将 element 的 之前聚焦的元素 设置为 originallyFocusedElement。
排队一个 popover 切换事件任务,给定 element、"closed
" 和 "open
"。
运行 cleanupShowingFlag。
要 排队一个 popover 切换事件任务,给定一个元素 element、一个字符串 oldState 和一个字符串 newState
如果 element 的 popover 切换任务跟踪器 不为 null,则
将 oldState 设置为 element 的 popover 切换任务跟踪器 的 旧状态。
从 element 的 popover 切换任务跟踪器 的 任务 中将其从其 任务队列 中删除。
将 element 的 popover 切换任务跟踪器 设置为 null。
排队一个元素任务,给定 DOM 操作任务源 和 element 以运行以下步骤
触发一个事件,名为 toggle
,在 element 上,使用 ToggleEvent
,其中 oldState
属性初始化为 oldState,而 newState
属性初始化为 newState。
将 element 的 popover 切换任务跟踪器 设置为 null。
将 element 的 popover 切换任务跟踪器 设置为一个结构体,其中 任务 设置为刚刚排队的 任务,旧状态 设置为 oldState。
所有当前引擎都支持。
hidePopover()
方法的步骤是
运行 隐藏 popover 算法,给定 this、true、true 和 true。
要 隐藏 popover,给定一个 HTML 元素 element、一个布尔值 focusPreviousElement、一个布尔值 fireEvents 和一个布尔值 throwExceptions
如果在给定 element、true、throwExceptions 和 null 的情况下运行 检查 popover 有效性 的结果为 false,则返回。
令 document 为 element 的 节点文档。
令 nestedHide 为 element 的 popover 显示或隐藏。
将 element 的 popover 显示或隐藏 设置为 true。
如果 nestedHide 为 true,则将 fireEvents 设置为 false。
令 cleanupSteps 为以下步骤
如果 nestedHide 为 false,则将 element 的 popover 显示或隐藏 设置为 false。
如果 element 的 popover 关闭观察器 不为 null,则
销毁 element 的 popover 关闭观察器。
将 element 的 popover 关闭观察器 设置为 null。
如果 element 的 popover
属性处于 自动 状态,则
运行 隐藏所有 popover 直到,给定 element、focusPreviousElement 和 fireEvents。
如果在给定 element、true 和 throwExceptions 的情况下运行 检查 popover 有效性 的结果为 false,则运行 cleanupSteps 并返回。
检查 popover 有效性 再次被调用,因为运行 隐藏所有 popover 直到 可能已断开 element 的连接或更改了其 popover
属性。
令 autoPopoverListContainsElement 为 true,如果 document 的 显示自动 popover 列表 的最后一项是 element,否则为 false。
将 element 的 popover 调用者 设置为 null。
如果 fireEvents 为 true
触发一个事件,名为 beforetoggle
,使用 ToggleEvent
,其中 oldState
属性初始化为 "open
",而 newState
属性初始化为 "closed
",在 element 上。
如果 autoPopoverListContainsElement 为 true 且 document 的 显示自动 popover 列表 的最后一项不是 element,则运行 隐藏所有 popover 直到,给定 element、focusPreviousElement 和 false。
如果在给定 element、true、throwExceptions 和 null 的情况下运行 检查 popover 有效性 的结果为 false,则运行 cleanupSteps 并返回。
检查 popover 有效性 再次被调用,因为触发 beforetoggle
事件可能已断开 element 的连接或更改了其 popover
属性。
请求将元素从顶层移除,给定 element。
否则,立即将元素从顶层移除,给定 element。
将 element 的 popover 可见性状态 设置为 。
如果 fireEvents 为 true,则 排队一个 popover 切换事件任务,给定 element、"open
" 和 "closed
"。
令 previouslyFocusedElement 为 element 的 之前聚焦的元素。
如果 previouslyFocusedElement 不为 null,则
运行 cleanupSteps。
所有当前引擎都支持。
togglePopover(force)
方法的步骤是
如果 this 的 popover 可见性状态 为 显示,且 force 不存在或为 false,则运行 隐藏 popover 算法,给定 this、true、true 和 true。
否则
要 隐藏所有弹出窗口直到,给定一个 HTML 元素 或 Document
endpoint,一个布尔值 focusPreviousElement 和一个布尔值 fireEvents
令 document 为 endpoint 的 节点文档。
令 closeAllOpenPopovers 为执行以下步骤的算法
如果 endpoint 是一个 Document
,则运行 closeAllOpenPopovers 并返回。
令 repeatingHide 为假。
至少执行一次以下步骤
令 lastToHide 为空。
令 foundEndpoint 为假。
对于 document 的 显示自动弹出窗口列表 中的每个 popover
如果 popover 是 endpoint,则将 foundEndpoint 设置为真。
否则,如果 foundEndpoint 为真,则将 lastToHide 设置为 popover 且 中断。
如果 foundEndpoint 为假,则运行 closeAllOpenPopovers 并返回。
当 lastToHide 不为空且 lastToHide 的 弹出窗口可见性状态 为 显示 且 document 的 显示自动弹出窗口列表 不为空时
运行给定 document 的 显示自动弹出窗口列表 的最后一个元素、focusPreviousElement、fireEvents 和假的 隐藏弹出窗口算法。
如果 document 的 显示自动弹出窗口列表 包含 endpoint 且 document 的 显示自动弹出窗口列表 的最后一个元素不是 endpoint,则将 repeatingHide 设置为真,否则为假。
如果 repeatingHide 为真,则将 fireEvents 设置为假。
并继续执行它们,当 repeatingHide 为真时。
在几种情况下使用 隐藏所有弹出窗口直到算法 来隐藏在事件发生时不会保持打开状态的所有弹出窗口。例如,在弹出窗口的轻微关闭期间,此算法确保我们只关闭与用户点击的节点无关的弹出窗口。
要查找 最顶层弹出窗口祖先,给定一个 Node
newPopoverOrTopLayerElement,一个 HTML 元素 或空 invoker,以及一个布尔值 isPopover,执行以下步骤。它们返回一个 HTML 元素 或空。
最顶层弹出窗口祖先 算法将返回为提供的弹出窗口或顶层元素提供的最顶层(在 显示自动弹出窗口列表 中最新)祖先弹出窗口。弹出窗口可以通过多种方式相互关联,从而创建弹出窗口树。弹出窗口(称为“子”弹出窗口)可以拥有最顶层祖先弹出窗口(称为“父”弹出窗口)的两种途径
弹出窗口在节点树中相互嵌套。在这种情况下,后代弹出窗口是“子”,其最顶层祖先弹出窗口是“父”。
调用元素(例如,button
)具有一个指向弹出窗口的 popovertarget
属性。在这种情况下,弹出窗口是“子”,调用元素所在的弹出窗口子树是“父”。调用元素必须在弹出窗口中并引用一个打开的弹出窗口。
在以上形成的每种关系中,父弹出窗口必须严格早于子弹出窗口在 显示自动弹出窗口列表 中,否则它将不形成有效的祖先关系。这将消除未显示的弹出窗口和自指针(例如,包含指向包含弹出窗口的调用元素的弹出窗口),并且允许从(可能是循环的)连接图构建一个格式良好的树。只考虑 auto 弹出窗口。
如果提供的元素是顶层元素,例如一个未显示为弹出窗口的 dialog
,则 最顶层弹出窗口祖先 将只在节点树中查找第一个弹出窗口。
如果 isPopover 为真
否则
断言:invoker 为空。
令 popoverPositions 为一个空的 有序映射。
令 index 为 0。
令 document 为 newPopoverOrTopLayerElement 的 节点文档。
对于 document 的 显示自动弹出窗口列表 中的每个 popover
设置 popoverPositions[popover] 为 index。
将 index 增加 1。
如果 isPopover 为真,则 设置 popoverPositions[newPopoverOrTopLayerElement] 为 index。
将 index 增加 1。
令 topmostPopoverAncestor 为空。
令 checkAncestor 为执行以下步骤的算法,给定 candidate
如果 candidate 为空,则返回。
令 candidateAncestor 为运行给定 candidate 的 最近包含的打开弹出窗口 的结果。
如果 candidateAncestor 为空,则返回。
令 candidatePosition 为 popoverPositions[candidateAncestor]。
如果 topmostPopoverAncestor 为空或 popoverPositions[topmostPopoverAncestor] 小于 candidatePosition,则将 topmostPopoverAncestor 设置为 candidateAncestor。
运行给定 newPopoverOrTopLayerElement 在 扁平树 中的父节点的 checkAncestor。
运行给定 invoker 的 checkAncestor。
返回 topmostPopoverAncestor。
要查找给定一个 Node
node 的 最近包含的打开弹出窗口,执行以下步骤。它们返回一个 HTML 元素 或空。
令 currentNode 为 node。
当 currentNode 不为空时
返回空。
要 查找最顶层自动弹出窗口,给定一个 Document
document,执行以下步骤。它们返回一个 HTML 元素 或空。
如果 document 的 显示自动弹出窗口列表 不为空,则返回 document 的 显示自动弹出窗口列表 的最后一个元素。
返回空。
要执行 弹出窗口聚焦步骤,针对一个 HTML 元素 subject
如果 subject 具有 autofocus
属性,则令 control 为 subject。
否则,令 control 为给定“other
”的 subject 的 自动聚焦委托。
如果 control 为空,则返回。
运行给定 control 的 聚焦步骤。
将 topDocument 的 自动聚焦处理标志 设置为 true。
要 检查弹出框有效性,对于给定布尔值 expectedToBeShowing、布尔值 throwExceptions 和 文档
或 null 的 expectedDocument 的 HTML 元素 element,执行以下步骤。它们将抛出异常或返回布尔值。
如果 element 的 弹出框
属性处于 无弹出框 状态,则
如果 throwExceptions 为 true,则抛出 "NotSupportedError
" DOM 异常
。
返回 false。
如果以下任何一项为真
expectedToBeShowing 为 false 且 element 的 弹出框可见性状态 不是 ,
则返回 false。
如果以下任何一项为真
则
如果 throwExceptions 为 true,则抛出 "InvalidStateError
" DOM 异常
。
返回 false。
返回 true。
要获取 显示自动弹出框列表,对于 文档
document
令 popovers 为 « »。
对于每个 元素
element,在 document 的 顶层 中:如果 element 的 弹出框
属性处于 自动状态 且 element 的 弹出框可见性状态 为 显示,则 追加 element 到 popovers 中。
返回 popovers。
按钮 可能具有以下内容属性
popovertarget
popovertargetaction
如果指定,popovertarget
属性值必须是具有 弹出框
属性的元素的 ID,该元素与具有 popovertarget
属性的 按钮 位于同一 树 中。
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 >
interface mixin PopoverInvokerElement {
[CEReactions ] attribute Element ? popoverTargetElement ;
[CEReactions ] attribute DOMString popoverTargetAction ;
};
HTMLButtonElement/popoverTargetElement
所有当前引擎都支持。
HTMLInputElement/popoverTargetElement
所有当前引擎都支持。
popoverTargetElement
IDL 属性必须 反映 popovertarget
属性。
HTMLButtonElement/popoverTargetAction
所有当前引擎都支持。
HTMLInputElement/popoverTargetAction
所有当前引擎都支持。
popoverTargetAction
IDL 属性必须 反映 popovertargetaction
属性,仅限于已知的值。
要运行 弹出框目标属性激活行为,对于给定的 节点
node
令 popover 为 node 的 弹出框目标元素。
如果 popover 为 null,则返回。
如果 node 的 popovertargetaction
属性处于 show 状态 且 popover 的 弹出框可见性状态 为 显示,则返回。
如果 node 的 popovertargetaction
属性处于 hide 状态 且 popover 的 弹出框可见性状态 为 ,则返回。
如果 popover 的 弹出框可见性状态 为 显示,则运行 隐藏弹出框算法,对于给定的 popover、true、true 和 false。
否则,如果 popover 的 弹出框可见性状态 为 且运行 检查弹出框有效性 的结果(对于给定的 popover、false、false 和 null)为 true,则运行 显示弹出框,对于给定的 popover、false 和 node。
要获取给定 节点
node 的 弹出框目标元素,执行以下步骤。它们将返回 HTML 元素 或 null。
如果 node 不是 按钮,则返回 null。
如果 node 已禁用,则返回 null。
令 popoverElement 为运行 node 的 获取 popovertarget
关联元素 的结果。
如果 popoverElement 为 null,则返回 null。
返回 popoverElement。
"淡出" 意味着点击 弹出框
属性处于 自动 状态的弹出框外部将关闭弹出框。这除了此类弹出框如何响应 关闭请求 外。
要 淡出打开的弹出框,对于给定的 事件
event
令 target 为 event 的 目标。
令 document 为 target 的 节点文档。
令 topmostPopover 为运行 最顶层的自动弹出框 的结果,对于给定的 document。
如果 topmostPopover 为 null,则返回。
如果 event 是一个 PointerEvent
且 event 的 类型
为 "pointerdown
",则:将 document 的 弹出框 pointerdown 目标 设置为运行 最顶层点击的弹出框 的结果,对于给定的 target。
如果 event 是一个 PointerEvent
并且 event 的 type
是 "pointerup
",则
轻微关闭打开的弹出框 将由 Pointer Events 规范 调用,当用户点击或触摸页面上的任何位置时。
为了找到 最顶层点击的弹出框,给定一个 Node
node
令 clickedPopover 为运行 最近包含的打开的弹出框 给定 node 的结果。
令 invokerPopover 为运行 最近包含的调用者的目标弹出框 给定 node 的结果。
令 getStackPosition 为一个算法,该算法在给定一个 HTML 元素 popover 时执行以下步骤
令 popoverList 为 popover 的 节点文档 的 显示的自动弹出框列表。
如果 popover 在 popoverList 中,则返回 popover 在 popoverList 中的索引 + 1。
返回 0。
如果运行 getStackPosition 给定 clickedPopover 的结果大于运行 getStackPosition 给定 invokerPopover 的结果,则返回 clickedPopover。
返回 invokerPopover。
为了找到 最近包含的调用者的目标弹出框,给定一个 Node
node