Front-End-Checklist 无障碍规则解析禁止在body上使用aria-hiddenaria-hidden-body【免费下载链接】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 无障碍accessibility类别下优先级为 critical 的规则aria-hidden-body任何情况下都不应给文档body元素设置aria-hiddentrue。你将理解aria-hidden的工作原理、它为何会把整个应用对屏幕阅读器用户静音、该问题在模态框场景下如何被意外触发以及如何通过源码审查、无障碍树检查、axe/Lighthouse 与键盘 屏幕阅读器手测完成修复验证。规则速览Quick Reference本规则对应仓库中的规则定义 aria-hidden-body.mdx 与配套技能 SKILL.md其核心结论可以浓缩为三条body元素在任何生命周期阶段都不应有aria-hiddentrue隐藏body会让整个页面从辅助技术assistive technologies简称 AT的视角消失该问题最常见的原因是管理模态框modal状态时本意是锁定背景内容却错误地把aria-hidden加到了body上。在仓库的规则元数据中该规则的优先级为critical严重、难度为intermediate进阶、预计排查时间为10 分钟归类于accessibility/aria子类目。aria-hidden的工作原理为什么加在body上是灾难aria-hidden属性会把一个元素及其全部后代从无障碍树accessibility tree中移除。无障碍树是浏览器向屏幕阅读器等辅助技术暴露页面结构的独立树形结构它决定了 AT 用户能听到什么、能操作什么。将aria-hiddentrue应用到body标签意味着整棵无障碍树被清空——页面上每一个标题、链接、按钮、表单控件以及全部可见文本对屏幕阅读器用户而言都不存在了。这正是本规则的严重性所在参见 aria-hidden-body.mdx 的whyItMatters字段与 rule.md 的原文描述Settingaria-hiddentrueon the body effectively silences the entire application for screen reader users, rendering the site completely unusable.即使页面在视觉上完全正常屏幕阅读器用户也会遇到全站不可访问无法读取任何内容无法与任何控件交互整个服务对 AT 用户关闭体验彻底断裂用户无法导航、阅读或操作应用的任何部分常见实现 Bug通常是某些自动化脚本或 UI 库在模态框打开时试图锁定背景却锁错了目标元素——锁到了body上。从代码结构看仓库将本规则与 aria-hidden-focus.mdx从 aria-hidden 容器中移除可聚焦元素列为常被一起评审的相关规则aria-hidden的误用往往不止影响内容可读性还会连带产生幽灵焦点ghost focus等键盘导航问题。代码示例正确与错误用法对照仓库规则文档给出了直接可对照的 HTML 示例见 aria-hidden-body.mdx 与 rule.md!-- ✅ Correct: Hidden attribute on background content only -- body div idapp-root aria-hiddentrue !-- Main content hidden while modal is open -- /div div idmodal-portal !-- Modal remains visible to AT -- /div /body !-- ❌ Incorrect: aria-hidden on body -- body aria-hiddentrue h1This whole page is invisible to a screen reader/h1 /body要点拆解正确做法aria-hidden只加在需要暂时从 AT 视角隐藏的具体背景容器上示例中的#app-root而模态框内容位于独立的#modal-portal中保持对辅助技术可见错误做法把aria-hidden直接放在body上整个文档连同h1一起对屏幕阅读器隐形该模式与仓库中 modal-accessibility 技能 给出的模态框实现一脉相承在真实组件里aria-hiddentrue只出现在模态框的backdrop遮罩层上模态框主体则使用roledialog、aria-modaltrue、aria-labelledby与tabIndex{-1}保证语义、可访问名称和焦点管理都正确见 rule.md。为什么它会意外发生模态框状态管理的常见陷阱规则文档特别强调这是常见实现 Bug很多自动化脚本或库在模态框打开时会尝试锁定背景滚动或隐藏背景内容常见错误实现包括// ❌ 错误直接作用于 body function lockBackground() { document.body.setAttribute(aria-hidden, true) } // ✅ 正确作用于背景容器或配合 inert 属性 function lockBackground() { document.getElementById(app-root).setAttribute(aria-hidden, true) }从源码结构可以推断正确的锁定对象应当是与模态框平级的背景容器节点而不是document.body。若组件库或自定义脚本把背景锁定实现成了document.body.setAttribute(aria-hidden, ...)就会在模态框打开的整个生命周期内触发本规则属于必须修复的 critical 级问题。例外情况Exceptions规则文档还列出了三条判断边界用于避免为合规而合规见 rule.md优先使用原生 HTML 语义当原生语义与 ARIA 都能实现时优先原生方案很多看似 ARIA 失效的问题在修正底层元素后就自然消失了缺失 ARIA 不是最强发现如果控件本身在语义上就是错的、没有可访问名称或键盘不可访问那么缺少某个 ARIA 属性未必是首要发现不要为了满足规则而堆砌 ARIA如果某个功能本应使用原生元素或更简单的交互模式实现就不应为了过检而添加 ARIA。遵循的标准Standards实现与验证应以权威规范为准而不是只盯着源码看见 aria-hidden-body.mdx对齐WAI-ARIA 1.2规范规则元数据中的主要权威来源对齐MDN 的 ARIA 参考文档关键要求验证的是渲染后的真实体验rendered experience而不只是源代码——因为属性是否真正生效取决于浏览器与辅助技术组合的实际行为。验证方法Verification自动化检查Automated Checks检查无障碍树打开浏览器 DevTools 的 Accessibility 面板Chrome/Edge/Firefox 均提供确认body及其内容节点是否出现在无障碍树中若 body 或大量内容节点从树中消失即命中本规则运行自动化检测工具在适用场景下运行axe DevTools或Lighthouse仓库规则元数据的 resources 字段中明确推荐了 axe DevTools两者都能在渲染后的 DOM 上检测aria-hidden误用可将该检查纳入 CI 流水线的可访问性回归测试中防止组件库升级或脚本改动后回归。手动检查Manual Checks纯键盘导航测试关闭鼠标仅用 Tab / ShiftTab / 方向键走查受影响页面确认焦点顺序合理、每个可聚焦元素都有对应的屏幕阅读器播报屏幕阅读器回归测试如果本规则影响关键交互如模态框打开/关闭流程用一款屏幕阅读器NVDA、VoiceOver、TalkBack 等重新走查一条代表性用户流程确认模态框内容可被朗读、背景内容按预期被隔离而非整体消失特别地在模态框打开状态下检查背景内容是否被隐藏✅ 正常、而整个页面是否仍可被 AT 感知✅ 正常若整页对 AT 静音即违反本规则。与相关规则的协同评审仓库将以下规则与 aria-hidden-body 列为常被一起评审的相关规则见 aria-hidden-body.mdx相关规则关注点aria-hidden-focusaria-hidden容器中不能存在可聚焦后代否则产生幽灵焦点aria-hidden只从无障碍树移除元素不会将其移出 Tab 键顺序decorative-elements装饰性元素的隐藏策略与aria-hidden的边界判断相关aria-text面向 AT 的文本暴露方式aria-allowed-attr哪些 ARIA 属性允许出现在哪些元素上其中 aria-hidden-focus.mdx 明确指出一个关键细节aria-hiddentrue会把元素移出无障碍树但不会把它移出键盘 Tab 顺序——这正是两个规则需要协同检查的原因。在修复body上误用aria-hidden的同时还要确保被隐藏的背景容器内的按钮、链接不会被键盘聚焦到可配合tabindex-1或inert属性处理。在 Front-End-Checklist 项目中的应用本规则在仓库中形成了完整的定义—技能—验证链路适合作为审查清单或 AI 辅助审查的切入点规则内容源aria-hidden-body.mdx 定义了 TL;DR、严重性、检查/修复/解释提示词check / fix / explain / codeReview 四类 prompt以及 WAI-ARIA 1.2、MDN 等权威来源Agent 技能封装skills/aria-hidden-body/SKILL.md 将其封装为可供 LLM/Agent 调用的技能使用场景描述为审查渲染后的 HTML、交互组件或设计系统模式时先检查原生语义再检查键盘行为、焦点流、可访问名称与屏幕阅读器输出详细参考skills/aria-hidden-body/references/rule.md 提供完整的代码示例、影响分析、例外、标准与验证步骤。实际审查时可以遵循技能中定义的检查路径先确认body上是否存在aria-hiddentrue覆盖页面生命周期内的任意时刻而不只是初始渲染若存在按上文验证方法一节定位到具体触发代码常见于模态框状态管理将其从body移到具体的背景容器并用无障碍树检查 键盘测试 屏幕阅读器测试确认修复生效。小结aria-hidden是控制无障碍树可见性的强大工具但它的作用域决定了它绝不能被用在body上——那等于把整个网站对屏幕阅读器用户一键静音。修复的关键是把隐藏范围精确限制到模态框打开时需要隔离的背景容器并通过渲染后验证无障碍树、axe/Lighthouse、键盘与屏幕阅读器测试确认 AT 用户始终能感知和操作你的应用。【免费下载链接】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），仅供参考