Modern Web Guidance 实践:用原生 `<dialog>` 构建可访问的模态与非模态对话框

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

Modern Web Guidance 实践:用原生 <dialog> 构建可访问的模态与非模态对话框

本文以 Dialog 指南 为核心,拆解在 modern-web-guidance 项目中如何用原生 <dialog> 元素实现模态/非模态浮层:如何按场景选择浮层类型、如何用 closedby 声明关闭行为、如何守住未保存更改,以及每一条规则背后的可降级策略。读完后你能直接产出一个不需要手写焦点陷阱、不需要 role="dialog"、并且能在旧浏览器上优雅降级的对话框组件,并理解仓库中配套的期望清单与评分器是如何验证这些行为的。

为什么选择原生 <dialog>

原指南给出的第一句结论就是全部设计前提:模态与非模态对话框都应使用原生 <dialog> 元素。因为它已经自带自定义浮层必须手工重建的四件事——无障碍语义、焦点管理、顶层(top layer)渲染和 Esc 处理(guide.md 的 Overview 一节)。

这意味着一大批"最佳实践"在原生 <dialog> 面前反而是错误代码:

常见手写做法 在原生模态对话框中的结论
加 role="dialog"、aria-modal="true" 不要加,原生模态已提供这些语义
手写焦点陷阱(focus trap) 不要写,浏览器自动把页面其余部分变为 inert
关闭时手动把焦点还给触发按钮 不要写,浏览器会返回给 invoker
监听 keydown 处理 Esc 不要写,原生模态自带 Esc 与返回手势关闭
用 open 属性或 show() 打开"模态" 不要用,那样没有 inert、没有 ::backdrop、没有焦点约束

仓库的回归断言也把这些写死成了硬性检查:expectations.md 明确要求"任何 <dialog> 都不得带 role="dialog" 或 aria-modal",并且"模态对话框必须用 showModal() 或 command="show-modal" 打开,且打开时 :modal 匹配"。

第一步:按场景选择浮层类型

指南要求自上而下匹配第一条命中的规则,拿不准就用规则 1。这个顺序本身就是重要的架构决策:先用最"重"的模态,只有明确不需要阻塞页面时才降级为 popover。

规则 1:浮层打断用户并阻塞页面(默认)

适用于确认框、表单、登录、破坏性操作,以及任何只说 "modal"、"dialog"、"lightbox"、"popup" 的需求。

声明式打开方式(推荐):

<button type="button" command="show-modal" commandfor="confirm">Delete</button>

<!-- MANDATORY: no role="dialog" or aria-modal; the native modal already provides them -->
<dialog id="confirm" aria-labelledby="confirm-title">
  <h2 id="confirm-title">Delete this item?</h2>
  <form method="dialog">
    <button value="cancel" autofocus>Cancel</button>
    <button value="delete">Delete</button>
  </form>
</dialog>

浏览器由此提供:页面 inert、焦点包含、顶层渲染、::backdrop、Esc 与返回手势关闭、关闭后焦点回到 invoker。

要点:

  • 不要加 role="dialog"、aria-modal、焦点陷阱、inert 切换或 Esc 监听。
  • 不要用 show() 或 open 属性打开。
  • 要用下文 CSS 阻止页面在背后滚动,细节见 prevent-page-scroll-under-modal-dialog 指南。
  • 不要用 overflow: hidden 或 position: fixed 锁 html / body 的滚动。

command / commandfor 属于 Invoker Commands API,仓库中的 declarative-dialog-popover-control 指南 说明了它的价值:把打开/关闭、焦点管理与 aria-expanded 等无障碍绑定交给浏览器,交互在 HTML 解析完即可用,避免脆弱的样板事件监听。注意该指南的一条硬性约束:同一个按钮上不要同时给同一个浮层写 popovertarget 和 commandfor,否则会双重切换而失灵。

规则 2:面板打开时用户仍要继续操作页面

适用于查找栏、检查器、命令面板、撰写面板这类"语义上仍是对话框,但不该阻塞页面"的场景。

用 <dialog popover> 获得顶层面板 + popover 的关闭行为(auto 支持轻关闭,manual 不支持);只有面板必须不在顶层时才用 dialog.show()。

<button type="button" popovertarget="find">Find</button>
<dialog id="find" popover="manual" aria-labelledby="find-title">
  <h2 id="find-title">Find</h2>
  <input type="search" aria-label="Search">
  <button type="button" popovertarget="find" popovertargetaction="hide">Close</button>
</dialog>

此时页面保持可交互,不会被置为 inert。必须提供可见的关闭按钮(这类面板没有隐式关闭入口);不要用 showModal(),它会阻塞页面。需要阻塞式确认时请回到规则 1。

规则 3:浮层其实不是对话框

菜单、下拉、tooltip、hovercard、toast 都属于这一类。用带 popover 属性的语义元素,而不是 <dialog>:

<button type="button" popovertarget="menu">Actions</button>
<ul id="menu" popover>
  <li><a href="/rename">Rename</a></li>
</ul>

这条规则的实质是:不要把"浮在顶层"当成"是对话框"。把菜单做成 <dialog> 会带来不必要的语义与焦点行为。仓库 demo.html 的第 7 个示例就是这种用法:<ul id="menu" popover class="menu">,用 anchor-name / position-anchor / position-area 做锚定定位。

第二步:确定对话框如何被关闭

关闭策略由 closedby 属性声明,默认值取决于打开方式:若 closedby 缺失或非法,showModal() 表现为 closerequest,其他打开方式表现为 none(guide.md)。

  • 仅 Esc 与返回手势(模态默认):不写,或写 closedby="closerequest"。
  • 还允许点击外部关闭:closedby="any"。
  • 只允许开发者主动关闭(例如有未保存更改的表单):closedby="none",并补一条确认路径。

完整的取值语义可对照 light-dismiss-a-dialog 指南:

  • any:轻关闭(点击 backdrop)、关闭请求(Esc)与开发者调用 dialog.close() 全部可用;
  • closerequest:只有关闭请求与开发者机制可用,这是模态对话框的默认值;
  • none:只有开发者机制能关闭。

同一篇指南还提醒:closedby 不适用于 show() 打开的非模态对话框(没有 backdrop,不会触发轻关闭),也不要用 click 事件承载"关闭前"的关键逻辑,应监听 close 或 cancel。

第三步:可访问名称与初始焦点

指南把这一点列为"必做",因为它是 <dialog> 唯一无法自动提供的语义部分:

  • 必须用 aria-labelledby 指向标题,没有可见标题时用 aria-label;仓库的 expectations.md 第 1 条要求名称非空,且评分器 grader.ts 会同时做静态解析与真实 DOM 的无障碍名称校验(aria-labelledby 中任一 id 的文本非空即算通过)。
  • 必须把 autofocus 放在主控件或第一个字段上。
  • 必须在破坏性确认中把 autofocus 放在安全动作上(如 Cancel、Keep)。
  • 不要写关闭后归还焦点的代码。

demo 的确认框就体现了第三点:破坏性按钮在左、autofocus 落在 Keep it 上。

<div class="actions">
  <button value="destroy" class="danger">Destroy</button>
  <button value="keep" class="primary" autofocus>Keep it</button>
</div>

对应地,评分器的浏览器用例会按下 Escape 关闭对话框后断言焦点回到触发按钮(await expect(trigger).toBeFocused()),这条断言的存在本身就是对"不要手写焦点归还"的反向证明——手写逻辑容易与浏览器行为打架。

第四步:打开与关闭的推荐写法

打开

  • 必须优先用声明式:<button command="show-modal" commandfor="...">。
  • 从脚本打开时用 dialog.showModal()。

关闭

  • 用 <form method="dialog"> 里的按钮,或 command="close"。
  • 显式选择 closedby(any / closerequest / none)。
  • 对需要遵守"未保存更改"逻辑的 Cancel 按钮,用 command="request-close" 或 requestClose():它们会先触发 cancel 事件,并且忽略 closedby。
  • 把 closedby 当作渐进增强:即使没有它,Esc 和移动端返回手势也已经能关闭模态。

<form method="dialog"> 的价值在于:提交按钮的 value 会成为 dialog.returnValue,无需额外事件监听就能区分用户点了哪个按钮。demo 第 2 个示例还展示了表单校验与"取消不校验"的组合:

