企业官网建设流程全解析

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

本篇技术指南聚焦 Rome（本仓库统一 JavaScript/TypeScript 与 Web 开发工具链）的 lint 规则useMediaCaption。该规则用于保证页面中的audio与video多媒体元素必须携带用于字幕的track子元素，属于 Rome 默认推荐的 a11y（无障碍）规则。阅读完本文，你将掌握该规则的判定逻辑、合法与非法写法、在rome.json中的配置方式，以及其与 ESLint 插件 jsx-a11ymedia-has-caption的对应关系。

规则概览

规则的核心职责：强制audio和video元素必须包含一个track元素用于字幕（captions）。规则文档位于 website/src/pages/lint/rules/useMediaCaption.md，其声明与注册代码位于 crates/rome_js_analyze/src/analyzers/a11y/use_media_caption.rs。

为什么需要这条规则

字幕（captions）不仅服务于听力障碍用户，也为所有观众提供音频信息的文字呈现。Rome 在规则诊断中给出的注释说明如下：

Captions support users with hearing-impairments. They should be a transcription or translation of the dialogue, sound effects, musical cues, and other relevant audio information.

即：字幕服务于听力受损用户，其内容应当是对话、音效、音乐提示及其他相关音频信息的转录或翻译。这与 HTML 标准中<track kind="captions">的语义一致——captions类型表示对白与关键音效的文字化，而subtitles仅提供翻译文本，不含音效描述，因此该规则只认可kind="captions"。

规则的判定逻辑（源码级解读）

从 crates/rome_js_analyze/src/analyzers/a11y/use_media_caption.rs 的实现可以看出，规则以Ast<AnyJsxElement>为查询对象，逐一对 JSX 元素执行如下判定流程：

1. 元素名匹配：仅当元素的名称 token 为"video"或"audio"时进入检查（源码第 51-52 行）。
2. 跳过条件一：muted属性：若元素带有muted属性（无论取值如何），直接视为合法、不报错（第 53 行）。其语义是静音视频不产生可听内容，因此无需字幕。
3. 跳过条件二：展开属性：若元素带有 JSX 展开属性（spread attribute，如{...props}），规则直接跳过（第 54-57 行）。因为字幕轨道可能通过展开属性注入，静态分析无法确认，规则选择放行以避免误报。
4. 子元素检查：对于显式闭合的<audio>...</audio>/<video>...</video>元素，规则遍历其全部子元素，找出track元素，并要求其kind属性的初始值为字符串"captions"（大小写不敏感，源码第 80-90 行通过to_lowercase()比较）。
5. 判定结果：若元素既非muted、也无展开属性、且不包含kind="captions"的track子元素，则报告诊断。

自闭合形式的<video />/<audio />因为没有子元素可承载track，必然触发诊断（源码第 100 行直接返回节点范围）。

诊断信息由 use_media_caption.rs 生成，主消息为 "Provide atrackfor captions when usingaudioorvideoelements."，并附上上述关于字幕用途的提示。诊断分类lint/a11y/useMediaCaption在 crates/rome_diagnostics_categories/src/categories.rs 中定义。

非法写法（Invalid）

规则文档与源码测试 crates/rome_js_analyze/tests/specs/a11y/useMediaCaption/invalid.jsx 共同覆盖了以下所有触发诊断的写法：

<video />

<audio>child</audio>

<audio><track /></audio>

<audio><track kind="subtitles" /></audio>

<video><track /></video>

<video><track kind="subtitles" /></video>

<video>Foo</video>

<audio>Foo</audio>

需要特别注意的是：仅仅存在<track>元素是不够的，kind必须为captions；kind="subtitles"同样会被判为非法（如上述第 4、6 个示例所示）。命令行运行后，Rome 会输出形如下方的诊断：

a11y/useMediaCaption.js:1:2 lint/a11y/useMediaCaption ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✖ Provide a track for captions when using audio or video elements. > 1 │ <video /> │ ^^^^^^^^ ℹ Captions support users with hearing-impairments. They should be a transcription or translation of the dialogue, sound effects, musical cues, and other relevant audio information.

合法写法（Valid）

规则文档与测试 crates/rome_js_analyze/tests/specs/a11y/useMediaCaption/valid.jsx 覆盖了以下合法场景：

<audio> <track kind="captions" {...props} /> </audio>

<video muted {...props}></video>

规则认可的合法写法类型包括：

• 包含kind="captions"的track子元素：

<audio><track kind="captions" /></audio> <video><track kind="captions" /></video>

• kind取值大小写不敏感，"Captions"同样合法（源码通过to_lowercase()归一化比较）：

<audio><track kind="Captions" /></audio> <video><track kind="Captions" /></video>

• 多个track中只要存在一个kind="captions"即合法：

<audio><track kind="Captions" /><track kind="subtitles" /></audio> <video><track kind="Captions" /><track kind="subtitles" /></video>

• 带muted属性的多媒体元素（属性值true或裸属性均合法）：

<audio muted={true}></audio> <video muted={true}></video> <video muted></video>

• 带展开属性的元素（字幕可能由 props 注入，静态分析放行）：

<audio {...props} /> <video {...props} />

• 非多媒体元素与自定义组件不受影响：

<div /> <MyDiv />

在 rome.json 中配置该规则

useMediaCaption在配置层面对应字段use_media_caption（类型为Option<RuleConfiguration>），定义于 crates/rome_service/src/configuration/linter/rules.rs。由于该规则在 declare_rule! 中标记为recommended: true，它默认随 Rome 的推荐规则集生效，无需显式声明。

如需在项目中显式启用或关闭该规则，可在rome.json的linter.rules.a11y下按名称useMediaCaption配置：

{ "linter": { "rules": { "a11y": { "useMediaCaption": "error" } } } }

常用取值说明：

若需关闭整个 a11y 分组后再单独开启某条规则，可配合分组的recommended开关组合使用。规则属于a11y分组这一事实，与诊断分类路径lint/a11y/useMediaCaption一致。更完整的规则禁用与选项说明，参见仓库中的 linter 文档（对应原文中的 "Disable a rule" 与 "Rule options" 两节）。

与 ESLint jsx-a11y media-has-caption 的对应关系

Rome 官方将该规则标注为 ESLint 插件eslint-plugin-jsx-a11y中media-has-caption规则的等价实现，这一点同时记录在规则文档与 规则源码 的注释中。因此，如果你此前在 ESLint 项目中使用过jsx-a11y/media-has-caption，迁移到 Rome 时可直接用useMediaCaption获得同等的无障碍检查能力，无需重复配置两套规则。

如何验证规则行为

仓库为每条 lint 规则维护了结构化的测试用例，useMediaCaption的输入样例位于 crates/rome_js_analyze/tests/specs/a11y/useMediaCaption/invalid.jsx 与 valid.jsx，对应的诊断快照分别为invalid.jsx.snap与valid.jsx.snap。这些样例覆盖了上文列举的几乎所有边界情况（缺失track、错误kind、大小写、muted、展开属性、自定义组件），是理解规则精确行为的首选参考资料。你也可以直接对自己项目中的 JSX/TSX 文件运行 Rome 的 lint 检查，观察该规则的实际诊断输出。

小结

useMediaCaption是 Rome 默认开启的无障碍 lint 规则之一，通过静态分析 JSX 中的audio/video元素，确保多媒体内容始终提供kind="captions"的字幕轨道，从而兼顾听力受损用户的信息获取需求。掌握它的触发条件（缺track、kind非 captions）与豁免条件（muted、展开属性），即可在日常开发中写出既合规又符合无障碍实践的多媒体代码。

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