专项： dialog 与 popover 深度指南

0. 学习目标（可验证）#

• 能说出 dialog 与 popover 的核心区别和各自适用场景
• 能写出 showModal() 打开、close() 关闭、returnValue 取值的完整流程，并区分 cancel 与 close 事件
• 能用 popovertarget/popovertargetaction 声明式触发 popover，并说出 auto 与 manual 的差异
• 能用 command/commandfor 属性不写一行 JS 地控制 dialog 与 popover（并说出旧名 invoketarget/invokeaction 已废弃）
• 能判断一个需求该用 dialog、popover、popover="hint" 还是 details

1. 一句话理解#

dialog 是”需要用户决策的对话框”，popover 是”轻量气泡弹层”。它们都是浏览器原生组件——过去要引一个弹窗库才能做对的事（层级、遮罩、焦点、Esc 关闭），现在写几个 HTML 属性浏览器就替你做对了。

可以把两者类比成日常办公：dialog 是老板把你叫进会议室”必须给个结论才能出来”（模态，阻断其他事务）；popover 是同事凑过来指着你屏幕说了一句”这里点一下”（非模态，说完就走）。类比只帮助建立直觉，两者真正的技术差异见第 6 节对比表。

2. dialog：原生模态框#

2.1 基础用法#

<dialog id="confirmDialog">
  <!-- method="dialog"：提交时自动关闭对话框，不发生真实网络请求 -->
  <form method="dialog">
    <p>确定删除这条记录吗？</p>
    <button value="cancel">取消</button>
    <button value="ok">确定</button>
  </form>
</dialog>

<button id="openBtn" type="button">打开对话框</button>

<script>
  const dialog = document.getElementById('confirmDialog');
  document.getElementById('openBtn').addEventListener('click', () => dialog.showModal());
</script>

要点：

• showModal() 打开模态对话框：自动聚焦到内部可聚焦元素、屏蔽背景交互、自带 Esc 关闭、渲染在顶层（top layer，不受页面 z-index 影响）；
• show() 打开非模态对话框：背景仍可操作，也没有遮罩；
• close() 手动关闭；用户按 Esc 时先触发 cancel 事件（可阻止），未阻止才会关闭并触发 close；
• form method="dialog" 提交时自动关闭，并把被点击按钮的 value 写入 dialog.returnValue。

2.2 关闭后读取用户选择#

<script>
  dialog.addEventListener('close', () => {
    console.log('用户选择：', dialog.returnValue); // 'ok' 或 'cancel'
  });
</script>

returnValue 初始是空字符串；按钮没写 value 时提交值为空。这是”无 JS 也能收集结果”的关键设计——表单语义与关闭动作合二为一。

cancel 与 close 的分工要分清：

2.3 定制遮罩：::backdrop#

/* 只有 showModal() 打开的模态对话框才有 backdrop */
dialog::backdrop {
  background: rgba(0, 0, 0, 0.5);
}

::backdrop 是模态框后面的全屏遮罩。之所以是伪元素而不是普通元素，是因为页面 CSS 本无权”画在文档之外”——遮罩存在于顶层，规范专门为它开了这个口子。

进阶提示：模态对话框的进入/退出动画要配合顶层过渡规则（如 @starting-style 与 transition-behavior: allow-discrete，属 CSS 新能力，详见 css 模块），第一遍了解即可。

3. popover：轻量弹出层#

3.1 基础用法#

<button popovertarget="tip" popovertargetaction="toggle">显示提示</button>

<div id="tip" popover>
  <p>这是一条轻量提示。</p>
  <button popovertarget="tip" popovertargetaction="hide">关闭</button>
</div>

要点：

• popover 属性声明弹出层，默认隐藏，无需写 display: none；
• popovertarget 挂在触发按钮上指向目标 id，popovertargetaction 可选 toggle/show/hide（默认 toggle）；
• 弹出层渲染在”顶层”（top layer），彻底告别 z-index 军备竞赛；
• popover=""（即 auto 状态）点击外部区域或按 Esc 自动关闭（light dismiss，轻关闭）；
• 对应的 JS 方法是 showPopover() / hidePopover() / togglePopover()，可用 'popover' in HTMLElement.prototype 做特性检测。

3.2 auto 与 manual：自动关闭与否#