<form method="dialog">
  <h2 id="form-title">Letter to Margaret</h2>
  <label for="letter">Your letter</label>
  <textarea id="letter" name="letter" rows="3" required>...</textarea>
  <div class="actions">
    <button value="cancel" formnovalidate>Cancel</button>
    <button value="send" class="primary">Send</button>
  </div>
</form>

第五步:在 close 中正确读取 returnValue

这是文档里最容易踩坑、也最容易被忽略的一段细节:

  • 必须在 close 监听器里读 dialog.returnValue 判断用户点了哪个按钮,读完后用 dialog.returnValue = '' 复位。
  • 原因:Esc 与其他关闭请求不会写入值,而各浏览器对"是否清空上一次的值"实现不一致;不复位就会让旧值泄漏。把 '' 语义化为"未选择即关闭"。

demo 中的实现(demo.html):

const formDlg = document.getElementById('form-dlg');
formDlg.addEventListener('close', () => {
  document.getElementById('form-out').textContent =
    `returnValue: "${formDlg.returnValue}"`;
  // Esc sets no value and browsers differ on clearing the old one, so reset after reading
  formDlg.returnValue = '';
});

第六步:用 cancel 守住未保存的更改

这是整个指南技术含量最高的部分,也是仓库示例工程与评分脚本的重心。

事件语义

cancel 用于拦截 Esc 与 request-close。但要清楚它的边界:不要依赖 preventDefault() 去拦截没有用户激活的连续 Esc 按下。

让 closedby="none" 成为渐进增强而非唯一防线

关键洞察是:在缺少 closedby 支持的浏览器里,closedby="none" 会被忽略——Esc 会触发 cancel 然后照常关闭对话框。因此守卫逻辑必须放在 cancel 处理器中,而不能只依赖 closedby="none",这样在 closedby 缺失的环境下保护依然生效。

日常咖啡店示例任务 就是这个场景的实战版:把三张 "Seasonal Favorites" 卡片与 hero 区的 "Order Now" 从跳转链接改成打开模态详情/下单对话框,并且一旦用户改过订单选项,就必须在对话框内的 "Discard changes" 按钮上确认后才能关闭。仓库给出的参考实现(claude-solution.patch)把这一逻辑收敛成一个 syncDismissal():

function isDirty() { return serialize() !== pristineState; }

// Prevent light dismiss and close requests while the order has unsaved changes
function syncDismissal() {
  const dirty = isDirty();
  dialog.setAttribute('closedby', dirty ? 'none' : 'any');
  if (!dirty) setConfirming(false);
}

// Guard unsaved changes for Esc, the back gesture and the Cancel (request-close) button,
// including browsers where closedby is not supported
dialog.addEventListener('cancel', (event) => {
  if (!isDirty()) return;
  event.preventDefault();
  setConfirming(true);
  discardButton.focus();
});

注意 closedby 是动态切换的:干净状态下是 any(可轻关闭),脏状态下变成 none。评分器正是这样断言的——它先通过 makeDialogDirty() 修改 input[type=number] / select / radio / 文本框并派发 input 与 change,然后断言 closedby="none",再按 Esc 断言对话框仍然可见,最后点 Discard 才关闭。

为什么要"告诉用户它为什么没关"

指南的这条规则很容易被当成可选项,其实是无障碍硬要求:cancel 被阻止后,必须给出可见信息说明原因,并让接收焦点的控件用 aria-describedby 引用这条信息。否则焦点移到一个新按钮时,屏幕阅读器只会读出"Discard, button",用户完全不知道发生了什么。

不要让确认把按钮挪到指针下方

这条规则可谓"事故预防条款":为提示信息预留空间(用 visibility 隐藏,而不是 display 或 hidden),并把破坏性按钮放在不移动既有按钮的位置(例如右对齐行里的第一个),这样用户在同一位置再点一次不会误丢更改。

demo 的 CSS 与 DOM 恰好是这条规则的教科书式写法:

/* visibility (not display) keeps the space reserved so showing the message shifts nothing */
#unsaved-note:not([data-show]) { visibility: hidden; }
<!-- 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">
  <!-- First in a right-aligned row, so revealing it moves neither Cancel nor Save -->
  <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>

配套的脚本在 cancel 中显示提示并聚焦 Discard,在 close 中复位全部状态:

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;
});

第七步:背景、样式与滚动锁

