使用 blueprintjs/eslint-plugin 守护 Blueprint 代码质量规则全景、自动修复与迁移实战【免费下载链接】blueprintA React-based UI toolkit for the web项目地址: https://gitcode.com/gh_mirrors/bl/blueprintBlueprintblueprintjs/*系列包是一套基于 React 的 Web UI 工具包而blueprintjs/eslint-plugin正是官方为其配套的 ESLint 插件提供一组面向 Blueprint 组件库的定制规则。本文以仓库内 packages/eslint-plugin/README.md 为骨架结合源码与测试系统讲解该插件的安装接入、recommended 预设、全部 9 类规则的能力与自动修复行为帮助你在使用 Blueprint 开发时统一类名书写、规范组件用法并平滑完成跨大版本的 API 迁移。一、插件定位与安装blueprintjs/eslint-plugin的核心价值在于它把 Blueprint 团队自身沉淀的代码规范固化为可执行的 ESLint 规则例如强制使用Classes常量而非硬编码 CSS 类名、强制用 Blueprint 组件替代原生 HTML 标签、以及拦截已废弃组件的继续使用。它不依赖类型检查运行成本低适合在 CI 与编辑器内实时反馈。从 packages/eslint-plugin/package.json 可以看到关键约束当前版本6.2.1主入口为lib/index.js由tsc -p src/编译产出peerDependencies声明支持eslint: ^8.57 || ^9.0.0即同时兼容 ESLint 8 与 9运行期仅依赖typescript-eslint/utils与tslib测试基于 Vitest。安装方式作为开发依赖pnpm add --save-dev blueprintjs/eslint-plugin二、接入 ESLint基础配置与 recommended 预设2.1 注册插件在 ESLint 配置中将插件注册为blueprintjs{ plugins: [blueprintjs] }2.2 一键启用全部内置推荐规则使用plugin:blueprintjs/recommended预设即可开启插件在推荐级别提供的全部规则{ extends: [plugin:blueprintjs/recommended] }需要说明的是recommended 预设并非启用插件导出的所有规则而是官方精选的、默认应开启的规则。从插件入口源码 packages/eslint-plugin/src/index.ts 可以看到recommended 实际启用 4 条规则全部以error级别生效规则推荐配置级别blueprintjs/classes-constantserrorblueprintjs/html-componentserrorblueprintjs/no-deprecated-componentserrorblueprintjs/no-deprecated-type-referenceserror2.3 同时支持 flat config插件源码同时导出了flatConfigs.recommended见 src/index.ts因此使用 ESLint 9 的扁平配置flat config时同样可以一键接入import blueprint from blueprintjs/eslint-plugin; export default [ blueprint.configs.recommended, // ...你的其他配置 ];2.4 按需启用单条规则如果你希望渐进式采用或需要为不同代码目录定制策略也可以单独启用某几条规则{ rules: { blueprintjs/classes-constants: error, blueprintjs/no-deprecated-components: error } }三、规则全景与逐条详解插件注册表 packages/eslint-plugin/src/rules/index.ts 导出了 9 条规则其中no-deprecated-components家族又派生出多条按包细分的变体。下面逐一展开。3.1blueprintjs/classes-constants强制使用Classes常量每个blueprintjs包都会导出一个Classes对象其中包含该包定义的所有 CSS 类的常量例如Classes.NAVBAR。本规则禁止在 JSX 与普通代码中直接书写bp6-dark之类的字符串字面量强制改用Classes常量。Rationale设计动机一是避免样式书写与组件拼接时的拼写错误二是面向未来——Blueprint 大版本升级时命名空间前缀如pt-→bp3-→ ... →bp6-会变化改用常量后升级只需更新常量定义代码本身无需改动。配置示例{ rules: { blueprintjs/classes-constants: error } }Has auto-fixer: ✅它可以把硬编码类名自动转换为Classes常量引用- const element div classNamept-navbar /; const element div className{Classes.NAVBAR} /;从实现源码 src/rules/classes-constants.ts 可以看到规则用正则同时识别pt-、bp3-、bp4-、bp5-、bp6-五种前缀的类名并排除以pt-icon或等价前缀开头的图标类名那是icon-components规则的管辖范围const BLUEPRINT_CLASSNAME_PATTERN /(?![\w])((?:pt|bp3|bp4|bp5|bp6)-(?!icon)[\w-])/g;该规则有两个值得注意的实现细节转换算法convertPtClassName去掉前缀、把连字符换成下划线、全部转大写例如bp6-navbar→Classes.NAVBAR自动补 import修复时若检测到文件中尚未引入Classes会自动向blueprintjs/core添加import { Classes } from blueprintjs/core见 classes-constants.ts 中的addImportToFile调用智能包裹若字符串中混有普通文本如bp6-navbar navbar-fixed修复器会把字面量改写为模板字符串并使用${Classes.NAVBAR}插值若该字符串出现在 JSX 属性位置会自动用{}包裹wrapForParent逻辑。3.2blueprintjs/html-components用 Blueprint 组件替代原生 HTML 标签本规则强制在 JSX 中使用 Blueprint 提供的组件替代对应的原生 HTML 标签映射关系如下原生标签替换为h1–h6H1–H6codeCodeprePreblockquoteBlockquotetableHTMLTableRationale设计动机保证常见排版元素与基础标记在视觉上的一致性统一走 Blueprint 的样式体系。Has auto-fixer: ✅配置示例{ rules: { blueprintjs/html-components: [error] } }源码实现见 src/rules/html-components.ts规则用/^(h[1-6]|code|pre|blockquote|table)$/匹配JSXOpeningElement的标签名修复时除了替换开标签还会同步替换对应闭标签closingElement并为新增组件自动补充blueprintjs/core的 import。命名转换规则为table特殊映射为HTMLTable其余标签首字母大写getNewTagName。3.3blueprintjs/icon-componentsIcon 组件与图标名字面量的互转已弃用⚠️DEPRECATED该规则已不再被推荐使用。自 Blueprint v5.x 起图标模块化与 tree-shaking 已成为一等公民能力因此此规则更多是历史遗留方案。本规则强制在 JSX 的icon属性上统一使用具名Icon组件还是IconName字符串字面量。需要特别注意的是它只处理icon属性上的硬编码值无法处理表达式或条件渲染。修复器虽然可用但实现较为朴素可能仍需人工介入例如补充组件 import 或修正非法名称。具名图标组件Tick、Graph等可以从blueprintjs/icons包导入。两种可选配置{ rules: { // 默认使用 component blueprintjs/icon-components // 展开语法 blueprintjs/icon-components: [error, component | literal] // 二选一 } }选项component默认值对应源码中的OPTION_COMPONENT要求使用组件形式——-Button icontick / Button icon{TickIcon /} /选项literal对应OPTION_LITERAL要求使用字面量形式——-Button icon{GraphIcon /} / Button icongraph /实现细节见 src/rules/icon-components.ts规则监听JSXAttribute且仅当属性名为icon时生效component方向把字面量tick通过pascalCase转换成TickIcon /literal方向则通过正则从GraphIcon /中提取组件名并用kebabCase转回graph。README 明确说明该规则之所以没有纳入 recommended 配置是因为它最有价值的应用场景是保证blueprintjs/icons包可被 tree-shaken这是需要全程使用组件、绝不使用IconName字面量的可选流程。3.4blueprintjs/no-deprecated-components禁用已废弃组件这是本插件最核心的规则封禁当前大版本中所有 Blueprint 包内的废弃组件覆盖清单包括README 原文完整列表Breadcrumbs2、ColumnHeaderCell2、ContextMenu2、DateInput、DateInput2、DatePicker、DateRangeInput、DateRangeInput2、DateRangePicker、JSONFormat2、MenuItem2、MultiSelect2、Popover2、ResizeSensor2、RowHeaderCell2、Select2、Suggest2、Tooltip2、TruncatedFormat2Rationale设计动机组件被标记为废弃通常出于两类原因——API 演进中的V1 → V2换代许多 Blueprint 组件在其自然演进过程中产生了下一代变体如Popover2。官方建议消费者尽早从旧的 V1 组件迁移到 V2 对应组件为下一个大版本做准备——届时 V2 将成为唯一可用 APIV1 变体将被移除。虽然deprecation/deprecation这类通用 ESLint 规则也能标记废弃 API但它往往过于宽泛难以在大规模代码库中作为error全局开启。no-deprecated-components提供了一条更简单、更聚焦的规则只标记 JSX 语法中 Blueprint 废弃组件的使用。你可以在迁移过程中把它设为error防止迁移进度倒退。大版本升级后的V2 别名当某代组件 APIV2 或 V3 命名在 Blueprint 的某个大版本中被晋升为标准 V1 API 时官方会为上一大版本中指向同一 API 的 V2 名称保留别名但这些别名会被立即标记为/** deprecated */。例如在 Blueprint v4.x 中{ Popover2 } from blueprintjs/popover2是推荐 API但在 v5.x 中它已被废弃若继续使用Popover2lint 会提示你改为{ Popover } from blueprintjs/core。由于两者在 v5.x 中是互为别名的同一符号这类迁移不会带来任何运行时影响。3.5 按包细分的 deprecation 规则渐进式迁移利器在大规模代码库的迁移中全量开启no-deprecated-components可能过于激进。插件为此提供了一系列按包细分、能力同源的规则让你可以把某个包的废弃组件设为error而其他包的暂时降级为warning逐步处理规则作用范围blueprintjs/no-deprecated-core-components仅检查blueprintjs/coreblueprintjs/no-deprecated-datetime2-components仅检查blueprintjs/datetime2blueprintjs/no-deprecated-popover2-components仅检查blueprintjs/popover2blueprintjs/no-deprecated-select-components仅检查blueprintjs/selectblueprintjs/no-deprecated-table-components仅检查blueprintjs/table例如仅将 core 包的废弃组件作为错误、其余包作为警告的配置思路{ rules: { blueprintjs/no-deprecated-core-components: error, blueprintjs/no-deprecated-components: warn } }从源码看这些规则由同一工厂函数createNoDeprecatedComponentsRule生成差异仅在传入的包列表与映射表。例如 src/rules/no-deprecated-components/no-deprecated-core-components.ts 中的映射代码库当前状态export const coreComponentsMigrationMapping: DeprecatedComponentsConfig { HotkeysTarget2: HotkeysTarget, Overlay: Overlay2, PanelStack2: PanelStack, Popover: PopoverNext, Toast2: Toast, };注意README 记载了no-deprecated-popover2-components这条规则仓库中确实存在其实现文件src/rules/no-deprecated-components/no-deprecated-popover2-components.ts与对应测试test/no-deprecated-popover2-components.test.ts但从当前注册表 src/rules/index.ts 看它尚未被纳入导出的规则集合使用时建议以插件实际导出的规则为准。3.6blueprintjs/no-deprecated-type-references清理废弃的 TS 类型与接口该规则封禁对废弃类型与接口的引用。绝大多数废弃源于 Blueprint 新的 TypeScript 接口命名约定——去掉了接口名的 I 前缀例如IProps已更名为Props。Has auto-fixer: ✅可自动修复规则自带修复器可作为 codemod 直接批量改写代码。Rationale设计动机确保代码与 Blueprint 下一个大版本保持前向兼容并可直接用自动修复完成迁移。实现源码位于 src/rules/no-deprecated-type-references.ts有几个值得了解的机制按包维护的废弃类型清单DEPRECATED_TYPE_REFERENCES_BY_PACKAGE覆盖blueprintjs/core、blueprintjs/datetime、blueprintjs/docs-theme、blueprintjs/popover2、blueprintjs/select、blueprintjs/table六个包清单中的条目通常是字符串如IProps此时规则假定新类型名 去掉 I 前缀slice(1)即Props也支持显式二元组形式[IControlledProps, ControlledProps2]、[IInputGroupProps, InputGroupProps2]、[ITreeNode, TreeNodeInfo]等特殊改名规则监听TSTypeReference与TSInterfaceHeritage节点覆盖let x: IProps、interface A extends IProps以及命名空间形式Blueprint.IProps等多种语法修复时会同步改写 importreplaceImportInFile若新类型名在当前文件已被占用会退化为带Blueprint前缀的别名如BlueprintProps以避免命名冲突。四、deprecation 规则族的底层原理no-deprecated-components及其按包变体共享同一套静态扫描机制核心实现见 src/rules/no-deprecated-components/createNoDeprecatedComponentsRule.ts。理解它的设计对用好这条规则很有帮助1. 不依赖 JSDoc 注释。规则基于一份静态的废弃组件 → 新组件映射表DeprecatedComponentsConfig因此与deprecated/deprecation这类读取deprecated注解的规则完全独立、互不干扰。2. 覆盖丰富的语法形态。从create函数返回的访问器可以看到它同时检查DeprecatedComponent /含自闭合标签的 JSX 用法Blueprint.DeprecatedComponent /命名空间成员表达式用法class Foo extends DeprecatedComponent类继承用法MultiSelect.ofTypeT()这类静态工厂方法用法更细粒度地映射表还支持组件名.属性名形式的键如MenuItem.popoverProps用于标记使用某组件且传了特定 prop的场景。3. 四种消息模板。根据是否涉及特定 prop与新组件是否位于其他包报告消息分为migration、migrationToNewPackage、migrationWithPropUsage、migrationWithPropUsageToNewPackage四种lint 信息会明确给出建议的迁移目标见 createNoDeprecatedComponentsRule.ts。4. 支持 import 别名与命名空间。规则会记录import { Popover as BlueprintPopover }的本地别名localFunctionName别名使用同样会被识别import * as Blueprint的命名空间用法也能被正确追踪。这一点在测试 test/no-deprecated-components.test.ts 中有直接体现——测试用例覆盖了直接导入、别名导入与命名空间导入三种形态并断言报告中的deprecatedComponentName与newComponentName数据。五、测试与质量保障插件自带完整的规则测试套件位于 packages/eslint-plugin/test 目录包含classes-constants、html-components、icon-components、no-deprecated-components、no-deprecated-core-components、no-deprecated-datetime2-components、no-deprecated-popover2-components、no-deprecated-select-components、no-deprecated-table-components、no-deprecated-type-references共 10 个测试文件通过typescript-eslint/rule-tester的RuleTester驱动测试运行命令为pnpm testVitest。例如no-deprecated-components的测试test/no-deprecated-components.test.ts会验证从blueprintjs/core导入Popover后渲染Popover /会被报错并建议迁移到PopoverNext且无论直接导入、Popover as BlueprintPopover别名导入还是import * as Blueprint命名空间导入都能被准确捕获。这些测试是规则行为最可靠的契约说明——如果你怀疑某条规则的行为直接看对应测试即可。六、落地建议综合 README 与源码在实际项目中可以这样组合使用本插件新项目直接使用plugin:blueprintjs/recommendedflat config 用blueprint.configs.recommended白拿 4 条核心规则的error级保护存量大型项目迁移先以warn级别开启no-deprecated-components摸清废弃组件分布再按包拆分为no-deprecated-core-components、no-deprecated-select-components等逐包提升到error防止迁移倒退批量清理类型遗留用no-deprecated-type-references的自动修复作为 codemod一次性把IProps类接口名升级为新约定图标 tree-shaking 专项若追求blueprintjs/icons的极致包体可按需非 recommended开启icon-components的component模式但需接受修复器可能需人工补 import。适用前提与限制插件面向使用blueprintjs/*组件库的 React JSX 项目要求 ESLint 版本为^8.57 || ^9.0.0deprecation 类规则基于静态映射而非类型检查因此requiresTypeChecking: false速度快但无法感知运行时动态拼接的组件名。所有规则均可在 packages/eslint-plugin/README.md 找到权威说明本文涉及的实现细节均可在上述源码与测试路径中进一步验证。【免费下载链接】blueprintA React-based UI toolkit for the web项目地址: https://gitcode.com/gh_mirrors/bl/blueprint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/20 22:29:56 · 阅读 1.2k 使用 @blueprintjs/eslint-plugin 守护 Blueprint 代码质量：规则全景、自动修复与迁移实战
使用 blueprintjs/eslint-plugin 守护 Blueprint 代码质量规则全景、自动修复与迁移实战【免费下载链接】blueprintA React-based UI toolkit for the web项目地址: https://gitcode.com/gh_mirrors/bl/blueprintBlueprintblueprintjs/*系列包是一套基于 React 的 Web UI 工具包而blueprintjs/eslint-plugin正是官方为其配套的 ESLint 插件提供一组面向 Blueprint 组件库的定制规则。本文以仓库内 packages/eslint-plugin/README.md 为骨架结合源码与测试系统讲解该插件的安装接入、recommended 预设、全部 9 类规则的能力与自动修复行为帮助你在使用 Blueprint 开发时统一类名书写、规范组件用法并平滑完成跨大版本的 API 迁移。一、插件定位与安装blueprintjs/eslint-plugin的核心价值在于它把 Blueprint 团队自身沉淀的代码规范固化为可执行的 ESLint 规则例如强制使用Classes常量而非硬编码 CSS 类名、强制用 Blueprint 组件替代原生 HTML 标签、以及拦截已废弃组件的继续使用。它不依赖类型检查运行成本低适合在 CI 与编辑器内实时反馈。从 packages/eslint-plugin/package.json 可以看到关键约束当前版本6.2.1主入口为lib/index.js由tsc -p src/编译产出peerDependencies声明支持eslint: ^8.57 || ^9.0.0即同时兼容 ESLint 8 与 9运行期仅依赖typescript-eslint/utils与tslib测试基于 Vitest。安装方式作为开发依赖pnpm add --save-dev blueprintjs/eslint-plugin二、接入 ESLint基础配置与 recommended 预设2.1 注册插件在 ESLint 配置中将插件注册为blueprintjs{ plugins: [blueprintjs] }2.2 一键启用全部内置推荐规则使用plugin:blueprintjs/recommended预设即可开启插件在推荐级别提供的全部规则{ extends: [plugin:blueprintjs/recommended] }需要说明的是recommended 预设并非启用插件导出的所有规则而是官方精选的、默认应开启的规则。从插件入口源码 packages/eslint-plugin/src/index.ts 可以看到recommended 实际启用 4 条规则全部以error级别生效规则推荐配置级别blueprintjs/classes-constantserrorblueprintjs/html-componentserrorblueprintjs/no-deprecated-componentserrorblueprintjs/no-deprecated-type-referenceserror2.3 同时支持 flat config插件源码同时导出了flatConfigs.recommended见 src/index.ts因此使用 ESLint 9 的扁平配置flat config时同样可以一键接入import blueprint from blueprintjs/eslint-plugin; export default [ blueprint.configs.recommended, // ...你的其他配置 ];2.4 按需启用单条规则如果你希望渐进式采用或需要为不同代码目录定制策略也可以单独启用某几条规则{ rules: { blueprintjs/classes-constants: error, blueprintjs/no-deprecated-components: error } }三、规则全景与逐条详解插件注册表 packages/eslint-plugin/src/rules/index.ts 导出了 9 条规则其中no-deprecated-components家族又派生出多条按包细分的变体。下面逐一展开。3.1blueprintjs/classes-constants强制使用Classes常量每个blueprintjs包都会导出一个Classes对象其中包含该包定义的所有 CSS 类的常量例如Classes.NAVBAR。本规则禁止在 JSX 与普通代码中直接书写bp6-dark之类的字符串字面量强制改用Classes常量。Rationale设计动机一是避免样式书写与组件拼接时的拼写错误二是面向未来——Blueprint 大版本升级时命名空间前缀如pt-→bp3-→ ... →bp6-会变化改用常量后升级只需更新常量定义代码本身无需改动。配置示例{ rules: { blueprintjs/classes-constants: error } }Has auto-fixer: ✅它可以把硬编码类名自动转换为Classes常量引用- const element div classNamept-navbar /; const element div className{Classes.NAVBAR} /;从实现源码 src/rules/classes-constants.ts 可以看到规则用正则同时识别pt-、bp3-、bp4-、bp5-、bp6-五种前缀的类名并排除以pt-icon或等价前缀开头的图标类名那是icon-components规则的管辖范围const BLUEPRINT_CLASSNAME_PATTERN /(?![\w])((?:pt|bp3|bp4|bp5|bp6)-(?!icon)[\w-])/g;该规则有两个值得注意的实现细节转换算法convertPtClassName去掉前缀、把连字符换成下划线、全部转大写例如bp6-navbar→Classes.NAVBAR自动补 import修复时若检测到文件中尚未引入Classes会自动向blueprintjs/core添加import { Classes } from blueprintjs/core见 classes-constants.ts 中的addImportToFile调用智能包裹若字符串中混有普通文本如bp6-navbar navbar-fixed修复器会把字面量改写为模板字符串并使用${Classes.NAVBAR}插值若该字符串出现在 JSX 属性位置会自动用{}包裹wrapForParent逻辑。3.2blueprintjs/html-components用 Blueprint 组件替代原生 HTML 标签本规则强制在 JSX 中使用 Blueprint 提供的组件替代对应的原生 HTML 标签映射关系如下原生标签替换为h1–h6H1–H6codeCodeprePreblockquoteBlockquotetableHTMLTableRationale设计动机保证常见排版元素与基础标记在视觉上的一致性统一走 Blueprint 的样式体系。Has auto-fixer: ✅配置示例{ rules: { blueprintjs/html-components: [error] } }源码实现见 src/rules/html-components.ts规则用/^(h[1-6]|code|pre|blockquote|table)$/匹配JSXOpeningElement的标签名修复时除了替换开标签还会同步替换对应闭标签closingElement并为新增组件自动补充blueprintjs/core的 import。命名转换规则为table特殊映射为HTMLTable其余标签首字母大写getNewTagName。3.3blueprintjs/icon-componentsIcon 组件与图标名字面量的互转已弃用⚠️DEPRECATED该规则已不再被推荐使用。自 Blueprint v5.x 起图标模块化与 tree-shaking 已成为一等公民能力因此此规则更多是历史遗留方案。本规则强制在 JSX 的icon属性上统一使用具名Icon组件还是IconName字符串字面量。需要特别注意的是它只处理icon属性上的硬编码值无法处理表达式或条件渲染。修复器虽然可用但实现较为朴素可能仍需人工介入例如补充组件 import 或修正非法名称。具名图标组件Tick、Graph等可以从blueprintjs/icons包导入。两种可选配置{ rules: { // 默认使用 component blueprintjs/icon-components // 展开语法 blueprintjs/icon-components: [error, component | literal] // 二选一 } }选项component默认值对应源码中的OPTION_COMPONENT要求使用组件形式——-Button icontick / Button icon{TickIcon /} /选项literal对应OPTION_LITERAL要求使用字面量形式——-Button icon{GraphIcon /} / Button icongraph /实现细节见 src/rules/icon-components.ts规则监听JSXAttribute且仅当属性名为icon时生效component方向把字面量tick通过pascalCase转换成TickIcon /literal方向则通过正则从GraphIcon /中提取组件名并用kebabCase转回graph。README 明确说明该规则之所以没有纳入 recommended 配置是因为它最有价值的应用场景是保证blueprintjs/icons包可被 tree-shaken这是需要全程使用组件、绝不使用IconName字面量的可选流程。3.4blueprintjs/no-deprecated-components禁用已废弃组件这是本插件最核心的规则封禁当前大版本中所有 Blueprint 包内的废弃组件覆盖清单包括README 原文完整列表Breadcrumbs2、ColumnHeaderCell2、ContextMenu2、DateInput、DateInput2、DatePicker、DateRangeInput、DateRangeInput2、DateRangePicker、JSONFormat2、MenuItem2、MultiSelect2、Popover2、ResizeSensor2、RowHeaderCell2、Select2、Suggest2、Tooltip2、TruncatedFormat2Rationale设计动机组件被标记为废弃通常出于两类原因——API 演进中的V1 → V2换代许多 Blueprint 组件在其自然演进过程中产生了下一代变体如Popover2。官方建议消费者尽早从旧的 V1 组件迁移到 V2 对应组件为下一个大版本做准备——届时 V2 将成为唯一可用 APIV1 变体将被移除。虽然deprecation/deprecation这类通用 ESLint 规则也能标记废弃 API但它往往过于宽泛难以在大规模代码库中作为error全局开启。no-deprecated-components提供了一条更简单、更聚焦的规则只标记 JSX 语法中 Blueprint 废弃组件的使用。你可以在迁移过程中把它设为error防止迁移进度倒退。大版本升级后的V2 别名当某代组件 APIV2 或 V3 命名在 Blueprint 的某个大版本中被晋升为标准 V1 API 时官方会为上一大版本中指向同一 API 的 V2 名称保留别名但这些别名会被立即标记为/** deprecated */。例如在 Blueprint v4.x 中{ Popover2 } from blueprintjs/popover2是推荐 API但在 v5.x 中它已被废弃若继续使用Popover2lint 会提示你改为{ Popover } from blueprintjs/core。由于两者在 v5.x 中是互为别名的同一符号这类迁移不会带来任何运行时影响。3.5 按包细分的 deprecation 规则渐进式迁移利器在大规模代码库的迁移中全量开启no-deprecated-components可能过于激进。插件为此提供了一系列按包细分、能力同源的规则让你可以把某个包的废弃组件设为error而其他包的暂时降级为warning逐步处理规则作用范围blueprintjs/no-deprecated-core-components仅检查blueprintjs/coreblueprintjs/no-deprecated-datetime2-components仅检查blueprintjs/datetime2blueprintjs/no-deprecated-popover2-components仅检查blueprintjs/popover2blueprintjs/no-deprecated-select-components仅检查blueprintjs/selectblueprintjs/no-deprecated-table-components仅检查blueprintjs/table例如仅将 core 包的废弃组件作为错误、其余包作为警告的配置思路{ rules: { blueprintjs/no-deprecated-core-components: error, blueprintjs/no-deprecated-components: warn } }从源码看这些规则由同一工厂函数createNoDeprecatedComponentsRule生成差异仅在传入的包列表与映射表。例如 src/rules/no-deprecated-components/no-deprecated-core-components.ts 中的映射代码库当前状态export const coreComponentsMigrationMapping: DeprecatedComponentsConfig { HotkeysTarget2: HotkeysTarget, Overlay: Overlay2, PanelStack2: PanelStack, Popover: PopoverNext, Toast2: Toast, };注意README 记载了no-deprecated-popover2-components这条规则仓库中确实存在其实现文件src/rules/no-deprecated-components/no-deprecated-popover2-components.ts与对应测试test/no-deprecated-popover2-components.test.ts但从当前注册表 src/rules/index.ts 看它尚未被纳入导出的规则集合使用时建议以插件实际导出的规则为准。3.6blueprintjs/no-deprecated-type-references清理废弃的 TS 类型与接口该规则封禁对废弃类型与接口的引用。绝大多数废弃源于 Blueprint 新的 TypeScript 接口命名约定——去掉了接口名的 I 前缀例如IProps已更名为Props。Has auto-fixer: ✅可自动修复规则自带修复器可作为 codemod 直接批量改写代码。Rationale设计动机确保代码与 Blueprint 下一个大版本保持前向兼容并可直接用自动修复完成迁移。实现源码位于 src/rules/no-deprecated-type-references.ts有几个值得了解的机制按包维护的废弃类型清单DEPRECATED_TYPE_REFERENCES_BY_PACKAGE覆盖blueprintjs/core、blueprintjs/datetime、blueprintjs/docs-theme、blueprintjs/popover2、blueprintjs/select、blueprintjs/table六个包清单中的条目通常是字符串如IProps此时规则假定新类型名 去掉 I 前缀slice(1)即Props也支持显式二元组形式[IControlledProps, ControlledProps2]、[IInputGroupProps, InputGroupProps2]、[ITreeNode, TreeNodeInfo]等特殊改名规则监听TSTypeReference与TSInterfaceHeritage节点覆盖let x: IProps、interface A extends IProps以及命名空间形式Blueprint.IProps等多种语法修复时会同步改写 importreplaceImportInFile若新类型名在当前文件已被占用会退化为带Blueprint前缀的别名如BlueprintProps以避免命名冲突。四、deprecation 规则族的底层原理no-deprecated-components及其按包变体共享同一套静态扫描机制核心实现见 src/rules/no-deprecated-components/createNoDeprecatedComponentsRule.ts。理解它的设计对用好这条规则很有帮助1. 不依赖 JSDoc 注释。规则基于一份静态的废弃组件 → 新组件映射表DeprecatedComponentsConfig因此与deprecated/deprecation这类读取deprecated注解的规则完全独立、互不干扰。2. 覆盖丰富的语法形态。从create函数返回的访问器可以看到它同时检查DeprecatedComponent /含自闭合标签的 JSX 用法Blueprint.DeprecatedComponent /命名空间成员表达式用法class Foo extends DeprecatedComponent类继承用法MultiSelect.ofTypeT()这类静态工厂方法用法更细粒度地映射表还支持组件名.属性名形式的键如MenuItem.popoverProps用于标记使用某组件且传了特定 prop的场景。3. 四种消息模板。根据是否涉及特定 prop与新组件是否位于其他包报告消息分为migration、migrationToNewPackage、migrationWithPropUsage、migrationWithPropUsageToNewPackage四种lint 信息会明确给出建议的迁移目标见 createNoDeprecatedComponentsRule.ts。4. 支持 import 别名与命名空间。规则会记录import { Popover as BlueprintPopover }的本地别名localFunctionName别名使用同样会被识别import * as Blueprint的命名空间用法也能被正确追踪。这一点在测试 test/no-deprecated-components.test.ts 中有直接体现——测试用例覆盖了直接导入、别名导入与命名空间导入三种形态并断言报告中的deprecatedComponentName与newComponentName数据。五、测试与质量保障插件自带完整的规则测试套件位于 packages/eslint-plugin/test 目录包含classes-constants、html-components、icon-components、no-deprecated-components、no-deprecated-core-components、no-deprecated-datetime2-components、no-deprecated-popover2-components、no-deprecated-select-components、no-deprecated-table-components、no-deprecated-type-references共 10 个测试文件通过typescript-eslint/rule-tester的RuleTester驱动测试运行命令为pnpm testVitest。例如no-deprecated-components的测试test/no-deprecated-components.test.ts会验证从blueprintjs/core导入Popover后渲染Popover /会被报错并建议迁移到PopoverNext且无论直接导入、Popover as BlueprintPopover别名导入还是import * as Blueprint命名空间导入都能被准确捕获。这些测试是规则行为最可靠的契约说明——如果你怀疑某条规则的行为直接看对应测试即可。六、落地建议综合 README 与源码在实际项目中可以这样组合使用本插件新项目直接使用plugin:blueprintjs/recommendedflat config 用blueprint.configs.recommended白拿 4 条核心规则的error级保护存量大型项目迁移先以warn级别开启no-deprecated-components摸清废弃组件分布再按包拆分为no-deprecated-core-components、no-deprecated-select-components等逐包提升到error防止迁移倒退批量清理类型遗留用no-deprecated-type-references的自动修复作为 codemod一次性把IProps类接口名升级为新约定图标 tree-shaking 专项若追求blueprintjs/icons的极致包体可按需非 recommended开启icon-components的component模式但需接受修复器可能需人工补 import。适用前提与限制插件面向使用blueprintjs/*组件库的 React JSX 项目要求 ESLint 版本为^8.57 || ^9.0.0deprecation 类规则基于静态映射而非类型检查因此requiresTypeChecking: false速度快但无法感知运行时动态拼接的组件名。所有规则均可在 packages/eslint-plugin/README.md 找到权威说明本文涉及的实现细节均可在上述源码与测试路径中进一步验证。【免费下载链接】blueprintA React-based UI toolkit for the web项目地址: https://gitcode.com/gh_mirrors/bl/blueprint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考