跳转至

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