<!-- auto：点外部就关，适合菜单、提示气泡 -->
<div id="menu" popover>...</div>

<!-- manual：只受显式控制，点外部不关，适合"跟随操作"的面板 -->
<div id="toast" popover="manual">...</div>

3.3 状态事件与样式联动#

popover 打开/关闭会触发 beforetoggle（可阻止）与 toggle 事件，事件对象的 newState/oldState 取值 "open"/"closed"：

<script>
  const tip = document.getElementById('tip');
  tip.addEventListener('toggle', (e) => {
    console.log('从', e.oldState, '变为', e.newState);
  });
</script>

样式上可用属性选择器区分开关状态，再配合过渡动画：

[popover] {
  opacity: 0;
}
[popover]:popover-open {
  opacity: 1;
}

3.4 dialog 与 popover 可以合体#

<dialog popover> 是合法组合：保留对话框语义，同时获得 popover 的显隐控制方式。需要”既能声明式开关、又有对话框语义”的场景可以考虑。

4. Invoker Commands：command / commandfor 声明式控制#

4.1 是什么，为什么重要#

过去打开一个 dialog 或 popover 必须写 JS：btn.addEventListener('click', () => dialog.showModal())。Invoker Commands 把这步也声明化了——按钮上写两个属性，浏览器替你完成调用：

<!-- 无一行 JS：点击按钮以模态方式打开对话框 -->
<button type="button" commandfor="mydialog" command="show-modal">打开</button>
<dialog id="mydialog">
  <p>纯声明式对话框</p>
  <button commandfor="mydialog" command="close">关闭</button>
</dialog>

命名历史务必写对：该特性早期提案使用 invoketarget/invokeaction，现已废弃并更名为 commandfor/command，自 Chrome/Edge 135（2025 年 4 月）起以新名支持。网上教程若出现旧属性名，请一律替换。

4.2 内置命令#

command 的内置关键字（当前规范共 6 个，写错则归入 Unknown 状态，按钮不会产生任何动作）：

注意两点：

• 没有对应非模态 show() 的内置命令——需要非模态打开对话框时仍要写一行 JS（dialog.show()），这是当前规范尚未覆盖的角落；
• command 写成 -- 开头即自定义命令（见 4.4 节），写成其他任何值都会被浏览器忽略。

commandfor 是”更通用的 popovertarget”（MDN 原话），popover 命令与 popovertargetaction 的行为一一对应。新代码建议统一用 command/commandfor，且不要在同一按钮上把两套属性指向不同目标——并存时的优先级规范未给出易读的承诺，混用只会埋坑。

4.3 完整示例：全声明式确认对话框#

<button type="button" commandfor="confirm" command="show-modal">删除文章</button>

<dialog id="confirm">
  <form method="dialog">
    <p>删除后不可恢复，确定吗？</p>
    <button commandfor="confirm" command="request-close">再想想</button>
    <!-- value 会成为 returnValue，配合 close 事件读取 -->
    <button commandfor="confirm" command="close" value="delete">确认删除</button>
  </form>
</dialog>

<script>
  document.getElementById('confirm').addEventListener('close', (e) => {
    if (e.target.returnValue === 'delete') {
      console.log('执行删除');
    }
  });
</script>

行为说明：点击”删除文章”→ 模态打开；“再想想”走 request-close（若有监听 cancel 并 preventDefault()，则不关闭，适合”有草稿未保存”的拦截）；“确认删除”关闭并把 returnValue 置为 delete。整段交互只有读取结果用了 JS。

4.4 自定义命令#

command 以两个连字符开头（如 --like）即为自定义命令：浏览器不会执行内置动作，而是在目标元素上派发 CommandEvent，由你的代码决定行为。这让”按钮发号施令、组件自行响应”的模式无需自己搭事件总线。

<button commandfor="player" command="--play-pause">播放/暂停</button>
<audio id="player" src="demo.mp3"></audio>

<script>
  document.getElementById('player').addEventListener('command', (e) => {
    // e.command 为 '--play-pause'，e.source 为触发按钮
    if (e.command === '--play-pause') {
      e.target.paused ? e.target.play() : e.target.pause();
    }
  });
</script>

4.5 兼容性与降级#

