原生 `<dialog>` 对话框的可验证验收标准:深度解读 Modern Web Guidance 对话框指南
原生 <dialog> 对话框的可验证验收标准:深度解读 Modern Web Guidance 对话框指南
在 Modern Web Guidance 项目中,guides/ui-components/dialog/expectations.md 用 10 条断言,把“一个做得对的原生 <dialog> 组件”拆成可被自动化校验的行为:accessible name、:modal 匹配、焦点归还、Esc 与 closedby 语义、遮罩点击的指针边界、脏表单保护、背景不可聚焦、禁用多余的 ARIA 角色、滚动不穿透。本文以该文件为骨架,结合同目录的 guide.md、demo.html 与 targets/daily-grind/grader.ts,逐条讲清每条期望背后的平台行为、正确写法、fallback 策略,以及它在 Playwright grader 中如何被验证——读完后你可以直接照着写一个通过全套验收的原生对话框组件。
为什么这 10 条期望值得当作规范来看
在仓库的分层设计里,expectations.md 不是普通文档,而是流水线中间产物:docs/CONTEXT.md 明确把它定义为“SME(人类专家)编写的、可观察断言的自然语言条目列表,作为生成 grader 的输入”,与 guide.md(写给 coding agent 的指导)、demo.html(黄金标准实现)并列为 Stage 2 的三件套。也就是说,guides/ui-components/dialog/expectations.md 里的每一条,最终都会变成 guides/ui-components/dialog/targets/daily-grind/grader.ts 中的静态断言或浏览器运行时断言。
这带来一个很实用的结论:这 10 条既是“验收标准”,也是“实现清单”。它覆盖了原生 <dialog> 最容易踩的十个坑——多写一行 role="dialog"、用 show() 冒充模态、忘了在关闭后清理 returnValue、用 overflow: hidden 锁 body 滚动、用 event.target 判断遮罩点击。
十条期望原文如下(便于逐条对照后文):
| # | 期望 |
|---|---|
| 1 | overlay 是一个 <dialog>,且拥有非空 accessible name(aria-labelledby 或 aria-label) |
| 2 | 模态对话框用 showModal() 或 command="show-modal" 打开,且打开期间 :modal 匹配 |
| 3 | 模态对话框关闭后,焦点回到触发它的元素 |
| 4 | 按 Esc 会关闭打开的模态对话框,除非设置了 closedby="none" |
| 5 | 若存在遮罩点击 fallback,则“在对话框内按下、在遮罩上抬起”不应关闭对话框 |
| 6 | 对话框存在未保存更改时,它具有 closedby="none" |
| 7 | 存在未保存更改时,cancel 请求会让它保持打开,直到用户确认丢弃 |
| 8 | 模态对话框打开期间,其外部内容不可聚焦 |
| 9 | 任何 <dialog> 都不得带 role="dialog" 或 aria-modal |
| 10 | 模态对话框打开期间,在遮罩上或其内部滚动,不会滚动背后页面 |
期望 1–2:用原生 <dialog>,用真正的方式打开它
期望 1:非空 accessible name
第一条期望要的是“语义起点正确”:overlay 必须是 <dialog>,且必须能被辅助技术读出名字。指南中的强制写法是让 aria-labelledby 指向对话框内的标题:
<dialog id="confirm" aria-labelledby="confirm-title">
<h2 id="confirm-title">Delete this item?</h2>
...
</dialog>
没有可见标题时才退化为 aria-label。同时指南要求“所有对话框标题使用一致的标题层级”,避免同一批对话框里混用 <h2> 与 <h4>。
grader 对这条做了双向校验:静态侧在 grader.ts 中用 getHtmlDocuments() 取出目标文件的 HTML,遍历所有 <dialog>,要求 aria-label 非空,或 aria-labelledby 拆分出的 id 中至少有一个能在文档里找到带文本内容的元素——注意它校验的是“解析后非空”,而不是属性是否存在。运行时侧(grader.ts)在真实 DOM 中再次计算 accessible name,并要求 toHaveRole('dialog') 通过。
期望 2:showModal() / command="show-modal",且 :modal 匹配
第二条期望把“模态”钉死在两种打开方式上:声明式的 command="show-modal" + commandfor,或脚本中的 dialog.showModal()。指南明确列出反面写法——不要用 show(),也不要用 open 属性,因为它们不会把对话框提升到 top layer,也不会让页面进入 inert 状态。
声明式写法(来自 demo.html):
<button type="button" class="danger" command="show-modal" commandfor="confirm-dlg">Destroy the creature…</button>
<dialog id="confirm-dlg" aria-labelledby="confirm-title">
<form method="dialog">
<h2 id="confirm-title">Abandon the work?</h2>
<div class="actions">
<button value="destroy" class="danger">Destroy</button>
<button value="keep" class="primary" autofocus>Keep it</button>
</div>
</form>
</dialog>
grader 的实现很有意思:grader.ts 用 ts-morph 做 AST 扫描,查找任意 CallExpression 中 PropertyAccessExpression 名为 showModal 的调用(即 xxx.showModal()),与 HTML 里的 [command="show-modal"] 取“或”关系;运行时再判断 document.querySelector('dialog:modal') 是否存在。这条同时验证了“怎么打开的”和“打开后状态对不对”——如果误用 show(),:modal 不会匹配,测试直接失败。
声明式控制的额外约束
command / commandfor 属于 Invoker Commands,细节在 guides/ui-behaviors/declarative-dialog-popover-control/guide.md:commandfor 指向目标 id,command 指定动作(弹层用 toggle-popover/show-popover/hide-popover,模态用 show-modal,关闭用 close)。有两条容易被忽略的坑:
- 不要在同一个按钮上对同一个 popover 同时使用
popovertarget与commandfor,会双重切换导致行为错乱。 - 不要在 target 元素之外用脚本模拟:native
command事件不冒泡,监听时要直接挂在目标元素上。
关闭按钮同样推荐声明式:command="close"(对应 dialog.close()),或表单内 <form method="dialog"> 的提交按钮——后者会把按钮的 value 写入 dialog.returnValue。
期望 3–5:焦点归还、Esc 语义与遮罩指针边界
期望 3:焦点自动回到触发者
浏览器在模态对话框关闭时会把焦点还给 invoker,因此指南要求 不要 手写“关闭后 return focus”的代码。grader 的验证方式是纯行为驱动:grader.ts 先 trigger.focus() 再 trigger.click(),按 Escape,然后断言 expect(trigger).toBeFocused()。它同时校验了焦点归还的“起点”——触发按钮在打开前必须是实际焦点所在。
期望 4:Esc 关闭,除非 closedby="none"
这条对应 closedby 的默认语义。指南给出的完整规则是:
closedby缺失或值非法时:showModal()打开 → 视作closerequest;其他方式打开 → 视作none。closerequest:仅响应 close request(Esc、移动端返回手势)与开发者调用。any:额外支持 light dismiss(点击遮罩)。none:仅开发者可关闭。
因此在正常场景下 Esc 必然能关,只有显式 closedby="none" 才挡得住。grader 在 grader.ts 中先读取 closedby 属性断言其不等于 none,再按 Escape 并断言对话框隐藏——这也解释了为什么“脏表单”必须动态切换 closedby(见期望 6)。
期望 5:遮罩点击 fallback 的指针边界
这是十条里最容易被写错的一条,也是最体现工程细节的一条。判断“点击遮罩”时,直觉写法是 event.target === dialog,但指南与 demo 都明确反对:
用指针位置判断,而不是
event.target:<dialog>自身的内边距和子元素之间的间隙,事件的 target 也是对话框本身,用 target 判断会在这些区域误关。
正确的 fallback 需要同时满足两个条件——按下在外部、抬起也在外部。demo 中的实现(demo.html):
if (!('closedBy' in HTMLDialogElement.prototype)) {
const outside = (e, dialog) => {
const r = dialog.getBoundingClientRect();
return e.clientX < r.left || e.clientX > r.right || e.clientY < r.top || e.clientY > r.bottom;
};
let pressedOutside = false;
dialog.addEventListener('pointerdown', (e) => { pressedOutside = outside(e, anyDlg); });
// Require press and release outside so text-selection drags don't dismiss
dialog.addEventListener('pointerup', (e) => { if (pressedOutside && outside(e, anyDlg)) anyDlg.close(); });
}
guide.md 的版本更进一步,在 pointerup 时重新检查 closedby,这样带未保存更改的订单不会因为一次拖拽被误关(见 claude-solution.patch 中 if (pressedOutside && outside(e) && dialog.getAttribute('closedby') === 'any') dialog.close();)。
grader 用真实鼠标动作复现了这一场景:grader.ts 取对话框 bounding box 中心点 mouse.down(),移动到 (5, 5) 再 mouse.up(),然后断言对话框仍然可见。这一条只对“存在 fallback”的实现有约束,但一旦写了 fallback 就必须过关。
期望 6–7:脏表单的关闭守卫
这两条是同一套机制的两个侧面:状态上要有 closedby="none",行为上 cancel 请求要能被拦截。
期望 6:脏了就切到 closedby="none"
grader 的 makeDialogDirty() 辅助函数(grader.ts)会依序尝试:input[type="number"] 加一、select 换一项、未选中的 radio 勾上、textarea / input[type="text"] 填值,并派发 input 与 change 事件——即模拟真实用户操作,然后断言 toHaveAttribute('closedby', 'none')。这要求你的实现必须在输入变化时同步属性,而不是只在打开时静态写死。
解决方案补丁中的典型实现(claude-solution.patch):
const serialize = () => new URLSearchParams(new FormData(form)).toString();
let pristineState = '';
const isDirty = () => serialize() !== pristineState;
function syncDismissal() {
const dirty = isDirty();
dialog.setAttribute('closedby', dirty ? 'none' : 'any');
if (!dirty) setConfirming(false);
}
form.addEventListener('input', (event) => {
if (event.target === form.elements.drink) showDrinkDetails(form.elements.drink.value);
syncDismissal();
});
form.addEventListener('change', syncDismissal);
这里用“表单序列化快照对比”判定脏状态,比逐字段比较更省事,也与 form.reset() 天然配合:打开前 prepare() 记录 pristineState,关闭后 form.reset() 并重新记录。
期望 7:cancel 请求保持打开,直到用户确认
关键 API 是 cancel 事件与 requestClose() / command="request-close"。指南的要求分三层:
- Cancel 按钮用
command="request-close",它会先触发cancel事件,并忽略closedby——这正是脏表单守卫需要的入口。 - 在
cancel处理器里preventDefault(),阻止关闭。 - 告诉用户为什么没关:显示可见消息,并让接收焦点的控件通过
aria-describedby引用它,否则屏幕阅读器只会读出“Discard, button”。
demo 的第四段是完整范例(demo.html 与 demo.html):
<dialog id="none-dlg" closedby="none" aria-labelledby="none-title">
<form method="dialog" id="journal-form">
<h2 id="none-title">Captain's journal</h2>
<textarea id="journal" rows="3">I have no friend, Margaret.</textarea>
<!-- Space for this message is always reserved, so showing it does not resize the dialog -->
<p class="note" id="unsaved-note">You have unsaved changes. Discard them, or keep editing.</p>
<div class="actions">
<button type="button" class="danger" command="close" commandfor="none-dlg" id="discard"
aria-describedby="unsaved-note" hidden>Discard</button>
<button type="button" command="request-close" commandfor="none-dlg">Cancel</button>
<button value="save" class="primary">Save</button>
</div>
</form>
</dialog>
noneDlg.addEventListener('cancel', (e) => {
if (journal.value !== initial) {
e.preventDefault();
unsavedNote.toggleAttribute('data-show', true);
discard.hidden = false;
discard.focus();
}
});
noneDlg.addEventListener('close', () => {
unsavedNote.toggleAttribute('data-show', false);
discard.hidden = true;
journal.value = initial;
});
配套的两条 CSS/布局约束非常值得抄进自己的项目:
- 提示文字用
visibility: hidden(demo 中写作#unsaved-note:not([data-show]) { visibility: hidden; })而不是display: none/hidden,始终占位,这样显示时对话框不会重排。 - “Discard” 按钮放在右对齐按钮行的首位,揭示它时 Cancel / Save 都不移动,避免用户在同一位置的第二次点击误触销毁操作。
grader 对第 7 条做了完整交互链验证(grader.ts):弄脏 → Escape 后仍可见 → 点击 Cancel/Close(若 Discard 尚未可见)后仍可见 → 断言 Discard 可见 → 点击后对话框隐藏。换句话说,拦截、提示、确认三段缺一不可。
关于 returnValue 的一个隐蔽 bug
guide.md 专门提示:在 close 监听里读 dialog.returnValue 判断用户点了哪个按钮,读完后必须重置 dialog.returnValue = ''。原因是 Esc 与其他 close request 不会写入值,而不同浏览器是否清除上一次的值并不一致,不重置会让旧值“泄漏”到下一次关闭,把“直接关闭”误判成“确认保存”。demo 的第二段(demo.html)演示了这个模式,并把 '' 约定为“未选择即关闭”。
期望 8–9:不要重复实现浏览器已经做对的事
期望 8:模态打开时外部不可聚焦
showModal() 会让文档其余部分 inert,焦点被困在对话框内。这条期望就是用来防止“自己写 focus trap 又写坏了”的实现。grader 的验证很直接(grader.ts):枚举页面上所有 a[href], button, input, select, textarea 中不在对话框内的元素,逐个 focus(),只要有一个能成为 document.activeElement 就失败。
期望 9:禁止 role="dialog" 与 aria-modal
这条是“少即是多”的典型:原生模态 <dialog> 已经自带 dialog 角色与模态语义,手写 role="dialog" / aria-modal="true" 属于重复语义,指南用 MANDATORY 注释标出。grader 的静态检查更严格——grader.ts 断言 dialog.hasAttribute('role') 为 false,也就是说任何 role 值都不接受,不只是 dialog。
同一组反模式还包括:手写 focus trap、手动切换 inert、手写 Esc 处理器。指南的原话是“浏览器已提供 inert 页面、焦点约束、top layer、::backdrop、Esc 与返回手势关闭、焦点归还”。
期望 10:滚动不穿透背后的页面
这是唯一一条纯 CSS 的期望,也是最容易被“锁 body”这种老办法带偏的一条。指南的结论是:inert 只挡点击与焦点,不挡滚动,于是存在两条泄漏路径——在 ::backdrop 上滚动会滚动背后页面;在对话框内滚到边界(或内容本来就不溢出)会滚动链到页面。
修复只需要两条声明(demo.html):
dialog:modal {
overscroll-behavior: contain; /* 阻止对话框内的滚动手势链到页面 */
}
dialog::backdrop {
overflow: hidden; /* ::backdrop 默认不是滚动容器,否则会忽略 overscroll-behavior */
overscroll-behavior: contain;
background: light-dark(rgb(15 23 42 / 0.45), rgb(0 0 0 / 0.65));
}
overflow: hidden 那行不是笔误:guides/ui-behaviors/prevent-page-scroll-under-modal-dialog/guide.md 解释了规范细节——overscroll-behavior 作用于所有滚动容器,包括“当前不可滚动”的滚动容器;而 ::backdrop 默认 overflow: visible,因此不是滚动容器,会直接无视 overscroll-behavior。同理,overflow: clip 也不行。
grader 对这条做了静态与运行时双重校验:静态侧(grader.ts)用 cssomnom 解析 CSSStyleRule,要求存在 dialog:modal(或 dialog)规则含 overscroll-behavior: contain,且存在 ::backdrop 规则同时含 overflow: hidden 与 overscroll-behavior: contain;运行时侧(grader.ts)通过 getComputedStyle(el) 与 getComputedStyle(el, '::backdrop') 断言三个计算值分别为 contain / contain / hidden。注意它校验的是计算值,所以写在 dialog 通用选择器上同样有效。
不要用 overflow: hidden 锁 html / body
指南明确禁止:修改根元素 overflow 会移除页面滚动条(引起水平布局位移)、可能重置或跳动滚动位置、并破坏底层页面上的 position: sticky。这类“锁滚动”方案在视觉上往往显示正常,但代价是整页重排。
如何选择叠层类型:三条规则定生死
guide.md 给了一个“按顺序匹配第一条”的决策树,它决定了你到底该用 <dialog> 还是 [popover]:
| 规则 | 场景 | 写法 |
|---|---|---|
| Rule 1(默认) | 确认框、表单、登录、破坏性操作等打断用户且阻塞页面的叠层 | <dialog> + command="show-modal" 或 showModal() |
| Rule 2 | 页面仍可交互的面板:查找栏、检查器、命令面板、撰写窗格 | <dialog popover>(auto 轻关,manual 不轻关);仅在必须脱离 top layer 时用 show() |
| Rule 3 | 菜单、下拉、tooltip、hovercard、toast——语义上根本不是对话框 | 语义元素 + popover 属性 |
Rule 2 的关键取舍是“不要把面板做成模态”:用 popover 让它获得 top layer 与轻关闭能力,但页面保持可交互、不被 inert。同时必须提供可见关闭按钮,并不要用 showModal()。
Rule 3 的 demo(demo.html)用 <ul popover> 做章节菜单,并配合 position-area / position-anchor 把菜单锚定到触发按钮上,明确说明“不是所有叠层都是对话框:没有模态、没有焦点陷阱,只有轻关闭”。
还有一个样式陷阱值得单独提:不要无条件给 dialog 设 display。display 会覆盖浏览器的关闭态样式,导致对话框“永久可见”。正确做法是 dialog[open] 限定作用域。demo 中则示范了另一种场景——show() 打开的对话框位于普通流,需要自己居中(dialog:not(:modal, [popover]) { position: fixed; inset: 0; margin: auto; }),而模态与 popover 的对话框由 UA 自动居中。
Fallback 与 Baseline:把新特性当渐进增强
guide.md 的 fallback 章节用三个宏(BASELINE_STATUS、FEATURE_FALLBACKS)标注了各特性的可用性,其数据来源是 src/core/baseline.ts 中的 getFeatureStatus()——它从 web-features 与浏览器兼容数据计算 baseline 与 baseline_low_date,再映射为 “Newly available / Widely available / Limited availability”。指南对这些特性统一采取“缺失即降级、不做硬依赖”的策略。
closedby
缺少 closedby 时,模态对话框仍能用 Esc 与返回手势关闭,只丢失“点击外部关闭”,因此是优雅降级。注意 closedby="none" 也会被同样忽略:Esc 触发 cancel 然后关闭。结论很重要——未保存更改的保护必须写在 cancel 处理器里,而不能只依赖 closedby="none",否则在不支持 closedby 的浏览器上完全失效。
Invoker Commands
polyfill 的加载必须做特性检测,且检测点必须是接口原型:
// MANDATORY: feature detect on HTMLButtonElement.prototype and load only when native support is missing
if (!('commandForElement' in HTMLButtonElement.prototype)) {
import('invokers-polyfill'); // npm install invokers-polyfill
}
demo 中还给出了 CDN 变体(https://esm.run/invokers-polyfill 与 @oddbird/popover-polyfill),并注明 CDN 写法仅供 demo、生产环境建议打包。需要注意 polyfill 不会像原生浏览器那样自动维护 aria-expanded 等 ARIA 状态,需要自行补上(详见 guides/ui-behaviors/declarative-dialog-popover-control/guide.md)。
overscroll-behavior
这条不能特性检测:@supports (overscroll-behavior: contain) 与 CSS.supports('overscroll-behavior', 'contain') 在所有现代浏览器都返回 true,即使它们只在内容溢出时才生效。因此指南要求把它当渐进增强处理:不支持“非滚动容器”语义的浏览器里,对话框自身内容溢出时仍然阻止滚动链,showModal() 仍然保持页面 inert——这已经足够好,不要退回 overflow: hidden。
从期望到测试:一个 guide 的验收闭环
这 10 条期望并非纸面约定,它们在仓库里形成闭环:
- 期望文本 → expectations.md
- 参考实现 → demo.html(7 个场景 + 内联注释对应编号)
- 真实任务 → task.md 要求把 “Daily Grind” 咖啡站的 “View Details” 与 “Order Now” 从跳转链接改成打开模态对话框,并在用户改动订单选项后禁止直接关闭,必须在对话框内点 “Discard changes” 才丢弃
- 自动评分 → grader.ts,静态断言用 linkedom / cssomnom / ts-morph,运行时断言用 Playwright
- 基线校准 → patches/zero-passrate.patch(该文件为空,意味着校准以未改动的原始应用为“零通过率”基线),与
claude-solution.patch、codex-solution.patch、antigravity-solution.patch三个黄金补丁对齐
这套结构的价值在于“期望不能空转”:如果一条期望无法被写成可失败、可通过的断言,它就不该写进 expectations.md。expectations.md 的 10 条恰好全部具备这种可验证性——它们描述的都是外部可观察的行为,而不是内部实现细节。
实现自查清单
按上面十条走一遍,你的对话框大概会长成这样:
- [ ] 叠层元素是
<dialog>,有aria-labelledby(或aria-label),标题层级统一 - [ ] 模态用
command="show-modal"/showModal()打开,绝不用show()或open属性冒充 - [ ] 不写
role="dialog"、aria-modal、手写 focus trap、手写inert切换、手写Esc关窗 - [ ] 主控件或首个字段加
autofocus;破坏性确认把autofocus放在安全动作上 - [ ] 关闭按钮用原生
<button>且有可访问名称;能声明式就用command="close" - [ ]
closedby显式选择:any(含点击外部)/closerequest(默认,仅Esc)/none(仅代码关闭) - [ ]
close回调里读returnValue后立即重置为'' - [ ] 脏状态下动态设置
closedby="none",Cancel 用command="request-close",在cancel中preventDefault() - [ ] 拦截时给出可见原因,并用
aria-describedby让焦点落点(如 Discard)关联该说明 - [ ] 提示区域用
visibility占位;“Discard” 放在按钮行首位,避免布局位移导致误点 - [ ] 遮罩 fallback 用指针坐标判断,且要求
pointerdown与pointerup都在外部,抬起前复核closedby - [ ]
dialog:modal { overscroll-behavior: contain; }+dialog::backdrop { overflow: hidden; overscroll-behavior: contain; } - [ ] 不在
html/body上锁overflow或position: fixed - [ ] 不给
dialog无条件设display,需要时用dialog[open]限定 - [ ] Invoker Commands / Popover 的 polyfill 按接口原型特性检测后条件加载
把这套清单与 guides/ui-components/dialog/expectations.md 对照阅读,你会发现每条 CSS 与 JS 都对应一条可被机器判定的断言——这正是 Modern Web Guidance 把“最佳实践”变成“可验收标准”的方式。