企业官网建设流程全解析

ESLint 文档组件库详解：replacementRuleList 宏与规则替换列表的实现与使用

【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint

导读

本文聚焦 ESLint 官方文档站（docs 站点）中docs/src/library/rule-list.md所讲解的replacementRuleList宏组件。该宏负责把“一条已被替换/废弃的规则”渲染为以or分隔的替换规则链接列表，是 ESLint Rules Reference（规则参考）页面中 deprecated/removed 规则展示的核心零件。读完本文，你将掌握该宏的引入方式、参数模型（ReplacedByInfo）、渲染逻辑，以及它与rule宏、rules.json数据文件的完整联动关系，可直接复用于你自己的文档站或组件库开发。

一、组件背景：它解决什么问题

ESLint 的规则会经历"新增 → 推荐 → 弃用（deprecated）→ 移除（removed）"的生命周期。当一条规则被弃用或移除时，文档站需要在规则列表中明确告诉用户"这条规则被什么替代了"。由于替代关系可能是一对多（例如一条旧规则被拆成多条新规则），且替代项可能来自官方核心（eslint 核心）也可能来自社区插件（如@stylistic/eslint-plugin），因此需要一种统一的渲染方式：

• 将一条或多条替代规则渲染成链接；
• 替代规则与插件成对出现，格式为"规则名in插件名"；
• 多条替代规则之间用or分隔；
• 无插件时，规则名本身直接作为链接文本。

replacementRuleList宏就是为此设计的。从源码结构看，它位于 docs/src/_includes/components/rule-list.macro.html，是 docs 站点组件库（docs/src/library/目录专门收录这些组件的使用说明）中的一个 Nunjucks 宏。

二、宏的定义与参数模型

2.1 宏定义位置

宏定义在 rule-list.macro.html，完整实现如下：

{%- macro replacementRuleList(params) -%} {% for specifier in params.specifiers %} <a href="{{ specifier.rule.url if specifier.plugin else specifier.rule.name }}" class="rule-list-item"><code>{{ specifier.rule.name }}</code></a> {% if specifier.plugin %}<span> in <a href="{{ specifier.plugin.url | url }}"><code>{{ specifier.plugin.name }}</code></a> {% endif %} {%- if loop.length > 1 and not loop.last -%} or <br />{%- endif -%} {% endfor %} {%- endmacro -%}

2.2 参数结构：specifiers与ReplacedByInfo

宏只接收一个params对象，核心字段为params.specifiers，它是一个ReplacedByInfo数组。从渲染代码和 docs/src/_data/rules.json 中的真实数据可以归纳出ReplacedByInfo的结构：

从源码结构看，plugin字段是可选的——宏通过if specifier.plugin判断是否存在插件：有插件时输出规则名 in 插件名双链接；无插件时仅输出规则名，且其href直接使用rule.name（此时rule.url为空，链接退化为锚点文本）。

2.3 渲染细节

• or 分隔：当specifiers长度大于 1 且非最后一项时，宏在每一项后面追加or <br />，从而形成"规则A or 规则B"的换行分隔列表；
• 样式钩子：每个链接都带rule-list-itemclass，样式定义见 docs/src/assets/scss/components/rules.scss；
• URL 处理：plugin.url会经过| url过滤器，说明文档站构建时会对插件链接做统一的路径归一化。

三、使用方式

3.1 引入宏

在任意 Nunjucks 模板中，通过from语句导入：

{% from 'components/rule-list.macro.html' import replacementRuleList %}

注意：该路径是相对 docs 站点_includes目录的引用，模板引擎会自动在 docs/src/_includes/components/ 下解析。

3.2 调用宏

向宏传入一个包含specifiers的对象：

{{ replacementRuleList({ specifiers: [{ rule: { name: 'global-require', url: '...' }, plugin: { name: '@eslint-community/eslint-plugin-n', url: '...' } }] }) }}

上述调用会渲染为类似：

global-requirein@eslint-community/eslint-plugin-n

即一条“规则名 + in + 插件名”的替换说明。如果传入多条specifiers，则会以or连接，例如global-requirein@eslint-community/eslint-plugin-norglobal-requireineslint-plugin-n。

四、与rule宏的联动：谁在消费它

replacementRuleList的典型调用方是 rule.macro.html（对应文档 docs/src/library/rule.md）。rule宏接收deprecated/removed/replacedBy等参数，当规则处于 deprecated 或 removed 状态且replacedBy非空时，就会委托replacementRuleList渲染替换列表：

{%- from 'components/rule-list.macro.html' import replacementRuleList -%} {%- if params.deprecated == true -%} {%- if params.replacedBy|length -%} <p class="rule__description">Replaced by {{ replacementRuleList({ specifiers: params.replacedBy }) }}</p> {%- endif -%} {%- elseif params.removed == true -%} {%- if params.replacedBy|length -%} <p class="rule__description">Replaced by {{ replacementRuleList({ specifiers: params.replacedBy }) }}</p> {%- endif -%} {%- endif -%}