• command/commandfor：Chrome/Edge 135 起可用；Firefox/Safari 的支持情况以 MDN/caniuse 为准。特性检测用 'command' in HTMLButtonElement.prototype；
• 不支持的浏览器中，这两个属性会被忽略、按钮点击无动作——生产环境务必补一段 addEventListener('click', ...) 兜底（检测到支持时不挂即可），或暂时沿用 popovertarget/JS 方案。

5. 前瞻：popover=“hint” 与 interest invokers（新兴，谨慎使用）#

这是 2025 年围绕 popover 生态新增的一组能力，目标是”悬停/聚焦预览”——鼠标划过术语时浮出注释、聚焦图标时提示用途，全程无 JS。

<!--
  popover="hint"：介于 auto 与 manual 之间的第三种状态，
  设计上让 hint 弹层不会被同类型弹层互相顶掉，配合 interest 触发。
  interestfor：悬停/聚焦按钮时对目标 popover 表达"兴趣"并显示它。
-->
<button interestfor="term-tip">CSS</button>
<div id="term-tip" popover="hint">Cascading Style Sheets 的缩写</div>

配套的事件与样式钩子：

• interest / loseinterest 事件：在目标元素上触发，事件对象（InterestEvent）的 source 指向触发元素；
• CSS interest-delay / interest-delay-start / interest-delay-end：控制悬停多久才触发，避免划过即弹的打扰；
• 选择器 :interest-source / :interest-target：仅在”兴趣生效”期间给触发者/目标加样式。

写作与使用纪律：这组能力的属性名经历过调整（早期资料写作 interesttarget，现行规范与 MDN 为 interestfor），且支持面仍然有限，主要落在较新的 Chromium 系浏览器。生产使用前必须：查 MDN/caniuse 确认当前状态；用 'interestfor' in HTMLButtonElement.prototype 做特性检测；不支持时退化为点击触发（popovertarget）。不要臆造具体支持版本号。

6. 使用时机对比#

7. 可访问性要点#

• showModal() 打开时自动聚焦对话框内（无合适元素则聚焦对话框本身），关闭时现代浏览器会把焦点归还给打开前的元素（规范行为）；兼容旧环境或需要指定落点时，再在 close 事件里手动 focus()；
• popover 默认不管理焦点：纯展示提示可以直接用；含表单或需要键盘操作的弹层，改用 dialog；
• 两者都响应 Esc（auto popover 与模态 dialog 原生支持），确保关闭后焦点不悬空；
• 给弹层提供可读名称（aria-labelledby 指向标题），不要只靠视觉位置传达信息。

8. 动手试试#

入门版#

1. 做一个”删除确认”对话框：commandfor+show-modal 打开、close+value 提交、Esc 关闭，并在 close 里打印 returnValue；
2. 做一个 popover 气泡，分别练习 toggle/show/hide 三种 popovertargetaction；
3. 把 popover 改成 popover="manual"，验证”点外部不再关闭”。

进阶版#

1. 用 ::backdrop 定制遮罩，并给对话框加进入动画（了解 @starting-style）；
2. 在 cancel 事件里实现”表单未保存时拦截 Esc 关闭”；
3. 写一个特性检测：支持 commandfor 用声明式，否则退回 addEventListener 兜底，两路行为一致。

9. 常见问题与改进建议#

10. 小结#

初学者记住这三点：

1. 要”必须回应的对话框”用 dialog + showModal()，结果从 returnValue 读；要”轻量即开即关”用 popover + popovertarget；
2. 两者都在顶层渲染，天然没有 z-index 问题，Esc 都能关；
3. command/commandfor 能让按钮零 JS 控制 dialog 与 popover——注意旧名 invoketarget/invokeaction 已废弃。

进阶者还需注意：

• cancel（可阻止）与 close（不可阻止）的分工是做”未保存拦截”的基础；request-close 是对应的声明式命令；
• popover 有 auto/manual/hint 三种状态，轻关闭行为各不相同；interestfor 悬停触发属新兴能力，必须特性检测并保守降级；
• 无障碍上默认焦点策略可用，但 popover 不管理焦点，含交互组件时换 dialog。

11. 下一步#

这两个组件是”结构层就能实现的交互”。下一篇专项 410-HTML5InternationalizationTags 转向国际化：ruby、bdi、bdo 与多语言排版；2023-2025 的其他新元素与新能力（<search>、可定制 select、hidden="until-found" 等）见 440-HTMLNewElementsAndCapabilities。