Dialog 组件契约¶
意图¶
Dialog 在当前页面之上呈现一个模态任务。它负责进入和退出该模态焦点上下文的过渡,以便键盘和辅助技术用户从可见内容内部开始,并在任务关闭时返回调用上下文。
本记录描述 Dialog 的组件局部焦点生命周期。共享的关闭机制、图层排序、公共 API 准入以及运行时资源所有权仍归其当前所属的 family 与 architecture 所有者。
兼容性与迁移¶
- 已发布默认行为:保留。
- 兼容性类别:记录已发布的原生模态与内联预览拆分。
- 受控/非受控行为:Dialog 可见性保持受控。
- 迁移决策:无;当前焦点生命周期被显式化。
所有权边界¶
拥有
- 原生模态变为可见后的初始焦点;
- 默认 DialogHeader 标题焦点目标;
- 模态关闭时焦点返回外部调用元素;
- 在内联文档渲染中抑制模态焦点行为。
不拥有 / 非目标
- Escape、背景层、嵌套和最顶层图层关闭——由
family:overlay-dismissal和architecture:layer-runtime所有; - 后代组件上 autofocus props 的公共准入或命名——由这些组件和
architecture:public-component-api所有; - 焦点环外观和模态检测——由无障碍与交互权威所有;或
- 面向所有 overlay 的通用焦点管理 API。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 默认值 | 所有者 | 稳定性 |
|---|---|---|---|---|---|
| visibility | open, closed | 受控模态是否呈现 | 由调用方控制 | component:Dialog |
稳定 |
| presentation | native modal, inline preview | 原生 dialog 行为与非模态文档渲染的相对关系 | 原生模态 | component:Dialog |
稳定 |
| initial-focus request | eligible descendant, default title, native fallback | 模态呈现后焦点从哪里开始 | 存在时 DialogHeader 标题 | component:Dialog 以及后代所有者 |
稳定结果 |
| invoking focus | focusable external trigger, unavailable trigger | 关闭后若仍可到达则恢复上下文 | 尽可能恢复 | component:Dialog |
稳定结果 |
行为与布局契约¶
| ID | 候选不变量 | 依据 | 草案评审状态 |
|---|---|---|---|
| FR1 | 原生 Dialog MUST 在应用其组件自有初始焦点请求之前,成为可见的模态。 | 已发布的 showModal() 顺序与后代焦点行为 |
已定稿 |
| FR2 | Dialog MUST 遵循合格的后代初始焦点请求。只有当请求的渲染目标位于活动 Dialog 内、既未隐藏也非惰性,并且在选择运行时能够接收程序化焦点,该请求才算合格。当没有渲染出非默认的合格请求时,DialogHeader 提供其标题作为默认值。多个非默认请求之间的排序未指定(AV3)。 | 已发布的 DialogHeader 与后代 autofocus 行为 | 已定稿 |
| FR3 | 当不存在合格的后代请求时,Dialog MUST 保持原生 dialog 的有效初始焦点行为,而不是将焦点移到模态外部。 | 原生模态语义与已发布回退 | 已定稿 |
| FR4 | 关闭原生 Dialog 时,若发起模态框的外部元素仍保持连接且可接收焦点,则 MUST 将焦点返回给该元素。后代挂载焦点 MUST NOT 替代该返回所有者。 | 已发布的触发返回意图与回归历史 | 已定稿 |
| FR5 | 内联渲染 MUST NOT 打开模态框、应用模态初始焦点、捕获焦点,或像模态框已关闭那样返回焦点。 | 已记录的 isInline 预览行为 |
已定稿 |
| FR6 | 初始焦点选择 MUST 遵循渲染出的合格后代,而非私有组件类型或仅基于源码的假设。 | 可组合后代契约 | 已定稿 |
| FR7 | 原生模态 Dialog MUST 通过 Core 的共享焦点区域模块成为一个焦点区域:Tab 从其最后一个可 Tab 到的控件将焦点移动到其第一个,Shift+Tab 从其第一个移动到其最后一个,因此焦点永远不会离开模态框而进入浏览器自身界面。无论是否按下 Alt(Option),Tab 和 Shift+Tab 都会循环,因为 Safari 会在 Option+Tab 时移动焦点;与 Ctrl 或 Meta 组合的 Tab 则传递给浏览器。当 Dialog 从另一个 Dialog 打开时,持有焦点的最内层 Dialog 响应 Tab。 | 所有者决定 DEC-2 | 已定稿 |
| FR8 | 在服务器端处于打开状态的模态 Dialog 在 hydration 之前以关闭状态渲染(没有打开样式、没有 aria-modal,即关闭 Dialog 的标记),并在 hydration 之后的渲染中打开,这是它第一个可以成为模态的渲染;它绝不会声称自己未拥有的模态性(spec:AST-020 FR1,WCAG 2.2 SC 4.1.2)。内联 Dialog 不是模态的,并且按原样渲染。服务器渲染和 hydration 渲染产生相同的标记(spec:AST-013 FR9),并且 hydration 后的打开是确定的,没有进入动画;后续打开和关闭照常动画(spec:AST-013 FR13)。 |
spec:AST-020 FR1 |
已定稿 |
| FR9 | 在所有指针上,模态背景层都是主题的 --color-overlay 暗色,且无模糊(没有 backdrop-filter);在强制颜色模式下,对话框保持可见边缘(系统颜色边框),使其与页面保持区分。全屏 Dialog(variant="fullscreen")覆盖页面且不绘制背景层。 |
所有者决定,2026-10-25:背景层在所有指针状态下保持由主题控制且不模糊。 | 已定稿 |
允许的变体¶
- AV1 — 初始目标。 当所有者暴露了支持的意图时,表单控件、操作、标题或其他合格后代可以作为初始目标。
- AV2 — 无请求。 如果不存在合格请求,浏览器原生选择可能有所不同,前提是焦点不会逃逸出活动模态框。
- AV3 — 多个请求。 调用方应指定一个预期的初始目标。多个同时请求之间的冲突排序不是公开 API 的承诺。
- AV4 — 不可用的调用者。 当调用者被移除或无法再接收焦点时,Dialog MUST 仍然无错误地关闭;在该状态下,它无需恢复焦点。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 带 DialogHeader 的原生模态 | 焦点应用前模态可见;标题获得默认焦点 | 更早的受支持请求可能胜出 |
| 带显式后代请求的原生模态 | 所请求的合格后代获得焦点 | 后代类型与位置 |
| 无请求的原生模态 | 焦点保持在有效的原生模态行为范围内 | 浏览器选择的合格后代 |
| 模态关闭 | 已连接的调用元素重新获得焦点 | 调用者不可用时不再恢复焦点 |
| 在模态边缘按 Tab 或 Shift+Tab | 焦点在模态内回绕到另一端 | 哪些控件可被 Tab 聚焦 |
| 内联预览 | 周围页面焦点保持不变 | 内联内容与布局 |
无障碍契约¶
- AR1 — 焦点进入可见的模态内容。 初始焦点 MUST NOT 指向隐藏的模态前内容,也不得停留在活动模态后方。
- AR2 — 焦点返回上下文。 关闭原生 Dialog MUST 将焦点恢复到仍然连接的外部调用上下文(当该上下文可以接收焦点时)。
- AR3 — 初始目标保持可感知。 可通过编程方式聚焦的标题或控件 MUST 保留其可访问角色、名称和可操作性。
设计关系¶
Dialog 的焦点时机与目标位置并不规定标题样式、模态尺寸、动效或视觉层级。这些仍由 Dialog 的组件设计和主题所有者负责。FR9 设置背景层的外观。
系列与系统关系¶
family:overlay-dismissal决定接受哪个关闭请求,并确保一次 Escape 按键只影响最顶层的相关层。architecture:layer-runtime负责模态层排序和共享生命周期。architecture:react-component-runtime负责节点/资源替换的安全性。architecture:interaction-modality的 INV1 决定初始焦点以及关闭时返回的焦点是否显示共享焦点指示器;Dialog 的Dialog.a11y.browser.spec.ts在指针和键盘输入后对两者进行验证。- 该组件负责 Dialog 模态焦点生命周期中的目标位置与返回结果。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计部分 |
|---|---|---|---|---|
| FR1–FR3, AR1 | 共享模态对话框绑定,位于 Dialog.a11y.test.tsx 和 Dialog.a11y.chromium.spec.ts;本地 DialogHeader 焦点测试 |
标题默认焦点、显式后代、无请求 | 当焦点在原生模态生效前被应用、未命中声明的目标,或在原生回退时离开可见模态时,共享契约失败 | audit:Dialog/accessibility |
| FR4, AR2 | 共享模态对话框浏览器绑定,外加调用者不可用时的本地关闭测试 | 外部触发器、后代挂载焦点、已移除触发器 | 当后代焦点取代返回所有者时,共享契约会记录当前出现的确切失败;本地测试确保在调用者被移除后关闭操作仍然安全 | audit:Dialog/behavior |
| AR2 | Dialog.test.tsx 中的 "unmounting while open" 用例 |
对话框仅在打开时渲染并由自身操作卸载;随其视图一起移除;焦点先移到别处;StrictMode | 若打开的对话框卸载后焦点留在页面 body 上,或焦点被拉回用户已移开的位置,则失败 | audit:Dialog/behavior |
| FR5 | 内联 Dialog 测试 | DialogHeader 和可聚焦子元素 | 内联预览窃取焦点或调用原生模态方法 | audit:Dialog/behavior |
| FR6, AR3 | 共享模态对话框绑定,外加本地组合操作焦点夹具 | DialogHeader 标题、TextInput、操作按钮 | 焦点依赖于私有的 React 子类型,或从目标上剥离语义 | audit:Dialog/public-api |
| FR7 | Dialog.test.tsx、AlertDialog.test.tsx 和 CommandPalette.test.tsx 的焦点区域套件,以及 useFocusTrap.test.tsx 的 “useFocusTrap chorded Tab” |
最后一个和第一个可 Tab 到的控件、Dialog 嵌套 Dialog、内联 | 从最后一个控件按 Tab 会离开模态,或外部 Dialog 响应了内部 Dialog 的 Tab | audit:Dialog/accessibility |
| FR8 | Dialog.ssr.test.tsx |
在服务端打开;水合;已关闭 Dialog 的标记 | 服务端渲染的打开状态带有 aria-modal、打开样式或与关闭状态不同的标记,出现水合错误,水合后没有 showModal(),水合后立即打开时出现进入动画,或稍后打开时没有进入动画——均视为失败。 |
audit:Dialog/accessibility |
| FR9 | modalBackdrop.test.tsx;Chromium 和 WebKit 中的 ModalBackdrop.a11y.browser.spec.ts |
手机宽度下的手指;桌面宽度下的鼠标;两种指针下的强制颜色;强制颜色下的全屏 Dialog | 在任一宽度下背景上的 backdrop-filter,强制颜色下没有可见边缘,或全屏 Dialog 出现边缘,均视为失败。 |
audit:Dialog/accessibility |
决策日志¶
DEC-1 — Dialog 拥有焦点时机;后代组件拥有焦点意图¶
参考: component:Dialog/DEC-1
决策者: 待所有者审核
Dialog 会等到原生模态呈现完成后再应用所选的请求。 后代组件拥有其支持的焦点意图;当前使用的 DOM 标记是实现证据,而非永久性或新认可的公共 API。
DEC-2 — 每个模态呈现都通过同一个模块成为焦点区域¶
参考: component:Dialog/DEC-2
决策者: cixzhang,2026-10-28
模态表面按照 APG 模态对话框模式描述的方式约束 Tab:Tab 和 Shift+Tab 在模态的控件之间移动,并在两端循环。Core 的共享焦点区域模块提供了这种约束:Tab 约束由 useFocusTrap 实现,适用于 Drawer 和 Popover。每个模态呈现都应用同一个模块,而不是把 Tab 留给浏览器:Dialog,以及通过 Dialog 应用该模块的 AlertDialog 和 CommandPalette,还有模态 BottomSheet、Lightbox 和模态 Drawer。循环逻辑中的缺陷在该模块中修复,而不是在组件中绕过。唯一的例外是已弃用的 BottomSheetSwitcher(DEP-0015)中的一个步骤:它在 component:BottomSheetSwitcher/DEC-1 下保留原生约束。
已否决:将 Tab 交给原生 showModal(),这会把焦点从模态内部移到浏览器自身的界面。
开放问题¶
无。DEC-2 确定了焦点约束。
内容边界¶
本文件不会重复 Dialog 的 props 表、关闭规则、视觉设计、私有焦点标记、审计结果或实现计划。消费者语法保留在 Dialog.doc.mjs 中;实现修复工作独立于本契约。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx