Rome useAriaPropsForRole 规则详解强制 ARIA 角色必备属性【免费下载链接】toolsUnified developer tools for JavaScript, TypeScript, and the web项目地址: https://gitcode.com/gh_mirrors/to/tools本文以 Rome 官方文档 website/src/pages/lint/rules/useAriaPropsForRole.md 为核心结合仓库中 RomeUnified developer tools for JavaScript, TypeScript, and the web的源码实现与测试用例深入讲解useAriaPropsForRole这一无障碍a11ylint 规则它强制带有 ARIA 角色的元素必须拥有该角色所要求的所有 ARIA 属性并逐步拆解其工作原理、常见误用场景、修复方法以及如何在项目中启用、配置与禁用。读完本文你将能在实际 JSX/TSX 代码中准确识别并修复此类可访问性问题并理解 Rome 如何基于 WAI-ARIA 规范数据模型实现这一检查。规则概览useAriaPropsForRole是 Rome 在v11.0.0引入的一条 a11y无障碍lint 规则归属于lint/a11y/useAriaPropsForRole诊断类别见 crates/rome_diagnostics_categories/src/categories.rs并且被 Rome 官方标记为recommended推荐启用。规则核心语义一句话概括强制带有 ARIA 角色的元素必须拥有该角色所要求的所有 ARIA 属性。在实际开发中很多开发者会给元素加上role属性来声明其语义角色例如把span改造成复选框、标题、滑块等却常常遗漏 WAI-ARIA 规范中该角色**必需required**的状态属性。例如span rolecheckbox缺少aria-checked就会让屏幕阅读器无法获知该复选框是否被选中——这正是 WCAG 4.1.2「名称、角色、值Name, Role, Value」所要求的内容。规则判定逻辑规则检查过程可分为三步确定检查范围规则只针对 JSX 元素AnyJsxElement且仅当该元素嵌套在其他 JSX 元素内部时才进行完整检查。从 crates/rome_js_analyze/src/aria_analyzers/a11y/use_aria_props_for_role.rs 的run方法可以看到它先通过ancestors()向上查找祖先元素只有找到 JSX 元素祖先时才继续。读取 role 属性通过find_attribute_by_name(role)找到role属性并取出其字符串值。比对必需属性用roles.get_role(name)从 crates/rome_aria/src/roles.rs 的 ARIA 角色表中查出该角色的定义遍历role.properties()中标记为requiredtrue的属性逐个调用node.find_attribute_by_name(property_name)检查元素上是否声明了该属性只要有一个必需属性缺失就产生诊断。其中角色到必需属性集合的映射数据来自 crates/rome_aria/src/roles.rs例如角色必需 ARIA 属性checkboxaria-checkedswitcharia-checkedradioaria-checkedoptionaria-selectedcomboboxaria-controls、aria-expandedheadingaria-levelspinbuttonaria-valuemax、aria-valuemin、aria-valuenowslider/separatoraria-valuemax、aria-valuemin、aria-valuenowscrollbararia-valuemax、aria-valuemin、aria-valuenow、aria-orientation、aria-controlsmenuitemcheckbox/menuitemradioaria-checked需要注意的是roles.rs中每个角色的PROPS列表同时包含必需true与可选false属性规则只对true的项进行强制检查可选属性缺失不会报错。此外Rome 的 a11y 检查依赖AriaServices提供的AriaRoles/AriaProperties服务见 crates/rome_js_analyze/src/aria_services.rs该服务在语法分析阶段Phases::Syntax注入。无效示例Invalid官方文档给出的两个经典无效示例分别命中状态类和标题类角色的必需属性缺失span rolecheckbox/spanRome 输出诊断a11y/useAriaPropsForRole.js:1:7 lint/a11y/useAriaPropsForRole ✖ The element with the checkbox ARIA role does not have the required ARIA attributes. 1 │ span rolecheckbox/span │ ^^^^^^^^^^^^^^^^^^^^^^^ ℹ Missing ARIA prop(s): - aria-checked另一个示例span roleheading/span诊断同样指向缺失的必需属性✖ The element with the heading ARIA role does not have the required ARIA attributes. ℹ Missing ARIA prop(s): - aria-level诊断信息结构主消息 Missing ARIA prop(s)列表与源码中UseAriaPropsForRoleState::as_diagnostic的实现一致缺失属性以footer_list形式逐条列出便于开发者一眼看出要补哪些属性见 use_aria_props_for_role.rs。仓库的官方测试夹具 crates/rome_js_analyze/tests/specs/a11y/useAriaPropsForRole/invalid.jsx 覆盖了更多无效场景例如var a span rolespinbutton/span; // 缺 aria-valuemax / aria-valuemin / aria-valuenow var a span rolespinbutton aria-valuemax100/span; // 缺 aria-valuemin / aria-valuenow var a span rolescrollbar aria-valuemin0 aria-valuemax100/span; // 缺 aria-valuenow / aria-orientation / aria-controls var a span rolecombobox aria-expandedtrue/span; // 缺 aria-controls对应的快照文件 invalid.jsx.snap 记录了全部 24 个无效用例的完整诊断输出可以作为理解规则判定边界的参考。特别值得注意spinbutton、slider、separator、scrollbar这类角色即使只缺一个必需属性例如已有aria-valuemin、aria-valuemax但缺aria-valuenow规则依然会精准报出剩余缺失项说明规则是逐属性独立校验而非全有或全无。有效示例Valid补齐必需属性后代码即可通过检查span rolecheckbox aria-checkedtrue/spanspan roleheading aria-level1/span测试夹具 valid.jsx 还覆盖了更多通过场景从中可以总结出几条重要规则必需属性齐全即可通过包括多属性角色var a span rolescrollbar aria-valuemax100 aria-valuemin0 aria-valuenow50 aria-orientationhorizontal aria-controls123/span; var a span rolecombobox aria-controlstrue aria-expandedtrue/span;大小写敏感Span rolemenuitemradio不会触发检查组件名大写Span不视为原生元素测试中它同样通过。这印证了规则只会命中识别为原生 HTML 元素的 JSX 标签。无障碍指南与相关资源罗马官方文档为该规则关联了以下规范与工具依据WCAG 4.1.2「名称、角色、值」要求所有用户界面组件的名称与角色可以被程序化确定且用户可设置的状态、属性和值应能被程序化设置——这正是角色必须带齐必需状态属性的规范源头。ARIA 规范RolesWAI-ARIA 1.1/1.2 规范中对各角色及其必需状态属性的定义Rome 的roles.rs数据即由此而来。Chrome Audit RulesAX_ARIA_03Chrome 无障碍审计工具中对应的同类检查项ARIA 角色必须具有其所需的 aria-* 属性。如何在项目中启用与配置启用规则由于useAriaPropsForRole属于 recommended 规则使用 Rome 的默认配置时它默认开启。你可以通过 CLI 或配置文件显式控制它。CLI 方式直接对文件或目录运行 lintrome lint src/配置文件方式在项目根目录的rome.json中配置。规则在配置结构中的字段名为useAriaPropsForRole见 crates/rome_service/src/configuration/linter/rules.rs 与 JSON 解析映射 crates/rome_service/src/configuration/parse/json/rules.rs配置示例如下{ linter: { rules: { a11y: { useAriaPropsForRole: error } } } }rome.json的完整 schema 可在 npm/rome/configuration_schema.json 与 editors/vscode/configuration_schema.json 中查看字段useAriaPropsForRole均包含于其中。关闭规则该规则不提供额外的选项Options——源码中type Options ()表明它不接受任何可配置参数见 use_aria_props_for_role.rs。因此你只能整体启用或禁用{ linter: { rules: { a11y: { useAriaPropsForRole: off } } } }单行/局部禁用如果某处代码确实无法满足例如第三方组件输出可以使用行内抑制注释// rome-ignore lint/a11y/useAriaPropsForRole: 该组件由设计系统接管可访问性 span rolecheckbox/span关于禁用规则的通用方法配置文件禁用、行内抑制、// rome-ignore语法详见官方文档 linter 页面的 Disable a lint rule 与 Rule options 章节对应原文档中的 Disable a rule 与 Rule options 两个关联链接。规则在 Rome 架构中的位置从源码结构看该规则位于 crates/rome_js_analyze/src/aria_analyzers/a11y/ 目录属于AriaAnalyzers分类下的a11y组见 crates/rome_js_analyze/src/aria_analyzers.rs。它通过AriaAnyJsxElement查询类型匹配所有 JSX 元素并依赖AriaServices注入的AriaRoles服务由 rome_aria crate 提供在语法分析阶段执行检查。整体调用链为JSX 源码 → rome_js_parser 解析 → AriaServices 注入 AriaRoles/AriaProperties → useAriaPropsForRole::run 查 role → 比对必需属性 → 缺失则产出 RuleDiagnostic规则测试由 crates/rome_js_analyze/tests/spec_tests.rs 驱动测试夹具位于 crates/rome_js_analyze/tests/specs/a11y/useAriaPropsForRole/包含invalid.jsx24 个无效用例、valid.jsx13 个有效用例及对应的.snap快照可作为回归测试的权威参考。常见问题与最佳实践为什么span rolecheckbox是常见错误开发者习惯用role把无语义的span/div改造成控件却忘记 ARIA 的角色-状态绑定声明了checkbox角色就必须同时用aria-checked暴露当前选中状态否则辅助技术无法判断控件状态违反 WCAG 4.1.2。优先使用原生元素input typecheckbox自带隐式角色与状态天然满足该规则且语义更优role属性应主要用在原生语义无法表达的场景。把规则的诊断信息当作修复清单Missing ARIA prop(s)列出的属性就是你必须补齐的字段逐个加上即可通过检查。测试夹具是最好的学习样本想确认某个角色需要哪些必需属性直接查阅 crates/rome_aria/src/roles.rs 中对应角色定义的PROPStrue为必需或运行 invalid.jsx 查看诊断输出。【免费下载链接】toolsUnified developer tools for JavaScript, TypeScript, and the web项目地址: https://gitcode.com/gh_mirrors/to/tools创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Rome useAriaPropsForRole 规则详解：强制 ARIA 角色必备属性
Rome useAriaPropsForRole 规则详解强制 ARIA 角色必备属性【免费下载链接】toolsUnified developer tools for JavaScript, TypeScript, and the web项目地址: https://gitcode.com/gh_mirrors/to/tools本文以 Rome 官方文档 website/src/pages/lint/rules/useAriaPropsForRole.md 为核心结合仓库中 RomeUnified developer tools for JavaScript, TypeScript, and the web的源码实现与测试用例深入讲解useAriaPropsForRole这一无障碍a11ylint 规则它强制带有 ARIA 角色的元素必须拥有该角色所要求的所有 ARIA 属性并逐步拆解其工作原理、常见误用场景、修复方法以及如何在项目中启用、配置与禁用。读完本文你将能在实际 JSX/TSX 代码中准确识别并修复此类可访问性问题并理解 Rome 如何基于 WAI-ARIA 规范数据模型实现这一检查。规则概览useAriaPropsForRole是 Rome 在v11.0.0引入的一条 a11y无障碍lint 规则归属于lint/a11y/useAriaPropsForRole诊断类别见 crates/rome_diagnostics_categories/src/categories.rs并且被 Rome 官方标记为recommended推荐启用。规则核心语义一句话概括强制带有 ARIA 角色的元素必须拥有该角色所要求的所有 ARIA 属性。在实际开发中很多开发者会给元素加上role属性来声明其语义角色例如把span改造成复选框、标题、滑块等却常常遗漏 WAI-ARIA 规范中该角色**必需required**的状态属性。例如span rolecheckbox缺少aria-checked就会让屏幕阅读器无法获知该复选框是否被选中——这正是 WCAG 4.1.2「名称、角色、值Name, Role, Value」所要求的内容。规则判定逻辑规则检查过程可分为三步确定检查范围规则只针对 JSX 元素AnyJsxElement且仅当该元素嵌套在其他 JSX 元素内部时才进行完整检查。从 crates/rome_js_analyze/src/aria_analyzers/a11y/use_aria_props_for_role.rs 的run方法可以看到它先通过ancestors()向上查找祖先元素只有找到 JSX 元素祖先时才继续。读取 role 属性通过find_attribute_by_name(role)找到role属性并取出其字符串值。比对必需属性用roles.get_role(name)从 crates/rome_aria/src/roles.rs 的 ARIA 角色表中查出该角色的定义遍历role.properties()中标记为requiredtrue的属性逐个调用node.find_attribute_by_name(property_name)检查元素上是否声明了该属性只要有一个必需属性缺失就产生诊断。其中角色到必需属性集合的映射数据来自 crates/rome_aria/src/roles.rs例如角色必需 ARIA 属性checkboxaria-checkedswitcharia-checkedradioaria-checkedoptionaria-selectedcomboboxaria-controls、aria-expandedheadingaria-levelspinbuttonaria-valuemax、aria-valuemin、aria-valuenowslider/separatoraria-valuemax、aria-valuemin、aria-valuenowscrollbararia-valuemax、aria-valuemin、aria-valuenow、aria-orientation、aria-controlsmenuitemcheckbox/menuitemradioaria-checked需要注意的是roles.rs中每个角色的PROPS列表同时包含必需true与可选false属性规则只对true的项进行强制检查可选属性缺失不会报错。此外Rome 的 a11y 检查依赖AriaServices提供的AriaRoles/AriaProperties服务见 crates/rome_js_analyze/src/aria_services.rs该服务在语法分析阶段Phases::Syntax注入。无效示例Invalid官方文档给出的两个经典无效示例分别命中状态类和标题类角色的必需属性缺失span rolecheckbox/spanRome 输出诊断a11y/useAriaPropsForRole.js:1:7 lint/a11y/useAriaPropsForRole ✖ The element with the checkbox ARIA role does not have the required ARIA attributes. 1 │ span rolecheckbox/span │ ^^^^^^^^^^^^^^^^^^^^^^^ ℹ Missing ARIA prop(s): - aria-checked另一个示例span roleheading/span诊断同样指向缺失的必需属性✖ The element with the heading ARIA role does not have the required ARIA attributes. ℹ Missing ARIA prop(s): - aria-level诊断信息结构主消息 Missing ARIA prop(s)列表与源码中UseAriaPropsForRoleState::as_diagnostic的实现一致缺失属性以footer_list形式逐条列出便于开发者一眼看出要补哪些属性见 use_aria_props_for_role.rs。仓库的官方测试夹具 crates/rome_js_analyze/tests/specs/a11y/useAriaPropsForRole/invalid.jsx 覆盖了更多无效场景例如var a span rolespinbutton/span; // 缺 aria-valuemax / aria-valuemin / aria-valuenow var a span rolespinbutton aria-valuemax100/span; // 缺 aria-valuemin / aria-valuenow var a span rolescrollbar aria-valuemin0 aria-valuemax100/span; // 缺 aria-valuenow / aria-orientation / aria-controls var a span rolecombobox aria-expandedtrue/span; // 缺 aria-controls对应的快照文件 invalid.jsx.snap 记录了全部 24 个无效用例的完整诊断输出可以作为理解规则判定边界的参考。特别值得注意spinbutton、slider、separator、scrollbar这类角色即使只缺一个必需属性例如已有aria-valuemin、aria-valuemax但缺aria-valuenow规则依然会精准报出剩余缺失项说明规则是逐属性独立校验而非全有或全无。有效示例Valid补齐必需属性后代码即可通过检查span rolecheckbox aria-checkedtrue/spanspan roleheading aria-level1/span测试夹具 valid.jsx 还覆盖了更多通过场景从中可以总结出几条重要规则必需属性齐全即可通过包括多属性角色var a span rolescrollbar aria-valuemax100 aria-valuemin0 aria-valuenow50 aria-orientationhorizontal aria-controls123/span; var a span rolecombobox aria-controlstrue aria-expandedtrue/span;大小写敏感Span rolemenuitemradio不会触发检查组件名大写Span不视为原生元素测试中它同样通过。这印证了规则只会命中识别为原生 HTML 元素的 JSX 标签。无障碍指南与相关资源罗马官方文档为该规则关联了以下规范与工具依据WCAG 4.1.2「名称、角色、值」要求所有用户界面组件的名称与角色可以被程序化确定且用户可设置的状态、属性和值应能被程序化设置——这正是角色必须带齐必需状态属性的规范源头。ARIA 规范RolesWAI-ARIA 1.1/1.2 规范中对各角色及其必需状态属性的定义Rome 的roles.rs数据即由此而来。Chrome Audit RulesAX_ARIA_03Chrome 无障碍审计工具中对应的同类检查项ARIA 角色必须具有其所需的 aria-* 属性。如何在项目中启用与配置启用规则由于useAriaPropsForRole属于 recommended 规则使用 Rome 的默认配置时它默认开启。你可以通过 CLI 或配置文件显式控制它。CLI 方式直接对文件或目录运行 lintrome lint src/配置文件方式在项目根目录的rome.json中配置。规则在配置结构中的字段名为useAriaPropsForRole见 crates/rome_service/src/configuration/linter/rules.rs 与 JSON 解析映射 crates/rome_service/src/configuration/parse/json/rules.rs配置示例如下{ linter: { rules: { a11y: { useAriaPropsForRole: error } } } }rome.json的完整 schema 可在 npm/rome/configuration_schema.json 与 editors/vscode/configuration_schema.json 中查看字段useAriaPropsForRole均包含于其中。关闭规则该规则不提供额外的选项Options——源码中type Options ()表明它不接受任何可配置参数见 use_aria_props_for_role.rs。因此你只能整体启用或禁用{ linter: { rules: { a11y: { useAriaPropsForRole: off } } } }单行/局部禁用如果某处代码确实无法满足例如第三方组件输出可以使用行内抑制注释// rome-ignore lint/a11y/useAriaPropsForRole: 该组件由设计系统接管可访问性 span rolecheckbox/span关于禁用规则的通用方法配置文件禁用、行内抑制、// rome-ignore语法详见官方文档 linter 页面的 Disable a lint rule 与 Rule options 章节对应原文档中的 Disable a rule 与 Rule options 两个关联链接。规则在 Rome 架构中的位置从源码结构看该规则位于 crates/rome_js_analyze/src/aria_analyzers/a11y/ 目录属于AriaAnalyzers分类下的a11y组见 crates/rome_js_analyze/src/aria_analyzers.rs。它通过AriaAnyJsxElement查询类型匹配所有 JSX 元素并依赖AriaServices注入的AriaRoles服务由 rome_aria crate 提供在语法分析阶段执行检查。整体调用链为JSX 源码 → rome_js_parser 解析 → AriaServices 注入 AriaRoles/AriaProperties → useAriaPropsForRole::run 查 role → 比对必需属性 → 缺失则产出 RuleDiagnostic规则测试由 crates/rome_js_analyze/tests/spec_tests.rs 驱动测试夹具位于 crates/rome_js_analyze/tests/specs/a11y/useAriaPropsForRole/包含invalid.jsx24 个无效用例、valid.jsx13 个有效用例及对应的.snap快照可作为回归测试的权威参考。常见问题与最佳实践为什么span rolecheckbox是常见错误开发者习惯用role把无语义的span/div改造成控件却忘记 ARIA 的角色-状态绑定声明了checkbox角色就必须同时用aria-checked暴露当前选中状态否则辅助技术无法判断控件状态违反 WCAG 4.1.2。优先使用原生元素input typecheckbox自带隐式角色与状态天然满足该规则且语义更优role属性应主要用在原生语义无法表达的场景。把规则的诊断信息当作修复清单Missing ARIA prop(s)列出的属性就是你必须补齐的字段逐个加上即可通过检查。测试夹具是最好的学习样本想确认某个角色需要哪些必需属性直接查阅 crates/rome_aria/src/roles.rs 中对应角色定义的PROPStrue为必需或运行 invalid.jsx 查看诊断输出。【免费下载链接】toolsUnified developer tools for JavaScript, TypeScript, and the web项目地址: https://gitcode.com/gh_mirrors/to/tools创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
