原生 `<dialog>` 对话框的可验证验收标准:深度解读 Modern Web Guidance 对话框指南

原创2026-11-12 21:05:431,736 阅读
文章标签:前端文档AI 技能AI 评测Agent 评测人工智能RAGCLI提示工程

原生 <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"。指南的要求分三层:

  1. Cancel 按钮用 command="request-close",它会先触发 cancel 事件,并忽略 closedby——这正是脏表单守卫需要的入口。
  2. 在 cancel 处理器里 preventDefault(),阻止关闭。
  3. 告诉用户为什么没关:显示可见消息,并让接收焦点的控件通过 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 条期望并非纸面约定,它们在仓库里形成闭环:

  1. 期望文本 → expectations.md
  2. 参考实现 → demo.html(7 个场景 + 内联注释对应编号)
  3. 真实任务 → task.md 要求把 “Daily Grind” 咖啡站的 “View Details” 与 “Order Now” 从跳转链接改成打开模态对话框,并在用户改动订单选项后禁止直接关闭,必须在对话框内点 “Discard changes” 才丢弃
  4. 自动评分 → grader.ts,静态断言用 linkedom / cssomnom / ts-morph,运行时断言用 Playwright
  5. 基线校准 → 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 把“最佳实践”变成“可验收标准”的方式。

登录后查看全文
modern-web-guidance-src