开发工具CLILint格式化静态分析代码质量构建工具【免费下载链接】toolsUnified developer tools for JavaScript, TypeScript, and the web项目地址https://gitcode.com/gh_mirrors/to/tools点击查看免费下载本指南以 Rome 官方 lint 规则文档useAltText为核心结合仓库源码与测试用例系统讲解该规则的作用范围、判定逻辑、CLI 运行方式与配置方法。读完本文你将掌握如何借助 Rome 在 JSX/TSX 代码中强制为img、area、input typeimage与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就会默认生效无需额外配置。默认情况下规则检查以下四类元素的替代文本元素说明img普通图片必须提供alt或 ARIA 标签area图像映射中的可点击区域input typeimage图像形式提交按钮object嵌入式对象需要title或 ARIA 标签注规则仅作用于 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: truetype Query AstAnyJsxElement规则遍历每个 JSX 元素节点use_alt_text.rsrun方法按元素标签名分派校验逻辑use_alt_text.rs。各元素的判定规则如下img与area必须满足以下任一条件否则报错存在有效的alt属性存在有效的aria-label属性存在有效的aria-labelledby属性。input typeimage仅当元素带有typeimage时才受检查has_type_image_attribute。普通input /、input typefoo /均不触发。校验属性与img相同alt/aria-label/aria-labelledby任一有效即可。object判定逻辑略有不同use_alt_text.rs优先检查title、aria-label、aria-labelledby三者皆无效时若为成对写法object.../object还会检查其内部是否包含可访问的子内容has_accessible_child()——例如objectFoo/object或objectpThis is descriptive!/p/object都算有效自闭合object /且无任何替代文本时直接报错。什么是有效的替代文本源码中两个辅助函数给出了精确定义use_alt_text.rshas_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} /因无法静态判断无效展开属性中可能缺少 altimg alt rolepresentation /有效presentation 角色下空 alt 是规范做法。运行示例错误与正确写法以下示例均来自仓库测试夹具crates/rome_js_analyze/tests/specs/a11y/useAltText 目录下的img.jsx、area.jsx、input.jsx、object.jsx可直接作为实战参考。触发错误的写法Invalidimg srcimage.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 srcimage.png / │ ^^^^^^^^^^^^^^^^^^^^^^^ 2 │ ℹ Meaningful alternative text on elements helps users relying on screen readers to understand contents purpose within a page.诊断消息由 diagnostic 方法 生成随附的ℹ提示解释了规则的无障碍意义。该诊断类别在 crates/rome_diagnostics_categories/src/categories.rs 中注册为lint/a11y/useAltText。其他同样会报错的常见写法input typeimage srcimage.png / area / object / img alt / img alt{undefined} / img alt aria-label / {/* aria-label 空字符串无效 */} img {...this.props} / {/* 展开属性无法确认 alt */} input typeimage aria-label / objectdiv aria-hidden //object {/* 子内容不可访问 */}通过检查的写法Validimg srcimage.png altimage alt / input typeimage srcimage.png altalt text / input typeimage srcimage.png aria-labelalt text / input typeimage srcimage.png aria-labelledbysomeId / area altThis is descriptive! / object titleAn object / objectpThis 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: OptionRuleConfiguration字段该字段的序列化与反序列化逻辑见 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/useAltTextimg.jsx覆盖img的 14 组 invalid 与 30 组 valid 场景area.jsx覆盖area的 9 组 invalid 与 valid 场景input.jsx覆盖input typeimage的 10 组 invalid 与 valid 场景object.jsx覆盖object的 8 组 invalid 与 valid 场景含title、可访问子内容两种豁免路径。每个.jsx文件对应一份.snap快照如 img.jsx.snap精确记录了每条违规的诊断位置与消息任何判定逻辑的变更都会在快照测试中被捕获。这些夹具同时被website侧文档useAltText.md的示例引用保证文档示例与真实行为始终一致。常见问题小结疑问结论空alt会不会报错不会alt对装饰性图片是合法写法没有值的alt布尔属性呢会报错has_valid_alt_text要求属性带初始化器input /会触发吗不会仅input typeimage触发自定义组件Img /会触发吗不会规则对自定义组件首字母大写直接跳过is_custom_component()object能用title代替吗可以title是object特有的有效替代途径动态表达式 alt 呢只要不是静态null/undefined/空串即视为有效通过useAltText规则Rome 在 CI 或编辑器集成VSCode 扩展 / LSP中即可将无障碍问题前置拦截帮助团队在编码阶段守住 WCAG 1.1.1 的底线。赞分享开发工具CLILint格式化静态分析代码质量构建工具【免费下载链接】toolsUnified developer tools for JavaScript, TypeScript, and the web项目地址https://gitcode.com/gh_mirrors/to/tools点击查看免费下载相关推荐Rome 无障碍 lint 规则 useMediaCaption 详解强制 audio/video 元素提供字幕轨道Rome 无障碍 lint 规则 useMediaCaption 详解强制 audio/video 元素提供字幕轨道 本篇技术指南聚焦 Rome本仓库统一开发工具CLILint格式化静态分析代码质量构建工具Rome 无障碍规则 noDistractingElements禁止 marquee 与 blink 等干扰性元素Rome 无障碍规则 noDistractingElements禁止 marquee 与 blink 等干扰性元素 RomeUnified develo开发工具CLILint格式化静态分析代码质量构建工具Rome 无障碍规则 noRedundantAlt 完全指南杜绝 img 替代文本中的冗余措辞Rome 无障碍规则 noRedundantAlt 完全指南杜绝 img 替代文本中的冗余措辞 noRedundantAlt 是 Rome本仓库 unifi开发工具CLILint格式化静态分析代码质量构建工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考