17370845950

本文详解 `jsx-a11y/img-redundant-alt` 报错原因及解决方案，重点说明为何在 `alt` 中使用 “image”“photo”“picture” 等冗余词违反可访问性原则，并提供 react 中 svg 与 img 的合规写法。

在构建符合 WCAG 和无障碍标准（a11y）的 React 应用时，eslint-plugin-jsx-a11y 插件中的 img-redundant-alt 规则常被触发。该规则的核心逻辑是：屏幕阅读器（如 NVDA、VoiceOver）默认将 元素识别为“图像”，因此 alt 文本中再重复出现 “image”、“photo” 或 “picture” 等词不仅无意义，反而降低信息传达效率，属于冗余描述。

✅ 正确做法：用功能或内容替代类型词

alt 的本质是为无法看到图像的用户（如视障者、加载失败场景）提供等效的内容描述，应聚焦于“它是什么”或“它做什么”，而非“它是什么类型的元素”。

❌ 错误示例（触发警告）

@@##@@
@@##@@

⚠️ image 和 photo 属于规则默认禁止的冗余词（默认配置：["image", "picture", "photo"]）。

✅ 正确示例（语义清晰、简洁有效）

@@##@@
@@##@@

✅ 描述具体对象/功能，不含类型标签，同时具备上下文信息（如时间范围、数值）。

⚠️ 特别注意：SVG 图标通常无需 alt

你提供的代码片段是一个装饰性 SVG（带 aria-hidden="true"），它根本不应使用 alt 属性——因为：

• aria-hidden="true" 已明确告知辅助技术忽略该元素；
• 若 SVG 是纯装饰（如图标、分隔线），应保持无文本描述；若具功能性（如按钮图标），需通过 aria-label 或 aria-labelledby 提供语义。

✅ 功能性 SVG 正确写法（带可访问性）

? 进阶：自定义规则（不推荐，仅作了解）

如团队有特殊命名规范（例如统一要求含 “icon”），可覆盖默认配置（eslint-config-airbnb 等主流配置中已禁用此规则，建议优先遵循标准）：

// .eslintrc.json
{
  "rules": {
    "jsx-a11y/img-redundant-alt": ["error", { "components": ["Image"], "words": ["icon"] }]
  }
}

但请注意：添加新关键词需确保其真正提升可访问性，而非妥协标准。

✅ 总结检查清单

• [ ] 的 alt 文本是否完全避免 “image”/“photo”/“picture”？
• [ ] 装饰性 SVG 是否移除了非法 alt 并设 aria-hidden="true"？
• [ ] 功能性 SVG 是否包裹在语义化容器（如 ）中，并用 aria-label 明确意图？
• [ ] 所有图像描述是否满足「盲人能据此理解内容」这一黄金标准？

遵循以上实践，即可彻底消除 Redundant alt attribute 警告，同时显著提升应用的包容性与专业度。