企业官网建设流程全解析

• 开发工具
• CLI
• Lint
• 格式化
• 静态分析
• 代码质量
• 构建工具

本指南以 Rome 官方 lint 规则文档useAltText为核心，结合仓库源码与测试用例，系统讲解该规则的作用范围、判定逻辑、CLI 运行方式与配置方法。读完本文，你将掌握如何借助 Rome 在 JSX/TSX 代码中强制为<img>、<area>、<input type="image">与<object>提供有效的替代文本，从而满足 WCAG 1.1.1 无障碍要求，帮助依赖屏幕阅读器的用户理解页面内容。

规则概览：为什么需要替代文本

useAltText是 Rome 从 v10.0.0 起内置的 lint 规则，用于强制所有需要替代文本（alternative text）的元素向终端用户传递有意义的信息。替代文本是屏幕阅读器用户理解页面内容目的的关键组成部分——没有它，视障用户将无法获知一张图片、一个图像按钮或一个嵌入式对象在页面中代表什么。

该规则由 Rome 官方推荐（recommended: true），属于a11y（无障碍）规则组。在 crates/rome_service/src/configuration/linter/rules.rs 中可以看到，A11y组共包含 22 条规则，其中 20 条（含useAltText）被列入RECOMMENDED_RULES。这意味着：只要启用 Rome 的推荐规则集，useAltText就会默认生效，无需额外配置。

默认情况下，规则检查以下四类元素的替代文本：

注：规则仅作用于 JSX/JSX 元素；对应 HTML 场景（如.html文件）不在本规则默认检查范围内。另需注意，规则只检查替代文本的存在性，不判断文案质量（后者由noRedundantAlt等规则补充）。

源码级判定逻辑：四种元素如何被校验

规则实现位于 crates/rome_js_analyze/src/analyzers/a11y/use_alt_text.rs，其核心结构如下：

• declare_rule!宏声明规则元数据：version: "10.0.0"、name: "useAltText"、recommended: true；
• type Query = Ast<AnyJsxElement>：规则遍历每个 JSX 元素节点（use_alt_text.rs）；
• run方法按元素标签名分派校验逻辑（use_alt_text.rs）。

各元素的判定规则如下：

<img>与<area>

必须满足以下任一条件，否则报错：

• 存在有效的alt属性；
• 存在有效的aria-label属性；
• 存在有效的aria-labelledby属性。

<input type="image">

仅当元素带有type="image"时才受检查（has_type_image_attribute）。普通<input />、<input type="foo" />均不触发。校验属性与<img>相同：alt/aria-label/aria-labelledby任一有效即可。

<object>

判定逻辑略有不同（use_alt_text.rs）：

• 优先检查title、aria-label、aria-labelledby；
• 三者皆无效时，若为成对写法<object>...</object>，还会检查其内部是否包含可访问的子内容（has_accessible_child()）——例如<object>Foo</object>或<object><p>This is descriptive!</p></object>都算有效；
• 自闭合<object />且无任何替代文本时直接报错。

什么是"有效"的替代文本

源码中两个辅助函数给出了精确定义（use_alt_text.rs）：

• has_valid_alt_text（检查alt）：属性必须带初始化器；若值可静态求值，则不能是null/undefined；属性不能位于展开属性之后（has_trailing_spread_prop为假）。注意：alt=""被视为有效（空 alt 适用于装饰性图片）。
• has_valid_label（检查aria-label/aria-labelledby/title）：同样要求有初始化器且非null/undefined，并且字符串常量不能为空字符串""；同时排除展开属性场景。

值得注意的几个边界：

• <img alt />（无值的布尔属性）无效；
• <img alt={undefined} />无效；
• <img alt="" />有效（装饰性图片约定）；
• <img alt={"foo"} />、<img alt={alt} />（动态值）有效；
• <img {...this.props} />因无法静态判断，无效（展开属性中可能缺少 alt）；
• <img alt="" role="presentation" />有效（presentation 角色下空 alt 是规范做法）。

运行示例：错误与正确写法

以下示例均来自仓库测试夹具（crates/rome_js_analyze/tests/specs/a11y/useAltText 目录下的img.jsx、area.jsx、input.jsx、object.jsx），可直接作为实战参考。

触发错误的写法（Invalid）

<img src="image.png" />