也就是说，调用链为：

1. rules.md（Rules Reference 页面）遍历 rules.json 中的deprecated/removed分组；
2. 对每条规则调用rule宏，把the_rule.replacedBy传入；
3. rule宏内部对非空replacedBy再调用replacementRuleList完成链接列表渲染。

五、真实数据示例：ReplacedByInfo 在仓库中的形态

5.1 deprecated 规则的真实数据

在 rules.json 的deprecated分组中，array-bracket-newline的replacedBy数据如下（节选关键字段）：

{ "name": "array-bracket-newline", "replacedBy": [ { "message": "ESLint Stylistic now maintains deprecated stylistic core rules.", "url": "https://eslint.style/guide/migration", "plugin": { "name": "@stylistic/eslint-plugin", "url": "https://eslint.style" }, "rule": { "name": "array-bracket-newline", "url": "https://eslint.style/rules/array-bracket-newline" } } ], "fixable": true, "hasSuggestions": false }

可见真实数据与宏的参数结构完全对齐：replacedBy数组的每个元素就是一个ReplacedByInfo，包含message、plugin、rule三个子对象。

5.2 元数据层：rules_meta.json

rules_meta.json 提供了规则更完整的生命周期信息，例如array-bracket-newline的弃用详情：

"array-bracket-newline": { "deprecated": { "message": "Formatting rules are being moved out of ESLint core.", "url": "https://eslint.org/blog/2023/10/deprecating-formatting-rules/", "deprecatedSince": "8.53.0", "availableUntil": "11.0.0", "replacedBy": [ { "message": "ESLint Stylistic now maintains deprecated stylistic core rules.", "url": "https://eslint.style/guide/migration", "plugin": { "name": "@stylistic/eslint-plugin", "url": "https://eslint.style" }, "rule": { "name": "array-bracket-newline", "url": "https://eslint.style/rules/array-bracket-newline" } } ] }, "type": "layout", ... }

从这里可以看出数据来源：rules_meta.json记录了deprecatedSince（8.53.0 起弃用）、availableUntil（11.0.0 前可用）等元信息，而rules.json中则是按类型分组、供页面渲染用的扁平化视图。

5.3 从仓库推断的覆盖范围

搜索 rules.json 可以发现replacedBy字段在该文件中出现数十次，覆盖了绝大多数 deprecated/removed 规则。这印证了：凡是进入弃用/移除流程的规则，都会通过ReplacedByInfo结构登记替代关系，最终由replacementRuleList统一渲染。核心规则源码中同样存在与之对应的元数据，例如global-require（对应 lib/rules/global-require.js）、no-arrow-condition（对应 lib/rules/no-arrow-condition.js）等被标记移除的规则。

六、在 Rules Reference 页面中的整体呈现

docs/src/pages/rules.md 是规则参考页面的模板，它按类型（problem / suggestion / layout / deprecated / removed）遍历rules.types，并针对 deprecated 与 removed 分组单独处理：

• 普通规则：渲染名称、描述，以及recommended（✅）、fixable（🔧）、hasSuggestions（💡）、frozen（❄️）等分类标记；
• deprecated 规则：名称带deprecated状态标签，若replacedBy非空则显示 "Replaced by ..."；
• removed 规则：名称带removed状态标签，同样展示替换列表。

分类标记的具体渲染逻辑同样在 rule.macro.html 中：recommended用 ✅ 表示“Extends”（即包含在eslint:recommended中）、fixable用 🔧 表示可自动修复、hasSuggestions用 💡 表示可提供建议修复，未启用时通过aria-hidden="true"隐藏，保证可访问性。

七、组件库文档定位：如何查阅其他类似组件

rule-list.md位于 docs/src/library/ 目录，这是 ESLint 文档站的“组件库（component library）”专区，收录了所有可复用组件的使用说明。与本主题强相关的其他组件文档包括：

• docs/src/library/rule.md：rule宏的使用说明，与replacementRuleList属于同一渲染体系；
• docs/src/library/rule-categories.md：规则分类图例组件的说明；
• docs/src/library/related-rules.md：相关规则组件；
• docs/src/library/rule-list.md：即本文主题文档，位于该目录下，同时可参考 docs/src/library/library.json 了解组件库的登记结构。

组件宏本体统一存放在 docs/src/_includes/components/，而组件样式集中在 docs/src/assets/scss/components/rules.scss 中管理。

八、实践小结

在实际开发中，若你需要在自己的 Nunjucks/Jekyll 文档站里实现“规则弃用提示”或“迁移指引”类的链接列表，直接参照该宏的写法即可：用数组承载“替代规则 + 托管插件”的结构，按or拼接渲染，并为每条链接保留独立可点击的<code>文本。这正是 ESLint 文档站中“Replaced by …”提示的底层实现，也是组件库化（macro 化）设计思想的直接体现。

【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint