Popover API

December 2, 2023October 13, 2025

128

在网页上非常常见的一种模式是在其它内容上显示内容，吸引用户注意力到特定的重要信息或需要执行的操作。
这种内容可以取多种不同的名字：overlay、popup、popover、dialog 等。规范称为 popover。
总的来说，它们可以分为：

modal，popover 显示时，其他页面部分将处于非交互状态，直到 popover 被通过某种方式进行操作（例如选择一个重要的选项）。

non-modal，popover 显示时，用户可以与其他页面部分进行交互。

使用 Popover API 创建的 popover 始终为 non-modal。
如果希望创建一个 modal 的 popover，可以使用 <dialog> 元素（需要通过 HTMLDialogElement.showModal() 实现，否则其不会创建 top layer；popover 则始终创建 top layer）

HTML popover 具有以下特性：

提升至 top layer。从而无需考虑 z-index（只需考虑在 top layer 的顺序，无需考虑 DOM 层级的层叠上下文）
Light-dismiss 功能。点击 popover 外部区域即可关闭 popover 并返还 focus （回到打开 popover 之前的 focus）
默认的 focus 管理。打开 popover 则 tab 键局限在 popover 内部
无障碍键盘绑定。按下 Esc 键即可关闭 popover 并返还 focus
无障碍组件绑定。可以从语义上将一个 popover 元素连接到一个触发者元素

HTML 属性

popover 可以是任何 HTML 元素（即 HTMLElement 而不是 SVGElement），popover 的触发者只能是 button 或 input 元素（下面主要以按钮举例）

html

<div id="div" popover>[popover]</div>
<button popovertarget="div">toggle</button>
<button popovertarget="div" popovertargetaction="show">show</button>
<button popovertarget="div" popovertargetaction="hide">hide</button>

popover=auto （空字符串相当于 auto）自动隐藏 popover 的元素（比如点击页面的其它部分或按 Esc 键）。因此只会同时出现一个 auto 的 popover（即所谓 "light dismissed"）
popover=manual 手动隐藏，需通过 js 或对应 popovertarget 元素来操纵。因此可以出现多个 popover
popovertarget 在 button 或 input 元素上设置，值为对应 popover 的 id，用于控制该 popover
popovertargetaction=toggle （空字符串或未设置相当于 toggle）相当于点击该按钮调用 popover 的 HTMLElement.togglePopover() 方法
popovertargetaction=show 相当于 popover 隐藏时，点击该按钮调用 popover 的 HTMLElement.showPopover() 方法
popovertargetaction=hide 相当于 popover 显示时，点击该按钮调用 popover 的 HTMLElement.hidePopover() 方法

CSS

注意 close 状态没有对应的伪类。要只匹配 close 状态，使用 :not() 即可

css

:popover-open {
}
:not(:popover-open) {
}

popover 的默认样式如下

css

[popover]:popover-open:not(dialog) {
    overlay: auto !important;
}
[popover] {
    position: fixed;
    width: fit-content;
    height: fit-content;
    color: canvastext;
    background-color: canvas;
    inset: 0px;
    margin: auto;
    border-width: initial;
    border-style: solid;
    border-color: initial;
    border-image: initial;
    padding: 0.25em;
    overflow: auto;
}

js 可利用此伪类判断是 open 还是 close 状态

popover.matches(":popover-open");

::backdrop

:popover-open 状态的 popover 会创建 top-layer 层，::backdrop 伪类可匹配该层的 backdrop

注：每一个提升至 top-layer 的元素都关联一个 ::backdrop，且在层叠顺序上 ::backdrop 在该元素下。

注意到 popover 的 ::backdrop 默认是透明且屏蔽指针事件的

css

[popover]:-internal-popover-in-top-layer::backdrop {
    position: fixed;
    background-color: transparent;
    pointer-events: none !important;
    inset: 0px;
}

相比于 HTMLDialogElement.showModal() 产生的默认 ::backdrop，则默认阴影且响应指针事件

css

dialog:-internal-dialog-in-top-layer::backdrop {
    position: fixed;
    inset: 0px;
    background: rgba(0, 0, 0, 0.1);
}

DOM API

// 仅作示意
interface HTMLButtonElement /* 以及 HTMLInputElement */ {
    //  html 属性 popovertarget 只能设置为 id
    popoverTargetElement: Element | null;
    // 反映 html 属性 popovertargetaction，即修改此值也会反映到 html 上
    // 注意 popovertargetaction 为空字符串或未设置相当于 toggle
    popoverTargetAction: "hide" | "show" | "toggle";
}

interface HTMLElement {
    // 反映 html 属性 popover
    popover: "auto" | "manual" | null;

    // 若 popover 已隐藏，会抛出 DOMException
    hidePopover(): void;
    // 若 popover 已显示，会抛出 DOMException
    showPopover(): void;

    // 不传 force 时，则切换显隐状态
    // force 为 true 时，强制显示 popover。若已显示，也不会抛出异常
    // force 为 false 时，强制隐藏 popover。若已隐藏，也不会抛出异常
    // 返回切换后 popover 是否是 open 状态（目前Chrome120暂不支持，会返回undefined）
    togglePopover(force?: boolean): boolean;

    // 状态切换之前触发，ToggleEvent 包含当前状态（oldState）和切换之后的状态（newState）
    // 注意：即使在一次事件循环中多次修改 popover 状态，也只会触发一次 beforetoggle 事件
    onbeforetoggle: ((this: HTMLElement, ev: ToggleEvent) => any) | null;

    // 状态切换之后触发，ToggleEvent 包含切换之前的状态（oldState）和当前状态（newState）
    // 注意：HTMLDetailsElement 也会触发此事件，与 HTMLElement 触发的事件略有不同
    ontoggle: ((this: HTMLElement, ev: ToggleEvent) => any) | null;

    addEventListener(
        type: "beforetoggle" | "toggle",
        listener: (this: HTMLElement, ev: ToggleEvent) => any,
        options?: boolean | AddEventListenerOptions,
    ): void;

    removeEventListener(
        type: "beforetoggle" | "toggle",
        listener: (this: HTMLElement, ev: ToggleEvent) => any,
        options?: boolean | EventListenerOptions,
    ): void;
}

// 注意是 open 或 closed，而不是 close 或者 show/hide
interface ToggleEvent extends Event {
    readonly newState: "open" | "closed";
    readonly oldState: "open" | "closed";
}

略。参见：https://developer.mozilla.org/docs/Web/API/Popover_API/Using#nested_popovers

https://developer.chrome.com/blog/tether-elements-to-each-other-with-css-anchor-positioning/

CSS 扩展

注意 CSS 属性 overlay 只能由浏览器设置，该属性作用在 ::backdrop 伪类之前的那个元素（比如 popover 和 dialog，作用相当于 ::backdrop 的 display:block 到 display:none）。我们只能设置 transition-property: overlay，且仅当 transition-behavior: allow-discrete 时才有实际效果。