运行 Rome 检查后，诊断输出如下：

a11y/useAltText.js:1:1 lint/a11y/useAltText ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✖ Provide a text alternative through the alt, aria-label or aria-labelledby attribute > 1 │ <img src="image.png" /> │ ^^^^^^^^^^^^^^^^^^^^^^^ 2 │ ℹ Meaningful alternative text on elements helps users relying on screen readers to understand content's purpose within a page.

诊断消息由 diagnostic 方法 生成，随附的ℹ提示解释了规则的无障碍意义。该诊断类别在 crates/rome_diagnostics_categories/src/categories.rs 中注册为lint/a11y/useAltText。

其他同样会报错的常见写法：

<input type="image" src="image.png" /> <area /> <object /> <img alt /> <img alt={undefined} /> <img alt="" aria-label="" /> {/* aria-label 空字符串无效 */} <img {...this.props} /> {/* 展开属性无法确认 alt */} <input type="image" aria-label="" /> <object><div aria-hidden /></object> {/* 子内容不可访问 */}

通过检查的写法（Valid）

<img src="image.png" alt="image alt" /> <input type="image" src="image.png" alt="alt text" /> <input type="image" src="image.png" aria-label="alt text" /> <input type="image" src="image.png" aria-labelledby="someId" /> <area alt="This is descriptive!" /> <object title="An object" /> <object><p>This is descriptive!</p></object> {/* 动态值同样有效 */} <img alt={photo.caption} /> <img alt={alt || "Alt text"} />

在命令行与配置中使用

命令行直接检查

在项目根目录（存在rome.json时）运行：

rome check path/to/file.jsx

若规则在推荐集中生效，违反useAltText的代码会以诊断形式输出；使用--apply类参数无法自动修复该规则（本规则无自动修复，属于纯诊断型规则），需要开发者手动补充替代文本。

通过 rome.json 配置

规则名在配置中写作useAltText，位于linter.rules.a11y分组下。推荐集之外可显式开关：

{ "linter": { "enabled": true, "rules": { "recommended": true, "a11y": { "useAltText": "warn" } } } }

• "recommended": true：启用 Rome 推荐规则集（useAltText已在其中，无需重复声明）；
• 若想关闭推荐集中的该规则，可设置"useAltText": "off"；
• 支持的值："on"、"warn"、"off"。"warn"表示仅告警、不使命令以错误码退出。

配置结构对应源码 crates/rome_service/src/configuration/linter/rules.rs 中A11y结构体的use_alt_text: Option<RuleConfiguration>字段；该字段的序列化与反序列化逻辑见 crates/rome_service/src/configuration/parse/json/rules.rs。

Rome 规则的通用开关方式还可参考仓库文档 linter 索引，其中说明了非推荐规则默认关闭、可通过配置开启的机制。

无障碍依据与测试保障

WCAG 合规

本规则直接对应 WCAG 2.1 成功标准1.1.1 非文本内容（Non-text Content）：所有非文本内容必须提供等价的文本替代。官方说明见 WCAG 1.1.1 理解文档（链接收录于 use_alt_text.rs 与 useAltText.md 的 Accessibility guidelines 小节）。

测试用例体系

仓库为规则维护了完整的规格测试夹具（crates/rome_js_analyze/tests/specs/a11y/useAltText）：

• img.jsx：覆盖<img>的 14 组 invalid 与 30+ 组 valid 场景；
• area.jsx：覆盖<area>的 9 组 invalid 与 valid 场景；
• input.jsx：覆盖<input type="image">的 10 组 invalid 与 valid 场景；
• object.jsx：覆盖<object>的 8 组 invalid 与 valid 场景（含title、可访问子内容两种豁免路径）。

每个.jsx文件对应一份.snap快照（如 img.jsx.snap），精确记录了每条违规的诊断位置与消息，任何判定逻辑的变更都会在快照测试中被捕获。这些夹具同时被website侧文档（useAltText.md）的示例引用，保证文档示例与真实行为始终一致。

常见问题小结

通过useAltText规则，Rome 在 CI 或编辑器集成（VSCode 扩展 / LSP）中即可将无障碍问题前置拦截，帮助团队在编码阶段守住 WCAG 1.1.1 的底线。

• 开发工具
• CLI
• Lint
• 格式化
• 静态分析
• 代码质量
• 构建工具