Front-End-Checklist 无障碍实战让 Modal 对话框对键盘用户完全可用的完整指南【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist本文以 Front-End-Checklist 仓库中的 modal-accessibility 规则为核心骨架系统讲解模态对话框Modal Dialog的可访问性实现从 ARIA 角色与属性、焦点陷阱focus trap、Escape 关闭、关闭后焦点回归到原生dialog元素的现代方案并结合仓库设计系统design-system中基于 Radix UI 的真实 Dialog 实现与测试用例给出可直接落地的前端无障碍实战方案。为什么模态框会成为键盘用户的无形陷阱模态对话框本身的设计意图是打断用户当前任务、强制其先处理模态内容。但如果实现不当它同时会切断键盘用户的导航路径焦点可能停留在背后的页面元素上Tab 键会穿过对话框走进页面深处屏幕阅读器无法获知现在处于模态上下文中用户既无法进入对话框、也无法逃离它。正如规则文档 SKILL.md 与规则正文 modal-accessibility.mdx 中所强调的Without proper focus trapping and keyboard handling, modal dialogs are invisible traps for keyboard users—they cant navigate, cant escape, and cant complete tasks.没有正确的焦点捕获与键盘处理模态对话框对键盘用户而言就是无形的陷阱——他们无法导航、无法逃离、无法完成任务。这条规则在 Front-End-Checklist 中被标记为priority: high高优先级、difficulty: intermediate中等难度、预计耗时 30 分钟分类属于 accessibility / html 下的 components 子类。它要求审查者先检查原生语义native semantics再检查键盘行为、焦点流向、可访问名称与屏幕阅读器输出。快速参考四条不可妥协的基线根据规则文档 rule.md 的 Quick Reference任何可访问的模态框都必须满足以下四点容器上使用roledialog与aria-modaltrue—— 向辅助技术声明这是一个模态对话框背后内容不可交互焦点陷阱—— Tab 只能在模态框内部循环不能逃逸到背后的页面Escape 键关闭并将焦点归还给触发元素aria-labelledby指向模态框标题让屏幕阅读器在进入对话框时立即播报其用途。这四条也是仓库规则数据中的tldr字段内容体现了先记忆基线、再深入实现的审查路径。最小语义骨架role / aria-modal / aria-labelledby / aria-describedby规则文档给出了最简 HTML 示例见 rule.md这是任何模态框的语义起点div roledialog aria-modaltrue aria-labelledbymodal-title aria-describedbymodal-description h2 idmodal-titleConfirm Action/h2 p idmodal-descriptionAre you sure you want to delete this item?/p buttonCancel/button buttonDelete/button /div逐属性解读roledialog告诉辅助技术这是一个对话框角色屏幕阅读器会切换为对话框浏览模式aria-modaltrue声明对话框处于模态状态背后的内容不应被辅助技术导航或交互aria-labelledbymodal-title通过 ID 引用标题元素为对话框提供可访问名称accessible namearia-describedbymodal-description补充一段描述性文本通常是操作确认的说明帮助用户理解对话框的意图。注意一个易错点aria-labelledby引用的元素必须是对话框内的标题而不是对话框本身。相关规则 aria-dialog-name 专门审查对话框是否具有可访问名称这一项两者常常在同一个实现中同时触发问题因此被列为相关规则relatedRules。完整可用的 React 模态框焦点管理与键盘处理全解析仅有语义标记还不够。要真正实现键盘可用还需要程序化的焦点管理与键盘事件处理。规则文档提供了一份可直接复用的 React 实现完整代码见 rule.md其核心逻辑分三个部分1. 打开时保存触发器、关闭时归还焦点useEffect(() { if (isOpen) { triggerRef.current document.activeElement as HTMLElement modalRef.current?.focus() document.body.style.overflow hidden } else { document.body.style.overflow triggerRef.current?.focus() } }, [isOpen])打开瞬间把当前焦点元素即用户激活的按钮/链接存入triggerRef立即将焦点移入模态框容器容器上设置了tabIndex{-1}使其可获得焦点同时通过document.body.style.overflow hidden禁用背景滚动关闭时恢复关闭后调用triggerRef.current?.focus()让焦点回到原点恢复用户的浏览上下文。2. 全局键盘事件Escape 关闭 Tab 焦点陷阱const handleKeyDown useCallback((e: KeyboardEvent) { if (e.key Escape) { onClose() return } if (e.key Tab) { const focusableElements modalRef.current?.querySelectorAll( button, [href], input, select, textarea, [tabindex]:not([tabindex-1]) ) if (!focusableElements?.length) return const first focusableElements[0] as HTMLElement const last focusableElements[focusableElements.length - 1] as HTMLElement if (e.shiftKey document.activeElement first) { e.preventDefault() last.focus() } else if (!e.shiftKey document.activeElement last) { e.preventDefault() first.focus() } } }, [onClose]) useEffect(() { if (isOpen) { document.addEventListener(keydown, handleKeyDown) return () document.removeEventListener(keydown, handleKeyDown) } }, [isOpen, handleKeyDown])Escape直接触发onClose()这是模态框键盘可用的逃生门Tab 陷阱通过querySelectorAll收集容器内所有可聚焦元素按钮、链接、输入框、选择框、文本域、显式tabindex且不等于 -1 的元素计算首尾元素当ShiftTab到达第一个元素时回绕到最后一个当Tab到达最后一个时回绕到第一个——焦点永远不会逃出对话框事件监听只在isOpen为 true 时挂载关闭时自动清理避免内存泄漏。3. 渲染结构backdrop dialogreturn ( div classNamemodal-backdrop onClick{onClose} aria-hiddentrue / div ref{modalRef} roledialog aria-modaltrue aria-labelledbymodal-title tabIndex{-1} classNamemodal h2 idmodal-title{title}/h2 {children} button onClick{onClose} aria-labelClose dialog classNameclose-button × /button /div / )细节要点遮罩层backdrop用aria-hiddentrue从辅助技术树中移除仅作视觉与点击关闭用途关闭按钮使用aria-labelClose dialog提供可访问名称避免屏幕阅读器只读到×。更现代的选择原生dialog元素 showModal()如果你不想手写焦点陷阱HTML 原生dialog元素配合showModal()方法可以自动处理焦点捕获focus trapping与模态语义。规则文档给出了对应实现function NativeDialog({ isOpen, onClose, title, children }) { const dialogRef useRefHTMLDialogElement(null) useEffect(() { const dialog dialogRef.current if (!dialog) return if (isOpen) { dialog.showModal() // Handles focus trapping automatically } else { dialog.close() } }, [isOpen]) return ( dialog ref{dialogRef} onClose{onClose} aria-labelledbydialog-title h2 iddialog-title{title}/h2 {children} button onClick{onClose}Close/button /dialog ) }原生方案的核心收益showModal()自动处理焦点陷阱Tab/ShiftTab 在对话框内循环无需手写querySelectorAll与首尾回绕逻辑dialog元素天然具有roledialog语义且showModal()打开时隐式等同aria-modaltrue按下 Escape 默认触发cancel事件并关闭对话框onClose回调由此触发对话框打开时页面其余部分对辅助技术而言处于 inert 状态。需要留意的是原生dialog的浏览器兼容性已相当完善但在需要对关闭按钮、动画、复杂布局做精细控制时仍可能倾向自研组件或组件库方案见下文仓库实践。无障碍验收清单从检查到验证规则文档总结了完整的验收矩阵见 rule.md需求实现方式ARIA 角色roledialog模态标记aria-modaltrue可访问名称aria-labelledby指向标题焦点陷阱Tab 仅在对话框内循环Escape 键关闭对话框焦点归还关闭后焦点回到触发元素背景滚动对话框打开时禁用自动化检查使用浏览器无障碍工具如 axe、Lighthouse对代表性的渲染状态执行检查。规则文档特别强调要验证的是渲染后的实际体验而非仅凭源码静态判断。手动键盘验证五步法用键盘在触发器上按 Enter/Space打开模态框验证焦点已移动到模态框内部连续 Tab 遍历所有元素——焦点不应逃逸到背景页面按 Escape——模态框应关闭验证焦点回到打开模态框的那个元素。例外与优先级判断Exceptions规则文档明确给出三条审查例外防止机械执行规则造成误报先看渲染结果再定性交互时序、浏览器行为与辅助技术输出往往决定严重程度不应仅凭静态代码的气味就判定为阻塞问题区分优先级并非所有次级无障碍问题都同等重要应优先处理最直接阻碍感知、操作或理解perception, operation, or understanding的问题避免冗余标记如果更简单的语义实现能彻底消除问题就不要为了凑规则而堆砌多余的 ARIA 标记——这也呼应了规则对原生语义优先native semantics first的一贯要求。相关规则文档如 keyboard-navigation.mdx、focus-management.mdx 与模态框无障碍常在同一个实现中共同生效审查时可一并查看。仓库实战design-system 中基于 Radix UI 的 Dialog 实现以上原理在 Front-End-Checklist 仓库自身的组件库中有真实落地。设计系统包 dialog.tsx 基于radix-ui/react-dialog封装了完整的 Dialog 组件族import * as DialogPrimitive from radix-ui/react-dialog import { X } from repo/design-system/icons const Dialog DialogPrimitive.Root const DialogTrigger DialogPrimitive.Trigger const DialogPortal DialogPrimitive.Portal const DialogClose DialogPrimitive.Close该封装导出了Dialog、DialogTrigger、DialogPortal、DialogClose、DialogOverlay、DialogContent、DialogHeader、DialogFooter、DialogTitle、DialogDescription等完整子组件其中几个实现细节与本文所述规则一一对应DialogTitle使用DialogPrimitive.TitleRadix 的 Title 组件会自动将其与DialogContent的aria-labelledby关联无需手工维护 ID 引用DialogDescription使用DialogPrimitive.Description同样自动接入aria-describedby与规则示例中的aria-describedby语义一致DialogOverlay全屏遮罩fixed inset-0 z-50 bg-black/50 backdrop-blur-sm负责视觉遮罩与点击关闭关闭按钮的图标用aria-hiddentrue隐藏、用sr-only文本提供名称这与规则示例中aria-labelClose dialog的做法殊途同归——确保辅助技术读到的是Close而非×焦点可见性样式关闭按钮与内容区都带有focus-visible:ring-2等样式保证键盘焦点清晰可见符合 WCAG 对焦点指示的要求。Radix Dialog 在底层自动处理了焦点陷阱、Escape 关闭与焦点回归这正是规则文档中完整可用的 React 模态框章节想要手写实现的能力——选用成熟的、遵循 WAI-ARIA 的组件库可以大幅降低出错概率。业务层的 ConfirmDialog把规则落到真实交互在业务组件层面仓库提供了可复用的确认对话框 confirm-dialog.tsx它组合了上述 Dialog 原语Dialog open{isOpen} onOpenChange{open (!open ? onCancel() : undefined)} DialogContent showClose classNamemax-w-md onEscapeKeyDown{onCancel} onPointerDownOutside{onCancel} div className{...} AlertTriangle className{cn(h-6 w-6, styles.icon)} aria-hiddentrue / /div DialogHeader classNametext-center DialogTitle{title}/DialogTitle DialogDescription{description}/DialogDescription /DialogHeader DialogFooter classNamesm:grid sm:grid-cols-2 Button variantsecondary onClick{onCancel} {cancelLabel} /Button Button className{styles.confirmButton} onClick{onConfirm} {confirmLabel} /Button /DialogFooter /DialogContent /Dialog值得注意的细节ConfirmDialog支持danger / warning / default三种语义变体危险操作如删除确认默认使用danger样式从视觉上强化操作后果onEscapeKeyDown{onCancel}与onPointerDownOutside{onCancel}明确声明Escape 键和点击遮罩外区域都会走取消逻辑——这正是规则要求的Escape 关闭行为的组件库表达测试用例 design-system.test.tsx 使用screen.getByRole(button, { name: Cancel })和name: Confirm按可访问名称查询按钮并断言回调触发验证了对话框的可访问名称确实可被测试工具解析从侧面印证了名称accessible name这一审查维度在真实测试中的价值。结语一条规则三种实现层次回顾 modal-accessibility 这条高优先级规则它实际上给了开发者三条递进的可落地路径语义层roledialogaria-modaltruearia-labelledby/aria-describedby这是任何方案的地基交互层手写 React 组件时必须覆盖焦点陷阱、Escape 关闭、焦点归还、背景滚动禁用四件事工程化层要么使用原生dialogshowModal()自动获得焦点捕获要么选择像 Radix UI 这样遵循 WAI-ARIA 的组件库如本仓库 dialog.tsx 的封装把高风险细节交给经过大量验证的实现。无论选择哪条路径最终的验收标准都一致用键盘完成打开 → 进入 → Tab 遍历 → Escape 关闭 → 焦点回归的完整旅程并用 axe/Lighthouse 与手动键盘验证对渲染后的真实状态做双重确认。这也正是 Front-End-Checklist 项目中所有无障碍规则共同的审查哲学——验证渲染体验而非只读源码。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Front-End-Checklist 无障碍实战让 Modal 对话框对键盘用户完全可用的完整指南【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist本文以 Front-End-Checklist 仓库中的 modal-accessibility 规则为核心骨架系统讲解模态对话框Modal Dialog的可访问性实现从 ARIA 角色与属性、焦点陷阱focus trap、Escape 关闭、关闭后焦点回归到原生dialog元素的现代方案并结合仓库设计系统design-system中基于 Radix UI 的真实 Dialog 实现与测试用例给出可直接落地的前端无障碍实战方案。为什么模态框会成为键盘用户的无形陷阱模态对话框本身的设计意图是打断用户当前任务、强制其先处理模态内容。但如果实现不当它同时会切断键盘用户的导航路径焦点可能停留在背后的页面元素上Tab 键会穿过对话框走进页面深处屏幕阅读器无法获知现在处于模态上下文中用户既无法进入对话框、也无法逃离它。正如规则文档 SKILL.md 与规则正文 modal-accessibility.mdx 中所强调的Without proper focus trapping and keyboard handling, modal dialogs are invisible traps for keyboard users—they cant navigate, cant escape, and cant complete tasks.没有正确的焦点捕获与键盘处理模态对话框对键盘用户而言就是无形的陷阱——他们无法导航、无法逃离、无法完成任务。这条规则在 Front-End-Checklist 中被标记为priority: high高优先级、difficulty: intermediate中等难度、预计耗时 30 分钟分类属于 accessibility / html 下的 components 子类。它要求审查者先检查原生语义native semantics再检查键盘行为、焦点流向、可访问名称与屏幕阅读器输出。快速参考四条不可妥协的基线根据规则文档 rule.md 的 Quick Reference任何可访问的模态框都必须满足以下四点容器上使用roledialog与aria-modaltrue—— 向辅助技术声明这是一个模态对话框背后内容不可交互焦点陷阱—— Tab 只能在模态框内部循环不能逃逸到背后的页面Escape 键关闭并将焦点归还给触发元素aria-labelledby指向模态框标题让屏幕阅读器在进入对话框时立即播报其用途。这四条也是仓库规则数据中的tldr字段内容体现了先记忆基线、再深入实现的审查路径。最小语义骨架role / aria-modal / aria-labelledby / aria-describedby规则文档给出了最简 HTML 示例见 rule.md这是任何模态框的语义起点div roledialog aria-modaltrue aria-labelledbymodal-title aria-describedbymodal-description h2 idmodal-titleConfirm Action/h2 p idmodal-descriptionAre you sure you want to delete this item?/p buttonCancel/button buttonDelete/button /div逐属性解读roledialog告诉辅助技术这是一个对话框角色屏幕阅读器会切换为对话框浏览模式aria-modaltrue声明对话框处于模态状态背后的内容不应被辅助技术导航或交互aria-labelledbymodal-title通过 ID 引用标题元素为对话框提供可访问名称accessible namearia-describedbymodal-description补充一段描述性文本通常是操作确认的说明帮助用户理解对话框的意图。注意一个易错点aria-labelledby引用的元素必须是对话框内的标题而不是对话框本身。相关规则 aria-dialog-name 专门审查对话框是否具有可访问名称这一项两者常常在同一个实现中同时触发问题因此被列为相关规则relatedRules。完整可用的 React 模态框焦点管理与键盘处理全解析仅有语义标记还不够。要真正实现键盘可用还需要程序化的焦点管理与键盘事件处理。规则文档提供了一份可直接复用的 React 实现完整代码见 rule.md其核心逻辑分三个部分1. 打开时保存触发器、关闭时归还焦点useEffect(() { if (isOpen) { triggerRef.current document.activeElement as HTMLElement modalRef.current?.focus() document.body.style.overflow hidden } else { document.body.style.overflow triggerRef.current?.focus() } }, [isOpen])打开瞬间把当前焦点元素即用户激活的按钮/链接存入triggerRef立即将焦点移入模态框容器容器上设置了tabIndex{-1}使其可获得焦点同时通过document.body.style.overflow hidden禁用背景滚动关闭时恢复关闭后调用triggerRef.current?.focus()让焦点回到原点恢复用户的浏览上下文。2. 全局键盘事件Escape 关闭 Tab 焦点陷阱const handleKeyDown useCallback((e: KeyboardEvent) { if (e.key Escape) { onClose() return } if (e.key Tab) { const focusableElements modalRef.current?.querySelectorAll( button, [href], input, select, textarea, [tabindex]:not([tabindex-1]) ) if (!focusableElements?.length) return const first focusableElements[0] as HTMLElement const last focusableElements[focusableElements.length - 1] as HTMLElement if (e.shiftKey document.activeElement first) { e.preventDefault() last.focus() } else if (!e.shiftKey document.activeElement last) { e.preventDefault() first.focus() } } }, [onClose]) useEffect(() { if (isOpen) { document.addEventListener(keydown, handleKeyDown) return () document.removeEventListener(keydown, handleKeyDown) } }, [isOpen, handleKeyDown])Escape直接触发onClose()这是模态框键盘可用的逃生门Tab 陷阱通过querySelectorAll收集容器内所有可聚焦元素按钮、链接、输入框、选择框、文本域、显式tabindex且不等于 -1 的元素计算首尾元素当ShiftTab到达第一个元素时回绕到最后一个当Tab到达最后一个时回绕到第一个——焦点永远不会逃出对话框事件监听只在isOpen为 true 时挂载关闭时自动清理避免内存泄漏。3. 渲染结构backdrop dialogreturn ( div classNamemodal-backdrop onClick{onClose} aria-hiddentrue / div ref{modalRef} roledialog aria-modaltrue aria-labelledbymodal-title tabIndex{-1} classNamemodal h2 idmodal-title{title}/h2 {children} button onClick{onClose} aria-labelClose dialog classNameclose-button × /button /div / )细节要点遮罩层backdrop用aria-hiddentrue从辅助技术树中移除仅作视觉与点击关闭用途关闭按钮使用aria-labelClose dialog提供可访问名称避免屏幕阅读器只读到×。更现代的选择原生dialog元素 showModal()如果你不想手写焦点陷阱HTML 原生dialog元素配合showModal()方法可以自动处理焦点捕获focus trapping与模态语义。规则文档给出了对应实现function NativeDialog({ isOpen, onClose, title, children }) { const dialogRef useRefHTMLDialogElement(null) useEffect(() { const dialog dialogRef.current if (!dialog) return if (isOpen) { dialog.showModal() // Handles focus trapping automatically } else { dialog.close() } }, [isOpen]) return ( dialog ref{dialogRef} onClose{onClose} aria-labelledbydialog-title h2 iddialog-title{title}/h2 {children} button onClick{onClose}Close/button /dialog ) }原生方案的核心收益showModal()自动处理焦点陷阱Tab/ShiftTab 在对话框内循环无需手写querySelectorAll与首尾回绕逻辑dialog元素天然具有roledialog语义且showModal()打开时隐式等同aria-modaltrue按下 Escape 默认触发cancel事件并关闭对话框onClose回调由此触发对话框打开时页面其余部分对辅助技术而言处于 inert 状态。需要留意的是原生dialog的浏览器兼容性已相当完善但在需要对关闭按钮、动画、复杂布局做精细控制时仍可能倾向自研组件或组件库方案见下文仓库实践。无障碍验收清单从检查到验证规则文档总结了完整的验收矩阵见 rule.md需求实现方式ARIA 角色roledialog模态标记aria-modaltrue可访问名称aria-labelledby指向标题焦点陷阱Tab 仅在对话框内循环Escape 键关闭对话框焦点归还关闭后焦点回到触发元素背景滚动对话框打开时禁用自动化检查使用浏览器无障碍工具如 axe、Lighthouse对代表性的渲染状态执行检查。规则文档特别强调要验证的是渲染后的实际体验而非仅凭源码静态判断。手动键盘验证五步法用键盘在触发器上按 Enter/Space打开模态框验证焦点已移动到模态框内部连续 Tab 遍历所有元素——焦点不应逃逸到背景页面按 Escape——模态框应关闭验证焦点回到打开模态框的那个元素。例外与优先级判断Exceptions规则文档明确给出三条审查例外防止机械执行规则造成误报先看渲染结果再定性交互时序、浏览器行为与辅助技术输出往往决定严重程度不应仅凭静态代码的气味就判定为阻塞问题区分优先级并非所有次级无障碍问题都同等重要应优先处理最直接阻碍感知、操作或理解perception, operation, or understanding的问题避免冗余标记如果更简单的语义实现能彻底消除问题就不要为了凑规则而堆砌多余的 ARIA 标记——这也呼应了规则对原生语义优先native semantics first的一贯要求。相关规则文档如 keyboard-navigation.mdx、focus-management.mdx 与模态框无障碍常在同一个实现中共同生效审查时可一并查看。仓库实战design-system 中基于 Radix UI 的 Dialog 实现以上原理在 Front-End-Checklist 仓库自身的组件库中有真实落地。设计系统包 dialog.tsx 基于radix-ui/react-dialog封装了完整的 Dialog 组件族import * as DialogPrimitive from radix-ui/react-dialog import { X } from repo/design-system/icons const Dialog DialogPrimitive.Root const DialogTrigger DialogPrimitive.Trigger const DialogPortal DialogPrimitive.Portal const DialogClose DialogPrimitive.Close该封装导出了Dialog、DialogTrigger、DialogPortal、DialogClose、DialogOverlay、DialogContent、DialogHeader、DialogFooter、DialogTitle、DialogDescription等完整子组件其中几个实现细节与本文所述规则一一对应DialogTitle使用DialogPrimitive.TitleRadix 的 Title 组件会自动将其与DialogContent的aria-labelledby关联无需手工维护 ID 引用DialogDescription使用DialogPrimitive.Description同样自动接入aria-describedby与规则示例中的aria-describedby语义一致DialogOverlay全屏遮罩fixed inset-0 z-50 bg-black/50 backdrop-blur-sm负责视觉遮罩与点击关闭关闭按钮的图标用aria-hiddentrue隐藏、用sr-only文本提供名称这与规则示例中aria-labelClose dialog的做法殊途同归——确保辅助技术读到的是Close而非×焦点可见性样式关闭按钮与内容区都带有focus-visible:ring-2等样式保证键盘焦点清晰可见符合 WCAG 对焦点指示的要求。Radix Dialog 在底层自动处理了焦点陷阱、Escape 关闭与焦点回归这正是规则文档中完整可用的 React 模态框章节想要手写实现的能力——选用成熟的、遵循 WAI-ARIA 的组件库可以大幅降低出错概率。业务层的 ConfirmDialog把规则落到真实交互在业务组件层面仓库提供了可复用的确认对话框 confirm-dialog.tsx它组合了上述 Dialog 原语Dialog open{isOpen} onOpenChange{open (!open ? onCancel() : undefined)} DialogContent showClose classNamemax-w-md onEscapeKeyDown{onCancel} onPointerDownOutside{onCancel} div className{...} AlertTriangle className{cn(h-6 w-6, styles.icon)} aria-hiddentrue / /div DialogHeader classNametext-center DialogTitle{title}/DialogTitle DialogDescription{description}/DialogDescription /DialogHeader DialogFooter classNamesm:grid sm:grid-cols-2 Button variantsecondary onClick{onCancel} {cancelLabel} /Button Button className{styles.confirmButton} onClick{onConfirm} {confirmLabel} /Button /DialogFooter /DialogContent /Dialog值得注意的细节ConfirmDialog支持danger / warning / default三种语义变体危险操作如删除确认默认使用danger样式从视觉上强化操作后果onEscapeKeyDown{onCancel}与onPointerDownOutside{onCancel}明确声明Escape 键和点击遮罩外区域都会走取消逻辑——这正是规则要求的Escape 关闭行为的组件库表达测试用例 design-system.test.tsx 使用screen.getByRole(button, { name: Cancel })和name: Confirm按可访问名称查询按钮并断言回调触发验证了对话框的可访问名称确实可被测试工具解析从侧面印证了名称accessible name这一审查维度在真实测试中的价值。结语一条规则三种实现层次回顾 modal-accessibility 这条高优先级规则它实际上给了开发者三条递进的可落地路径语义层roledialogaria-modaltruearia-labelledby/aria-describedby这是任何方案的地基交互层手写 React 组件时必须覆盖焦点陷阱、Escape 关闭、焦点归还、背景滚动禁用四件事工程化层要么使用原生dialogshowModal()自动获得焦点捕获要么选择像 Radix UI 这样遵循 WAI-ARIA 的组件库如本仓库 dialog.tsx 的封装把高风险细节交给经过大量验证的实现。无论选择哪条路径最终的验收标准都一致用键盘完成打开 → 进入 → Tab 遍历 → Escape 关闭 → 焦点回归的完整旅程并用 axe/Lighthouse 与手动键盘验证对渲染后的真实状态做双重确认。这也正是 Front-End-Checklist 项目中所有无障碍规则共同的审查哲学——验证渲染体验而非只读源码。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