用 dialog:modal 区分模态样式

必须样式化 ::backdrop,并用 dialog:modal 只命中模态状态。不要无条件给 dialog 设 display——那会覆盖关闭状态,应限定为 dialog[open]。

demo 中还用了一条容易忽略的定位技巧:模态与 popover 对话框由 UA 居中(position: fixed; inset: 0; margin: auto),而 show() 打开的对话框位于常规流中,需要自己显式选入同样的居中:

/* Modal and popover dialogs are centered by the UA (fixed, inset: 0, margin: auto).
   A dialog opened with show() sits in normal flow, so opt in to the same centering. */
dialog:not(:modal, [popover]) {
  position: fixed;
  inset: 0;
  margin: auto;
}

阻止模态背后的页面滚动

指南把这段 CSS 标为两条规则都必做:

/* MANDATORY (both rules): without them, scrolling over the backdrop or inside the dialog scrolls the page behind it */
dialog:modal {
  overscroll-behavior: contain; /* stops scroll gestures in the dialog chaining to the page */
}
dialog::backdrop {
  overflow: hidden; /* ::backdrop is not a scroll container by default, so it would ignore overscroll-behavior */
  overscroll-behavior: contain;
}

其原理在 prevent-page-scroll-under-modal-dialog 指南 里解释得很清楚:showModal() 会让文档其余部分 inert,挡住点击与焦点,但不阻止滚动。存在两条滚动泄漏路径:

  1. 指针/触摸手势落在 ::backdrop 上,滚的是背后的页面;
  2. 在 <dialog> 内部滚动,一旦到达边界(或内容根本不溢出)就链式传递给背后页面。

按 CSS Overscroll Behavior 规范,overscroll-behavior 适用于所有滚动容器,包括不可滚动的滚动容器。所以:

  • <dialog> 被 UA 样式设为 overflow: auto,本来就是滚动容器,直接加 overscroll-behavior: contain 即可截断链式滚动;
  • ::backdrop 默认 overflow: visible,不是滚动容器,会忽略 overscroll-behavior,必须先 overflow: hidden 把它变成"不可滚动的滚动容器"。

同一篇指南还给出两条禁止项:不要对 dialog::backdrop 或 dialog 用 overflow: clip / overflow: visible(都不建立滚动容器);不要用 html / body 上的 overflow: hidden 或 position: fixed 锁滚动——那会移除根滚动条造成横向布局跳动、可能重置滚动位置,并破坏背后页面上的 position: sticky 元素。

评分器的静态检查(getRules + CSSStyleRule)要求同时存在"dialog:modal(或 dialog)上的 overscroll-behavior: contain"和"::backdrop 上的 overflow: hidden + overscroll-behavior: contain",运行时再通过 getComputedStyle(el, '::backdrop') 断言 overflow 为 hidden、两者的 overscroll-behavior 为 contain(grader.ts)。

第八步:降级策略(三条独立的渐进增强)

指南在 Fallback strategies 一节把三种能力拆开处理,这里逐条落地。

closedby(dialog-closedby)

缺少 closedby 时,模态仍然能用 Esc 和返回手势关闭,只是失去"点击外部关闭"——所以这是优雅降级。若你的 Baseline 目标要求轻关闭,就补下列特性检测兜底:

if (!('closedBy' in HTMLDialogElement.prototype)) {
  // Test the pointer position, not event.target: the <dialog> is also the target for its own
  // padding and the gaps between its children, so a target check would close on those clicks
  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;
  };
  for (const dialog of document.querySelectorAll('dialog[closedby="any"]')) {
    let pressedOutside = false;
    dialog.addEventListener('pointerdown', (e) => { pressedOutside = outside(e, dialog); });
    // Require the press and the release outside, so a text-selection drag that ends on the backdrop does not dismiss
    dialog.addEventListener('pointerup', (e) => { if (pressedOutside && outside(e, dialog)) dialog.close(); });
  }
}

三个细节值得强调:

  1. 必须按指针坐标判断,而不是 event.target。<dialog> 自身的内边距和子元素之间的空隙也以它为目标,用 target 判断会在这些位置误关。
  2. 按下与抬起都要在外部。否则从对话框内部开始、在 backdrop 上结束的文本选择拖拽会误触发关闭。评分器中就有一条专门用例:把鼠标按在对话框中心、移动到 (5, 5) 再抬起,断言对话框仍然可见。
  3. 在"未保存更改"场景中,参考实现会在抬起时重新读取 closedby(dialog.getAttribute('closedby') === 'any'),使兜底逻辑与动态 closedby 切换保持一致。

