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 }} classrule-list-itemcode{{ 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的结构字段类型含义渲染行为rule.namestring替代规则名作为链接文本包裹在code中rule.urlstring替代规则链接地址当存在plugin字段时作为a的href无plugin时href直接取rule.nameplugin.namestring托管该规则的插件名在in之后作为插件链接文本plugin.urlstring插件首页/文档链接作为插件a的href经 Nunjucks 的url过滤器处理messagestring替换说明文案可选由上层rule宏消费replacementRuleList本身不直接渲染从源码结构看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.scssURL 处理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-requireineslint-community/eslint-plugin-n即一条“规则名 in 插件名”的替换说明。如果传入多条specifiers则会以or连接例如global-requireineslint-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 classrule__descriptionReplaced by {{ replacementRuleList({ specifiers: params.replacedBy }) }}/p {%- endif -%} {%- elseif params.removed true -%} {%- if params.replacedBy|length -%} p classrule__descriptionReplaced by {{ replacementRuleList({ specifiers: params.replacedBy }) }}/p {%- endif -%} {%- endif -%}也就是说调用链为rules.mdRules Reference 页面遍历 rules.json 中的deprecated/removed分组对每条规则调用rule宏把the_rule.replacedBy传入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.jsonrules_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记录了deprecatedSince8.53.0 起弃用、availableUntil11.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-hiddentrue隐藏保证可访问性。七、组件库文档定位如何查阅其他类似组件rule-list.md位于 docs/src/library/ 目录这是 ESLint 文档站的“组件库component library”专区收录了所有可复用组件的使用说明。与本主题强相关的其他组件文档包括docs/src/library/rule.mdrule宏的使用说明与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 中管理。八、实践小结要点说明宏名称replacementRuleList定义位置docs/src/_includes/components/rule-list.macro.html引入方式{% from components/rule-list.macro.html import replacementRuleList %}核心参数params.specifiersReplacedByInfo数组rule 可选plugin输出形态规则名可选in 插件名链接多条目用or分隔主要调用方rule宏rule.macro.html数据来源rules.json、rules_meta.json应用页面docs/src/pages/rules.mdRules Reference在实际开发中若你需要在自己的 Nunjucks/Jekyll 文档站里实现“规则弃用提示”或“迁移指引”类的链接列表直接参照该宏的写法即可用数组承载“替代规则 托管插件”的结构按or拼接渲染并为每条链接保留独立可点击的code文本。这正是 ESLint 文档站中“Replaced by …”提示的底层实现也是组件库化macro 化设计思想的直接体现。【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ESLint 文档组件库详解：replacementRuleList 宏与规则替换列表的实现与使用
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 }} classrule-list-itemcode{{ 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的结构字段类型含义渲染行为rule.namestring替代规则名作为链接文本包裹在code中rule.urlstring替代规则链接地址当存在plugin字段时作为a的href无plugin时href直接取rule.nameplugin.namestring托管该规则的插件名在in之后作为插件链接文本plugin.urlstring插件首页/文档链接作为插件a的href经 Nunjucks 的url过滤器处理messagestring替换说明文案可选由上层rule宏消费replacementRuleList本身不直接渲染从源码结构看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.scssURL 处理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-requireineslint-community/eslint-plugin-n即一条“规则名 in 插件名”的替换说明。如果传入多条specifiers则会以or连接例如global-requireineslint-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 classrule__descriptionReplaced by {{ replacementRuleList({ specifiers: params.replacedBy }) }}/p {%- endif -%} {%- elseif params.removed true -%} {%- if params.replacedBy|length -%} p classrule__descriptionReplaced by {{ replacementRuleList({ specifiers: params.replacedBy }) }}/p {%- endif -%} {%- endif -%}也就是说调用链为rules.mdRules Reference 页面遍历 rules.json 中的deprecated/removed分组对每条规则调用rule宏把the_rule.replacedBy传入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.jsonrules_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记录了deprecatedSince8.53.0 起弃用、availableUntil11.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-hiddentrue隐藏保证可访问性。七、组件库文档定位如何查阅其他类似组件rule-list.md位于 docs/src/library/ 目录这是 ESLint 文档站的“组件库component library”专区收录了所有可复用组件的使用说明。与本主题强相关的其他组件文档包括docs/src/library/rule.mdrule宏的使用说明与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 中管理。八、实践小结要点说明宏名称replacementRuleList定义位置docs/src/_includes/components/rule-list.macro.html引入方式{% from components/rule-list.macro.html import replacementRuleList %}核心参数params.specifiersReplacedByInfo数组rule 可选plugin输出形态规则名可选in 插件名链接多条目用or分隔主要调用方rule宏rule.macro.html数据来源rules.json、rules_meta.json应用页面docs/src/pages/rules.mdRules Reference在实际开发中若你需要在自己的 Nunjucks/Jekyll 文档站里实现“规则弃用提示”或“迁移指引”类的链接列表直接参照该宏的写法即可用数组承载“替代规则 托管插件”的结构按or拼接渲染并为每条链接保留独立可点击的code文本。这正是 ESLint 文档站中“Replaced by …”提示的底层实现也是组件库化macro 化设计思想的直接体现。【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考