# 浏览器原生 Popover API 使用指南：HTML 属性与 JavaScript 控制

> 本文档介绍了浏览器原生 Popover API 的使用指南。Popover API 提供了一种标准机制，用于在页面内容之上显示非模态弹出层，支持通过 HTML 属性（如 `popover`, `popovertarget`, `interestfor`）声明式控制，或通过 JavaScript 方法（`showPopover`, `hidePopover`, `togglePopover`）编程式控制。文章详细说明了 `auto`、`hint` 和 `manual` 三种状态的区别，嵌套 Popover 的规则，以及 CSS 样式定制（如 `::backdrop` 和 `:popover-open`）。此外，还对比了 Popover API 与 `&lt;dialog&gt;` 元素在模态性、堆栈管理和可访问性方面的差异，指出 Popover 适用于非模态交互场景，而 `&lt;dialog&gt;` 更适合模态对话框。

原文：/knowledge/crawler-05b21b6a8eaaddd15aa3d7557a1bb5b39f79c6bda505efccfc061b4a8cacb146

浏览器原生 Popover API 为开发者提供了一套标准、一致且灵活的机制，用于在页面内容之上显示弹出层（Popover）内容。该 API 允许通过 HTML 属性声明式控制，或通过 JavaScript 编程式控制弹出层的显示与隐藏。Popover 内容始终位于页面的“顶层”（Top Layer），确保其显示在其他所有页面内容之上。

## 核心概念与使用场景

Popover 通常用于需要吸引用户注意力的交互元素，如操作菜单、自定义“Toast”通知、表单建议、内容选择器或教学 UI。根据交互行为，Popover 可分为两类：

*   **非模态（Non-modal）**：Popover 显示时，用户仍可与页面其他部分交互。Popover API 创建的弹出层默认均为非模态。
*   **模态（Modal）**：Popover 显示时，页面其余部分变为不可交互，直到用户处理弹出层内容。若需创建模态弹出层，应使用 `<dialog>` 元素。

> **注意**：虽然 Popover API 与 `<dialog>` 元素存在重叠，但二者定位不同。若需结合 Popover 的控制方式与 Dialog 的语义，可将 `<dialog>` 元素转换为 Popover（即 `<dialog popover>` 是合法的），但这会使其变为非模态。

## 浏览器兼容性

根据 MDN 的 Baseline 标准，Popover API 于 **2025 年 1 月** 起在所有主流浏览器（Chrome, Firefox, Safari, Edge）的最新稳定版本中成为 **Newly available**（新可用）功能。这意味着该功能在最新浏览器中广泛支持，但在旧版本浏览器或设备上可能无法使用。在部署前，建议通过特性检测确认支持情况。

## HTML 属性控制

Popover API 提供了一组 HTML 属性，使得无需 JavaScript 即可创建基本的弹出层交互。

### 1. 定义 Popover 元素
使用全局属性 `popover` 将任意元素转换为 Popover。该属性接受以下值：

*   `"auto"`（默认）：启用“轻dismiss”（Light Dismiss）行为。用户点击弹出层外部或按 Esc 键可关闭弹出层。同时，显示新的 auto Popover 会关闭其他已打开的 auto Popover。
*   `"hint"`：用于提示类弹出层（如工具提示）。它们不会关闭 auto Popover，但会关闭其他非祖先关系的 hint Popover。通常通过鼠标悬停或焦点事件触发。
*   `"manual"`：完全由 JavaScript 控制显示与隐藏，不支持轻dismiss，也不参与 auto/hint 堆栈管理。

```html
<!-- 默认 auto 状态 -->
<div id="mypopover" popover>Popover content</div>

<!-- 显式指定状态 -->
<div id="myhint" popover="hint">Tooltip content</div>
<div id="mymanual" popover="manual">Manual content</div>
```

### 2. 定义触发器（Invoker）
使用 `popovertarget` 属性将 `<button>` 或 `<input>` 元素定义为触发器，其值为目标 Popover 元素的 ID。

*   **`popovertarget`**：指定要控制的 Popover 元素的 ID。
*   **`popovertargetaction`**：指定触发器执行的动作，可选值为：
    *   `"toggle"`（默认）：切换显示/隐藏状态。
    *   `"show"`：仅显示 Popover。
    *   `"hide"`：仅隐藏 Popover。

```html
<button popovertarget="mypopover">Toggle the popover</button>
<div id="mypopover" popover>Popover content</div>

<!-- 分离的显示/隐藏按钮 -->
<button popovertarget="mypopover" popovertargetaction="show">Show</button>
<button popovertarget="mypopover" popovertargetaction="hide">Hide</button>
<div id="mypopover" popover>Popover content</div>
```

### 3. 兴趣触发器（Interest Invokers）
对于需要悬停或聚焦时显示的 Popover，可使用 `interestfor` 属性（适用于 `<a>`, `<button>`, `<area>`, `<area>` 等）。

*   **`interestfor`**：指定目标 Popover 的 ID。当用户鼠标悬停或聚焦于触发器元素时，目标 Popover 显示；当失去兴趣（鼠标移开或失去焦点）时，目标 Popover 隐藏。