overscroll-behavior

把滚动包含当作渐进增强,并且不要特性检测:@supports 会在"不溢出的容器上也忽略该属性"的浏览器中误报为支持。

在不强制该行为的浏览器里,对话框内容溢出时 overscroll-behavior: contain 仍然有效,showModal() 也仍然让页面 inert。不要退回 overflow: hidden / position: fixed 的根元素方案。

Invoker Commands(command / commandfor)

如果 Baseline 目标不含 Invoker Commands,保持同一份 HTML,按条件加载 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
}

declarative-dialog-popover-control 指南 补充了两条易错点:

  • 必须检测 HTMLButtonElement.prototype 上的 commandForElement,不要检测 window 或 document。
  • 由于原生 command 事件不冒泡,需要在目标元素上直接监听 command 事件。参考实现正是这样在多张卡片共用同一个对话框时区分来源:
dialog.addEventListener('command', (event) => {
  if (event.command !== 'show-modal') return;
  const source = event.source;
  prepare(source instanceof HTMLElement ? source.dataset.drink ?? DEFAULT_DRINK : DEFAULT_DRINK);
});

该指南同时提醒 polyfill 的局限:它不会像原生那样维护命令按钮的 ARIA 状态(如 aria-expanded),需要自行处理以保证无障碍。

Popover(仅规则 2、3 需要)

{{ FEATURE_FALLBACKS("popover") }} 在仓库中展开为 features/popover.md。核心结论:Popover API 大部分是渐进增强,但顶层提升、轻关闭、popovertarget 触发这三项没有纯 CSS 等价物。需要 polyfill 时按 HTMLElement.prototype 上的 popover 属性做特性检测:

// MANDATORY: Feature detect 'popover' on HTMLElement.prototype.
if (!Object.hasOwn(HTMLElement.prototype, "popover")) {
  import("@oddbird/popover-polyfill");
}

两个 polyfill 特有的坑:

  • 不要在 polyfill 完全加载前的任何代码里使用 popover IDL 属性:它不会被镜像成属性,polyfill 也就识别不到该元素,而且这个属性会永久遮蔽 polyfill 添加的访问器。改用 setAttribute() / removeAttribute()。
  • polyfill 无法定义真实的 :popover-open,只能用 .\\:popover-open 类替代。必须用 :is() 或 :where() 合并两者,否则不支持 :popover-open 的浏览器会丢弃整条规则:
[popover]:is(:popover-open, .\:popover-open) {
  display: block;
}

demo 的降级脚本把两个 polyfill 都放在 try/catch 中按需动态导入,并通过 console.error 报告加载失败,避免浮层彻底不可用而静默失败。

与其他指南的边界:动画、拖拽、重挂载

指南明确要求把这三件事交给专门的指南,不要在对话框指南里重复造轮子:

  • 进出场动画 → animate-to-from-top-layer。该指南要求在过渡列表中必须包含 overlay,并对 display / overlay 使用 transition-behavior: allow-discrete;同时不要把 allow-discrete 写进 transition 简写,否则旧浏览器会丢弃整条声明。
  • 拖拽 → drag。
  • 重挂载(reparenting)→ persistent-top-layer-ui。该指南指出:用 appendChild() / insertBefore() 移动一个已打开的 <dialog>、popover 或全屏元素会隐式移除再插入,导致它们被关闭;应改用原子的 moveBefore(),并在不支持的浏览器里先记录打开状态、移动后手动 showModal() / showPopover() 恢复。

规则速查清单

以下把 guide.md 的 DO / DON'T 浓缩为可勾选项。

结构与语义

  • [ ] 用 <dialog> 承载对话框;菜单/tooltip 用 [popover] 而非 <dialog>。
  • [ ] 每个对话框都有 aria-labelledby(或无语义标题时用 aria-label)。
  • [ ] 不加 role="dialog"、aria-modal、手写焦点陷阱、inert 切换。
  • [ ] 关闭控件使用带可访问名称的原生 <button>。
  • [ ] 对话框标题使用统一一致的标题层级。

