Rome 无障碍规则 noRedundantAlt 完全指南：杜绝 img 替代文本中的冗余措辞

开发工具CLILint格式化静态分析代码质量构建工具【免费下载链接】toolsUnified developer tools for JavaScript, TypeScript, and the web项目地址https://gitcode.com/gh_mirrors/to/tools点击查看免费下载noRedundantAlt是 Rome本仓库 unified developer tools 项目内置的 a11y无障碍推荐规则用于强制要求img元素的alt替代文本中不得出现 image、picture、photo 这三个冗余词。本文将基于该规则的官方文档、Rust 源码实现与快照测试完整讲解其判定逻辑、aria-hidden 豁免机制、边界行为与在rome.json中的配置方式帮助你在实际项目中正确使用并深度理解这一规则。规则概览规则名称noRedundantAlt诊断分类lint/a11y/noRedundantAlt引入版本since v12.0.0见 declare_rule 声明推荐状态Rome 官方推荐规则recommended: true已列入 RECOMMENDED_RULES所属分组a11y与useAltText、useValidLang等 22 条规则同组见 a11y.rs 分组声明核心作用强制img的alt属性中不包含 image、picture 或 photo 单词该规则的核心实现位于 crates/rome_js_analyze/src/analyzers/a11y/no_redundant_alt.rs规则通过declare_rule!宏注册type Query AstAnyJsxElement即作用于 JSX 元素节点属于静态 AST 分析规则无需运行时信息。设计动机屏幕阅读器已播报 image规则的设计依据来自辅助技术AT的实际行为屏幕阅读器在遇到img元素时会自动将其播报为 image因此如果在替代文本中再写 image of ...、photo of ... 这类措辞就是重复信息反而干扰视障用户的听觉理解。源码中的诊断备注精确描述了这一动机Screen readers announce img elements as images, so it is not necessary to redeclare this in alternative text.见 diagnostic 函数 中的note部分。好的替代文本应该直接描述图片内容例如altA red car on a mountain road而不是altphoto of a red car。判定逻辑与源码剖析run函数的执行流程no_redundant_alt.rs可以拆解为以下四个步骤1. 仅检查小写的img元素if node.name_value_token()?.text_trimmed() ! img { return None; }规则只针对名称严格等于img全小写的 JSX 元素。因此a /、自定义组件UX.Layout、甚至IMG /大写都不会触发该规则——测试用例 valid.jsx 中明确包含这些放行场景。2.aria-hidden豁免检查隐藏图片直接通过规则的第二步是检查aria-hidden属性若图片对辅助技术隐藏则不再强制执行规则恒通过let aria_hidden_attribute node.find_attribute_by_name(aria-hidden); if let Some(aria_hidden) aria_hidden_attribute { let is_false match aria_hidden.initializer()?.value().ok()? { AnyJsxAttributeValue::AnyJsxTag(_) false, AnyJsxAttributeValue::JsxExpressionAttributeValue(aria_hidden) { /* 布尔字面量 false */ } AnyJsxAttributeValue::JsxString(aria_hidden) { aria_hidden.inner_string_text().ok()?.text() false } }; if !is_false { return None; } }这里is_false的计算覆盖了三种书写形态aria-hidden写法判定结果规则是否执行裸属性aria-hidden或aria-hidden{true}非 false跳过通过aria-hiddentrue字符串非 false跳过通过aria-hiddenfalse字符串false继续检查 altaria-hidden{false}布尔字面量false继续检查 altaria-hidden{foo?.bar}非静态表达式无法静态求值?直接返回跳过通过注意最后一种形态当aria-hidden的值是无法静态确定的表达式时如{foo?.bar}、{isHidden}源码中的?操作符会让整个run函数直接返回None即不报告。这一点同样有测试佐证valid.jsx 中的img altphoto image picture aria-hidden{foo?.bar} /是合法用例。从源码结构看这是保守策略静态分析无法确知运行时的隐藏状态因此宁可放过也不误报。3. 提取alt属性值并分类处理通过豁免检查后规则获取alt属性值并按 JSX 属性值的语法形态分流match alt { AnyJsxAttributeValue::AnyJsxTag(_) None, AnyJsxAttributeValue::JsxExpressionAttributeValue(ref value) { /* 见下 */ } AnyJsxAttributeValue::JsxString(ref value) { let text value.inner_string_text().ok()?.to_string(); is_redundant_alt(text).then_some(alt) } }JSX 字符串alt...直接取文本内容检测。字符串字面量表达式alt{photo}JsStringLiteralExpression会被检测。模板字符串alt{picture doing ${things}}只检测模板块chunk中的静态文本部分插值表达式一律忽略。即picture doing ${things}中的picture doing会被检测而${photo}里的变量名不会被误判——这正是 invalid.jsx 中let a img alt{picture doing ${picture}} {...this.props} /;被报告、而 valid.jsx 中img alt{${photo}} /被放行的原因。其他表达式标识符{photo}、成员表达式{imageAlt.name}、可选链{imageAlt?.name}、函数{() {}}、{undefined}等无法静态求值一律放行。4. 冗余词判定大小写不敏感的全词匹配规则定义了三词黑名单并采用按空白拆分 小写化 精确相等的匹配策略const REDUNDANT_WORDS: [str; 3] [image, photo, picture]; fn is_redundant_alt(alt: String) - bool { REDUNDANT_WORDS .into_iter() .any(|word| alt.split_whitespace().any(|x| x.to_lowercase() word)) }由此可以得出两个重要边界行为大小写不敏感Photo、PhOtO、IMAGE等任意大小写组合都会命中测试中专门覆盖了PhOtO of friend.、piCTUre of friend.等用例。必须整词匹配由于先按空白拆分再全等比较Photography、ImageMagick这类包含子串的单词不会误报——它们不是独立的 photo/image 单词。这也符合文档does not contain the word的表述禁止的是作为独立单词出现的冗余措辞而非任意子串。Invalid 示例与诊断输出官方文档给出了三个触发该规则的典型示例均产生lint/a11y/noRedundantAlt错误诊断img srcsrc altphoto content /;img alt{picture doing ${things}} {...this.props} /;img altpicture of cool person aria-hidden{false} /;诊断输出格式如下位置会精确标注到 alt 值的区间lint/a11y/noRedundantAlt ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✖ Avoid the words image, picture, or photo in img element alt text. 1 │ img srcsrc altphoto content /; │ ^^^^^^^^^^^^^^ ℹ Screen readers announce img elements as images, so it is not necessary to redeclare this in alternative text.在 invalid.jsx 测试用例 中还覆盖了更多变体均被报告let a img altPhoto of friend. /; let a img altPhOtO of friend. /; let a img alt{photo} /; let a img altimAGE of friend. /; let a img altphoto of cool person aria-hidden{false} /; let a img altimage of cool person aria-hiddenfalse /; let a img altphoto {...this.props} /; let a img alt{image doing ${things}} {...this.props} /;注意最后两行{...this.props}属性展开不影响检查alt 仍可静态读取aria-hiddenfalse字符串形式与{false}一样会被识别为未隐藏从而照常检查 alt 文本。Valid 示例哪些写法安全通过官方文档给出的合法示例 img srcsrc altalt / img srcsrc alt{photo} / img srcbar aria-hidden altPicture of me taking a photo of an image / /结合 valid.jsx可以将安全通过归纳为以下六类alt 中不含冗余词altfoo、altDoing cool things.。元素本身不是 imga /、UX.Layouttest/UX.Layout、IMG /大写。图片已隐藏aria-hidden、aria-hiddentrue与altphoto of image组合即使 alt 含冗余词也放行。alt 值无法静态求值{photo}、{alt}、{imageAlt.name}、{imageAlt?.name}、{() {}}、{undefined}、{${photo}}纯插值模板。冗余词出现在插值而非静态文本alt{this should pass for ${photo}}。非整词匹配altPhotography、altImageMagick子串不命中。需要特别说明的是第 4 类例如alt{photo}运行时确实可能是冗余文本但静态分析无法确认photo变量最终的值规则选择不误报。若你的代码中 alt 来自动态变量请自行保证其文案质量。在项目中启用、配置与关闭该规则默认行为由于该规则是推荐规则recommended: true使用 Rome 默认配置运行 lint 时即会生效无需额外开启。它以error级别报告并随rome check/rome lint命令输出。通过 rome.json 调整该规则的配置项注册于 crates/rome_service/src/configuration/linter/rules.rs 的a11y分组下其 CLI 参数接受的取值为on|off|warn对应 bpaf 定义argument(on|off|warn)。在项目根目录的rome.json中可按需调整{ linter: { enabled: true, rules: { a11y: { noRedundantAlt: off } } } }将值设为off可完全关闭该规则禁用方式详见 linter 文档Disable a lint rule设为warn可将其降级为警告适合在迁移/重构期间保持 CI 通过详见 Change the diagnostic severity设为error或on则保持错误级别。由于源码中该规则的type Options ()它不接受任何附加选项因此无需也无法配置options字段Rome 中带选项的规则才需要使用{ level: warn, options: {...} }对象写法参见 Rule options。使用诊断分类过滤或抑制该规则的诊断分类lint/a11y/noRedundantAlt注册于 crates/rome_diagnostics_categories/src/categories.rs可在命令行按分类过滤规则也可作为代码内抑制注释的标识。文档中Related links指向的 Disable a rule 与 Rule options 是调整规则行为的两条主要路径。测试与快照验证规则的正确性由 Rome 的规格测试体系保障相关测试位于invalid.jsx20 个应报错用例覆盖大小写变体、模板字符串、属性展开、aria-hidden{false}/aria-hiddenfalse等场景invalid.jsx.snap对应诊断快照逐条验证了诊断消息文本、诊断分类lint/a11y/noRedundantAlt以及高亮区间例如第 20 行image doing ${image}精确标注到模板字符串区间valid.jsx 与 valid.jsx.snap32 个合法用例验证不误报。这些用例由 spec_tests.rs 驱动快照文件同时记录了诊断输出的精确格式是理解规则行为最直观的参考资料。若你想在本地复现可运行cargo test -p rome_js_analyze或对应的规格测试目标来执行全部 a11y 规则测试。小结noRedundantAlt是一个小而精的静态分析规则它只关心一件事——img的替代文本里不要重复屏幕阅读器已经会播报的 image 措辞。理解它的关键在于三点aria-hidden 豁免隐藏图片直接放行、取值形态分流字符串/字面量/模板静态块被检查动态表达式放行、整词匹配大小写不敏感但不误伤Photography这类单词。掌握这些边界后你既能写出符合 WCAG 精神的替代文本也能在收到该规则的报错时快速判断是改文案、加aria-hidden还是调整规则级别。赞分享开发工具CLILint格式化静态分析代码质量构建工具【免费下载链接】toolsUnified developer tools for JavaScript, TypeScript, and the web项目地址https://gitcode.com/gh_mirrors/to/tools点击查看免费下载相关推荐Front-End-Checklist 无障碍规则精讲避免冗余的图片替代文本image-redundant-altFront End Checklist 无障碍规则精讲避免冗余的图片替代文本image redundant alt 导读 本篇文章深入解析 Front EESLint no-duplicate-imports 规则完全指南杜绝重复模块导入与冗余导出ESLint no duplicate imports 规则完全指南杜绝重复模块导入与冗余导出 本文围绕 ESLint 内置规则 no duplicate i开发工具Lint静态分析代码质量Front-End-Checklist 无障碍检查项详解避免冗余的图片替代文本image-redundant-altFront End Checklist 无障碍检查项详解避免冗余的图片替代文本image redundant alt 本文是 Front End Chec上一篇progressive-image.js与WebP、AVIF格式现代图片优化组合方案下一篇从数据到决策Deep_Learning_Machine_Learning_Stock股票数据分析全流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考