规避废弃 ARIA 角色Front-End-Checklist 的 aria-deprecated-role 规则实战指南【免费下载链接】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 仓库中的 aria-deprecated-role 规则文档 与 SKILL.md 为主体系统讲解 WAI-ARIA 规范演进中被废弃或抽象化的角色如directory为何危险、如何识别、如何修复以及如何在浏览器辅助功能树、axe/Lighthouse 自动化检查和屏幕阅读器手动验证中确认修复效果。读完本文你将掌握一套可直接复用的优先原生语义 → 检查废弃角色 → 替换现代等价物 → 双通道验证的实战流程。规则背景为什么废弃 ARIA 角色值得单独设立一条规则WAI-ARIA 规范持续演进部分角色因语义不精确、浏览器与辅助技术Assistive TechnologyAT支持不一致而被废弃取而代之的是更精确、兼容性更好的角色定义。Front-End-Checklist 仓库将该检查点归类为accessibility大类下的aria子类优先级priority为 medium、难度difficulty为 intermediate、预计耗时 10 分钟规则的核心定位是Checks for deprecated or abstract ARIA roles to ensure long-term compatibility.即检查页面中是否使用了废弃或抽象的 ARIA 角色以保证长期兼容性。这一检查点同时出现在站点的规则目录packages/content/rules/en/accessibility/aria-deprecated-role.mdx与面向 Agent 的技能包skills/aria-deprecated-role/SKILL.md中——前者是给人类审计者看的完整规则后者是给 AI Agent 在审查渲染后 HTML、交互组件或设计系统模式时使用的操作指引两者共享同一套判定标准与修复策略。哪些角色属于废弃或抽象范畴根据 WAI-ARIA 规范演进历史以下几类角色是这条规则的重点排查对象明确废弃的角色最典型的代表是roledirectory。它曾经被建议用于表示一个目录或条目列表但现代规范建议直接使用原生ul/olli结构无需任何 ARIA 角色。抽象角色abstract roles如command、composite、input、landmark、range、roletype、section、sectionhead、select、structure、widget等。抽象角色只存在于 WAI-ARIA 的角色继承体系role hierarchy中严禁直接出现在 HTML 的role属性里它们的作用仅是为具体角色提供语义分类。浏览器遇到抽象角色时会将其忽略辅助技术无法据此给出有意义的结果。与仓库中相邻的 aria-roles 规则Use valid ARIA role values 互补aria-roles关注角色值是否拼写正确、是否属于规范标准集合而aria-deprecated-role进一步关注角色值虽然合法但已过时或被抽象化。代码示例正误对照规则文档给出了最核心的正误对照示例!-- ✅ Correct: Use modern roles or native elements -- nav aria-labelSite.../nav ul rolelist.../ul !-- ❌ Incorrect: Using deprecated roles -- div roledirectory.../div三个要点nav aria-labelSite使用原生导航元素 aria-label提供可访问名称完全不需要rolenavigation虽然navigation是合法角色但原生nav已隐含该语义这符合 WAI-ARIA 的第一原则——能不用 ARIA 就不用 ARIA。ul rolelist中rolelist属于规范中的合法角色在某些场景如浏览器对列表语义的降级处理下用于显式声明列表语义而roledirectory则是规范明确走向废弃路径的角色。div roledirectory是反面教材既使用了废弃角色又忽略了原生ul/ol语义。从实现角度看仓库中对应规则页 aria-deprecated-role.mdx 的检查提示check prompt明确写道Search the codebase for deprecated ARIA roles likedirectoryor abstract roles that shouldnt be used in HTML.——即审计时先在代码库中全局搜索directory等废弃角色以及不应出现在 HTML 中的抽象角色。为什么这条规则值得重视规则文档从四个维度阐述了废弃 ARIA 角色的危害面向未来Future-Proofing让应用与持续演进的浏览器、辅助技术标准保持兼容。浏览器未来版本可能逐步移除对废弃角色的支持一旦移除无障碍语义将静默失效。可靠性Reliability废弃角色在不同平台、不同设备上的解释往往不一致。现代角色则能确保所有平台对元素角色产生一致的解读。语义准确性Semantic Accuracy现代角色比旧角色提供更精确的含义。例如directory无法准确表达列表结构关系而原生列表语义或rolelist能精确传达项目列表的集合关系。更干净的代码Cleaner Code绝大多数废弃角色都可以被原生 HTML 元素替换如nav替代rolenavigation这是首选的修复方式代码更简洁、可维护性更强。SKILL.md 的Quick Reference进一步补充了三句速记要点可直接用于代码评审沟通废弃 ARIA 角色应替换为现代等价物浏览器未来版本可能放弃对废弃角色的支持使用废弃角色会损害与辅助技术的长期兼容性。修复策略三层递进方案结合 SKILL.md 的 Fix 提示Update deprecated ARIA roles to their modern recommended equivalents or use native HTML elements与规则文档的 Exceptions 部分推荐的修复路径按优先级排列第一层优先原生 HTML 语义Prefer native HTML semantics over ARIA when both are possible; some apparent ARIA failures disappear when the underlying element is corrected.当原生元素与 ARIA 角色都能表达同一语义时无条件选择原生元素。例如!-- 修复前 -- div rolenavigation aria-labelMain.../div !-- 修复后 -- nav aria-labelMain.../nav很多表面上的 ARIA 问题在纠正底层元素本身例如把div换成nav、ul之后会自然消失根本不需要添加 ARIA。第二层替换为现代角色等价物当无法使用原生元素例如需要自定义组件时将废弃角色替换为规范中推荐的现代角色。例如早期一些组件把列表容器标记为roledirectory可替换为rolelist并配合子项rolelistitem抽象角色则直接删除因为它们在 HTML 中毫无意义。第三层拒绝为满足规则而添加 ARIADo not add ARIA only to satisfy the rule if the feature should instead be implemented with a native element or a simpler interaction pattern.这是规则文档中一条容易被误用的边界不允许为了让这条规则通过而刻意添加 ARIA。如果某项功能本应用原生元素或更简单的交互模式实现那么正确做法是重构实现而不是靠 ARIA 打补丁。同时要注意A missing ARIA attribute is not automatically the strongest finding if the control is already semantically broken, unnamed, or keyboard-inaccessible.——如果控件本身已语义破损、无可访问名称或键盘不可达缺失 ARIA 属性未必是最强的发现项应优先修复更根本的问题。与相邻 ARIA 规则的协同审查在 packages/content/rules/en/accessibility/aria-deprecated-role.mdx 的 frontmatter 中该规则声明了四组关联规则relatedRules在实际审计中常被一起审查关联规则协同理由aria-hidden-body同属accessibility/aria领域常一起审查aria-allowed-attr同属accessibility/aria领域常一起审查aria-command-name同属accessibility/aria领域常一起审查aria-required-children同属accessibility/aria领域常一起审查以roledirectory的修复为例删除废弃角色后若列表子项没有rolelistitem或原生li就会触发 aria-required-children 的检查若替换成自定义按钮组件却缺少可访问名称则会触发 aria-command-name。因此废弃角色修复往往不是孤立操作而是整个 ARIA 语义链的重构。标准依据与验证方法对齐的标准规则文档的 Standards 部分明确要求实现对齐两大权威来源WAI-ARIA 1.2以 W3C WAI-ARIA 1.2 规范 为最终标准判定某角色是否废弃、是否抽象以该规范的角色定义与废弃记录为准MDN: ARIA以 MDN 的角色参考文档作为工程实践中的快速对照表。同时强调verify the rendered experience, not only the source code——必须验证渲染后的实际体验而非只检查源代码。这是因为 ARIA 的效果取决于浏览器如何将其映射到辅助功能树源码层面看起来对不等于渲染后用起来对。自动化检查规则文档给出的自动化验证路径检查浏览器辅助功能树accessibility tree或无障碍面板在 DevTools 的 Accessibility 面板中选中相关元素确认其暴露的角色、可访问名称是否符合预期废弃角色在辅助功能树中通常不会暴露任何语义。运行自动化无障碍检查器如 axeDeque 提供规则页 resources 中列出的 axe DevTools或 Lighthouse在适用场景下直接扫描整页。这些工具内置了对废弃/抽象角色的检测逻辑能快速定位roledirectory之类的用法。手动检查纯键盘导航测试对受影响 UI 进行仅键盘操作确认规则在真实交互体验中成立——例如移除废弃角色后Tab 焦点顺序、Enter/Space 触发逻辑是否依旧正常。屏幕阅读器复测若该规则影响了关键交互如自定义列表、菜单、工具栏至少用一个代表性用户流程配合屏幕阅读器如 NVDA、VoiceOver复测一次确认朗读结果与预期语义一致。在 Front-End-Checklist 中的定位与使用方式该规则是站点 Accessibility 检查清单 中的一个条目规则页面的 frontmatter 完整记录了其元数据标题 Avoid using deprecated ARIA roles、描述、分类accessibility / aria、优先级medium、难度intermediate、预计耗时10 分钟、检查/修复/解释/代码评审四类提示词check / fix / explain / codeReview以及权威来源WAI-ARIA 1.2 与 MDN均为 primary authority。面向 AI Agent 的使用场景skills/aria-deprecated-role/SKILL.md 的 aiContext 字段给出了明确触发条件Use when reviewing rendered HTML, interactive components, or design-system patterns related to Avoid using deprecated ARIA roles. Check native semantics first, then inspect keyboard behavior, focus flow, accessible names, and screen-reader output where relevant.即在审查渲染后的 HTML、交互组件或设计系统模式时启用本规则先检查原生语义再检查键盘行为、焦点流、可访问名称以及相关的屏幕阅读器输出。SKILL.md 同时给出了代码评审Code Review的操作口径审查渲染后的标记与交互状态精确标记违反规则的元素、角色、标签、焦点行为或键盘交互并说明如何用浏览器无障碍工具或辅助技术验证修复。实战检查清单完成本文内容后可按下述清单快速执行一轮废弃 ARIA 角色审计全局搜索roledirectory及其他已知废弃角色如早期版本中的roleslider变体用法需对照 WAI-ARIA 1.2 逐一确认排查抽象角色command、composite、input、landmark、range、roletype、section、sectionhead、select、structure、widget是否被直接写在role属性中对每个命中项判断能否用原生元素替代nav、ul/li、table等无法原生替代时替换为 WAI-ARIA 1.2 中的现代等价角色在 DevTools Accessibility 面板确认辅助功能树中的角色映射正确用 axe/Lighthouse 做整页扫描复验对关键交互执行纯键盘 屏幕阅读器抽查全程遵循不为通过规则而添加 ARIA的原则优先重构为更简单的原生实现。通过以上流程你可以系统性地消除废弃 ARIA 角色带来的兼容性隐患让应用在浏览器与辅助技术持续演进的未来依然保持稳定、准确的无障碍语义。【免费下载链接】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），仅供参考