打开与关闭

  • [ ] 模态用 command="show-modal" + commandfor,或 showModal()。
  • [ ] 不用 show() 或 open 属性打开模态。
  • [ ] 关闭用 <form method="dialog"> 或 command="close"。
  • [ ] 显式选择 closedby;把 closedby 视为渐进增强。
  • [ ] Cancel 按钮用 command="request-close" / requestClose()。
  • [ ] 在 close 中读 returnValue 后立即复位为 ''。

焦点与未保存更改

  • [ ] autofocus 放在主控件或首个字段;破坏性确认中放在安全动作上。
  • [ ] 不写关闭后归还焦点的代码。
  • [ ] 脏状态下 closedby="none",并在 cancel 中阻止默认行为 + 展示原因 + 聚焦确认控件。
  • [ ] 原因文案通过 aria-describedby 关联到接收焦点的控件。
  • [ ] 用 visibility 预留提示空间,破坏性按钮放在不会移动既有按钮的位置。

样式与滚动

  • [ ] 样式化 ::backdrop,用 dialog:modal 定位模态专属样式。
  • [ ] 不在 dialog 上无条件设置 display;需要时用 dialog[open]。
  • [ ] dialog:modal { overscroll-behavior: contain }。
  • [ ] dialog::backdrop { overflow: hidden; overscroll-behavior: contain }。
  • [ ] 不对 html / body 用 overflow: hidden 或 position: fixed 锁滚动。

仓库如何验证这些规则

modern-web-guidance 不是"只会讲道理的文档",每条指南都配有期望清单、评分器与可运行的示例页面。理解这套验证机制,能帮你判断自己的实现是否真的合规。

期望清单:expectations.md 把指南中最可判定的行为写成 10 条陈述,例如"模态打开时 :modal 匹配"、"关闭后焦点回到 invoker"、"按 Esc 关闭模态,除非设置了 closedby="none""、"按压始于对话框内部、结束于 backdrop 时不关闭"、"有未保存更改时对话框带 closedby="none""、"模态打开时外部内容不可聚焦"、"模态打开时在 backdrop 上或内部滚动不会滚动背后页面"。

评分器:targets/daily-grind/grader.ts 用两层断言落地这些陈述。静态层基于 getHtmlDocuments / getJsProject / getRules(test-fixture.ts):解析 DOM 找 <dialog> 与其可访问名称、用 ts-morph 的 CallExpression 搜索 showModal 调用、用 CSSStyleRule 校验滚动包含声明;浏览器层用 Playwright 打开真实页面,断言角色、:modal 匹配、Escape 后焦点归还、外部元素不可聚焦、以及 getComputedStyle(el, '::backdrop') 的真实计算值。

静态分析规则:src/analyzing/rules/dialog.ts 从"改造旧代码"的方向切入。它的 summary 是"手写的 backdrop 点击关闭监听应改用声明式 <dialog closedby="any">";匹配器 dialogJsMatcher 只在 click / onclick 处理器既调用了对话框的 close()、又做了 target 比较或包围盒坐标判断时才报告,并且用一个 closedBy 特性检测的豁免提前返回,避免把合法的渐进增强兜底误判为遗留代码。规则还配了 verifierRubric 的 keepWhen / dropWhen,用于丢弃误报(例如处理器绑定在专用关闭按钮、而非 backdrop 上)。

这几层证据合起来说明了一个设计取向:指南里的"必须"不是风格偏好,而是可以被静态解析、真实浏览器行为和代码审查三方交叉验证的契约。

结语

原生 <dialog> 已经把模态对话框最难的部分——inert、焦点约束、顶层渲染、Esc 与返回手势、焦点归还——做进了浏览器。因此一个现代对话框组件的工程量,不体现在"补浏览器缺的能力",而体现在三件事上:别重复实现浏览器已有的能力,正确使用 closedby 与 cancel 把"未保存更改"守成渐进增强,以及用两行 CSS 把滚动包含补上。按本文的八步落地,再对照 期望清单 与 评分器 自检,你得到的就不只是一个能弹出来的框,而是一个在旧浏览器上不崩、在屏幕阅读器下能说清、在误点击时不会丢数据的对话框。

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