```html
<button interestfor="myhint">Hover me</button>
<div id="myhint" popover="hint">Tooltip</div>
```

## JavaScript 控制

对于更复杂的交互逻辑，可使用 JavaScript API 控制 Popover。

### 核心方法
*   `HTMLElement.showPopover()`：显示 Popover。
*   `HTMLElement.hidePopover()`：隐藏 Popover。
*   `HTMLElement.togglePopover()`：切换 Popover 状态。

### 状态检测
使用 CSS 伪类选择器 `:popover-open` 结合 `Element.matches()` 方法检测 Popover 当前状态，避免对已显示或已隐藏的 Popover 重复调用方法导致错误。

```javascript
const popover = document.getElementById('mypopover');

// 检查是否已显示
if (popover.matches(':popover-open')) {
  popover.hidePopover();
} else {
  popover.showPopover();
}
```

### 键盘交互示例
```javascript
document.addEventListener('keydown', (event) => {
  if (event.key === 'h') {
    popover.togglePopover();
  }
});
```

## 嵌套 Popover

Popover API 支持嵌套结构，主要用于实现多级菜单。嵌套 Popover 允许同时显示多个弹出层，但需遵循特定规则：

1.  **直接 DOM 后代**：子 Popover 是父 Popover 的直接后代。
2.  **通过触发器关联**：父 Popover 内的触发器指向子 Popover。
3.  **通过 `anchor` 属性关联**：子 Popover 使用 `anchor="parent-id"` 指向父 Popover。

> **注意**：如果 auto Popover 嵌套在 hint Popover 内，浏览器会自动将其降级为 hint 类型。Auto Popover 不能以 hint Popover 为父级存在于 auto 堆栈中。

## 交互规则

浏览器维护两个独立的堆栈：auto 堆栈和 hint 堆栈。

*   **显示 Hint**：不会关闭 auto Popover，但会关闭其他非祖先关系的 hint Popover。
*   **显示 Auto**：会关闭所有其他 auto Popover（嵌套除外）。
*   **轻dismiss（Light Dismiss）**：点击 Popover 外部会关闭所有非祖先关系的 auto 和 hint Popover。
*   **关闭 Auto**：关闭 auto Popover 不会关闭非后代关系的 hint Popover。
*   **Manual Popover**：不参与任何堆栈，完全由 JS 控制，不影响其他 Popover。

## CSS 样式定制

### 选择器
*   `[popover]`：选择所有 Popover 元素。
*   `[popover="auto"]`：选择特定状态的 Popover。
*   `:popover-open`：选择当前显示的 Popover。

### 背景遮罩（Backdrop）
使用 `::backdrop` 伪元素为 Popover 背后的页面内容添加样式，如模糊或变暗效果。

```css
::backdrop {
  backdrop-filter: blur(3px);
  background-color: rgba(0, 0, 0, 0.5);
}
```

### 兴趣延迟
使用 `interest-delay`、`interest-delay-start` 和 `interest-delay-end` 属性控制兴趣触发器响应鼠标悬停/聚焦的延迟时间，优化用户体验。

### 兴趣源与目标样式
*   `:interest-source`：当用户对该触发器显示兴趣时，应用于触发器元素。
*   `:interest-target`：当用户对该触发器显示兴趣时，应用于目标 Popover 元素。

## 事件处理

Popover 状态变化时触发以下事件，可用于执行自定义逻辑：

*   **`beforetoggle`**：在状态改变前触发。可通过 `event.preventDefault()` 阻止状态改变。
*   **`toggle`**：在状态改变后触发。
*   **`interest`**：当用户显示兴趣（如悬停）时触发。
*   **`loseinterest`**：当用户失去兴趣（如移开鼠标）时触发。

```javascript
popover.addEventListener('beforetoggle', (event) => {
  if (event.oldState === 'open' && event.newState === 'closed') {
    console.log('Popover is closing');
  }
});
```

## 与 `<dialog>` 元素的对比

| 特性 | Popover API | `<dialog>` 元素 |
| :--- | :--- | :--- |
| **模态性** | 默认非模态（`auto`/`hint`/`manual`） | 支持模态（`showModal()`）和非模态（`show()`） |
| **堆栈管理** | 维护 auto 和 hint 两个堆栈 | 维护模态堆栈，非模态独立 |
| **轻dismiss** | `auto` 和 `hint` 支持点击外部关闭 | 模态不支持，非模态支持（若配置） |
| **可访问性** | 基础 ARIA 支持，需手动处理焦点 | 内置 `aria-modal` 支持，自动处理焦点陷阱（模态） |
| **适用场景** | 菜单、提示、非模态通知 | 确认对话框、模态表单、模态通知 |

> **最佳实践**：若需要模态交互和严格的焦点管理，优先使用 `<dialog>`。若需要非模态弹出层且希望简化 HTML 结构，使用 Popover API。也可将 `<dialog>` 转换为 Popover 以结合两者优势，但需注意其变为非模态。

[来源1](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) · [来源2](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API/Using) · [来源3](https://developer.mozilla.org/en-US/docs/Glossary/Baseline/Compatibility) · [来源4](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog)
