ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

eslint-plugin-react 的 jsx-pascal-case 规则:强制 JSX 自定义组件使用 PascalCase 命名

eslint-plugin-react 的 jsx-pascal-case 规则:强制 JSX 自定义组件使用 PascalCase 命名 开发工具代码质量静态分析【免费下载链接】eslint-plugin-reactReact-specific linting rules for ESLint项目地址https://gitcode.com/gh_mirrors/es/eslint-plugin-react点击查看免费下载导读jsx-pascal-case是 eslint-plugin-react 提供的一条样式类Stylistic Issues规则用于强制要求用户自定义的 JSX 组件在定义和引用时遵循 PascalCase 命名规范。本文以 规则文档 为骨架结合 规则源码 与 测试用例完整讲解该规则的触发逻辑、allowAllCaps、allowNamespace、allowLeadingUnderscore、ignore四个配置项的语义与实战用法并深入剖析底层校验算法的实现细节帮助你将该规则准确落地到团队 ESLint 配置中。规则概述规则的核心诉求是用户自定义的 JSX 组件必须使用 PascalCase大驼峰命名。例如TestComponent、CSSTransitionGroup都是合规的而Test_component、TEST_COMPONENT则会被报告为错误。规则有一个重要的设计前提React 的 JSX 正是依靠首字母的大小写来区分局部组件类与HTML 标签div /、span /这类小写开头的标签被 React 视为内置 DOM 元素。因此该规则不会对小写字母开头的组件发出警告——因为小写开头的标识符在 JSX 语境下根本不会被当作自定义组件处理也就谈不上命名检查。这一点在 测试用例 中有明确印证testcomponent /、testComponent /、test_component /均被标记为 valid。从源码角度看该规则挂在JSXOpeningElement节点的访问器上。它首先通过jsxUtil.isDOMComponent(node)判断当前元素是否属于 DOM 组件即是否匹配COMPAT_TAG_REGEX /^[a-z]/只检测首字符若是则直接跳过参见 lib/util/jsx.js。随后使用elementType提取组件全名再依次执行命名校验。规则触发示例不正确的写法以下代码会被规则报告为错误Test_component /TEST_COMPONENT /在默认配置下它们都会抛出错误消息Imported JSX component {{name}} must be in PascalCase其中{{name}}会被替换为实际的组件名。对应的错误断言可见 测试用例。正确的写法div /TestComponent /TestComponent div / /TestComponentCSSTransitionGroup /值得注意的细节CSSTransitionGroup虽然是多个大写字母连续排列但它满足 PascalCase 判定详见下文校验算法实现属于合法命名。此外单字符组件名如T /、带数字的组件名如Test1Component /、T3StComp0Nent /以及含非 ASCII 大写字母的组件如Éurströmming /、Año /、Søknad /在测试中也都判定为 valid说明规则对 Unicode 字符与数字有良好支持。规则配置规则接受一个对象作为第二项配置参数完整 schema 如下react/jsx-pascal-case: [enabled, { allowAllCaps: allowAllCaps, allowNamespace: allowNamespace, allowLeadingUnderscore: allowLeadingUnderscore, ignore: ignore }]各参数说明enabled规则开关。0表示关闭1表示警告2表示错误。默认值为0。allowAllCaps可选布尔值设为true时允许全大写命名的组件默认false。allowLeadingUnderscore可选布尔值设为true时允许以下划线开头的组件名默认false。allowNamespace可选布尔值设为true时忽略命名空间形式的组件默认false。ignore可选字符串数组列出在校验过程中需要忽略的组件名支持 minimatch 风格的 glob 通配符。对应地规则源码 中的schema声明了这四个属性均为可选且additionalProperties: false即不允许出现未定义的额外配置项。create函数在入口处通过context.options[0] || {}读取配置并为四个选项设置了默认值allowAllCaps false、allowLeadingUnderscore false、allowNamespace false、ignore []。选项一allowAllCaps当allowAllCaps为true时以下写法视为正确ALLOWED / TEST_COMPONENT /需要注意的是该选项允许的是SCREAMING_SNAKE_CASE全大写加下划线而非任意全大写写法。从 CHANGELOG 可以看到该选项经历了演进allowAllCapsoption now allowsSCREAMING_SNAKE_CASE——即启用后规则会在 PascalCase 与 SCREAMING_SNAKE_CASE 之间取并集任何不满足其中之一的命名都会报错。源码中这一点体现得十分明确当allowAllCaps开启时规则会使用testAllCaps进行二次校验若仍不合格错误消息会切换为usePascalOrSnakeCasemust be in PascalCase or SCREAMING_SNAKE_CASE参见 lib/rules/jsx-pascal-case.js 与 lib/rules/jsx-pascal-case.js。测试用例从正反两面覆盖了该选项的行为合法YMCA /、TEST_COMPONENT /启用allowAllCaps非法TEST_COMPONENT_ /末尾多了一个下划线、TEST-COMPONENT /连字符不合法、__ /allowAllCaps: true但无首字母失败于testAllCaps首字符检查。这说明testAllCaps对命名结构的约束非常严格具体规则见下文算法分析。选项二allowNamespace当allowNamespace为true时命名空间点分隔形式的组件被视为正确Allowed.div / TestComponent.p /该选项针对的是成员表达式形式的组件例如 styled-components 的Styled.h1、UI 库的Typography.P这类写法。源码中的处理逻辑是当组件名包含.时将名字按.拆分为数组逐段校验而allowNamespace开启后循环条件index checkNames.length !allowNamespace使得只要首段通过校验就立即跳出循环不再继续检查后续的命名空间段参见 lib/rules/jsx-pascal-case.js。一个典型场景是Styled.h1 /默认配置下它会报错因为h1段不符合 PascalCase而开启allowNamespace后则通过。测试用例对此有直接对比非法默认Styled.h1 /报usePascalCase错误数据中的name为h1合法启用allowNamespaceStyled.h1 /非法启用allowNamespaceSTYLED.h1 /仍报错因为首段STYLED本身就不是 PascalCase。此外Modal.Header /、qualification.T3StComp0Nent /在默认配置下即为合法Typography.P /亦然。当命名空间段只有单字符如$ /、_ /时源码中splitName.length 1的提前返回逻辑会直接跳过检查。选项三allowLeadingUnderscore当allowLeadingUnderscore为true时以下写法视为正确_AllowedComponent / _AllowedComponent div / /_AllowedComponent源码中的实现是若开启该选项且组件名以_开头则在校验前先把开头的_去掉splitName.startsWith(_) ? splitName.slice(1) : splitName再对剩余部分做 PascalCase 判定参见 lib/rules/jsx-pascal-case.js。测试覆盖的边界情况包括__ /在同时开启allowAllCaps与allowLeadingUnderscore时仍报错去掉一个_后剩_既不是 PascalCase 也不是全大写_div /在开启allowLeadingUnderscore时报错去掉_后剩div小写开头不满足 PascalCase_TEST_COMPONENT /需同时开启allowAllCaps与allowLeadingUnderscore才能通过。重要警告给组件名添加前导下划线不会影响组件的可见性或可访问性。试图用前导下划线来强制私有化组件是错误的做法——JavaScript 并不存在真正意义上的私有组件约定_前缀只是命名习惯规则仅将其视为一种可选的命名风格而非隐私保护机制。选项四ignoreignore接受一个字符串数组用于在校验中跳过特定组件名。它支持 minimatch 风格的 glob 通配符例如react/jsx-pascal-case: [error, { ignore: [Foo_DEPRECATED, *_D*D, *_(DEPRECATED|IGNORED)] }]源码中的匹配逻辑位于ignoreCheck函数先做精确的字符串相等比较若不相等再通过minimatch(name, entry, { noglobstar: true })做 glob 匹配参见 lib/rules/jsx-pascal-case.js。测试用例展示了 glob 的实际效果IGNORED /配合ignore: [IGNORED]精确匹配通过Foo_DEPRECATED /配合ignore: [*_D*D]通过通配符匹配_D 任意 DFoo_DEPRECATED /配合ignore: [*_(DEPRECATED|IGNORED)]通过extglob 分组匹配Foo_DEPRECATED /配合ignore: [*_FOO]仍然报错模式不匹配。注意ignore数组的 schema 声明了uniqueItems: true即数组中不允许出现重复项同时minItems: 0表示允许空数组。底层校验算法解析PascalCase 判定testPascalCase从 lib/rules/jsx-pascal-case.js 可以看出PascalCase 的判定分三步首字符必须是大写字母testUpperCase(name.charAt(0))检查首字符且要求该字符的大写形式不等于小写形式排除数字、符号等无大小写之分的字符。其余字符中不允许出现非字母数字字符逐个检查name.slice(1)任何小写等于大写且非数字的字符如_、-、$都会让整段判定失败。这就是Test_component、TEST_COMPONENT报错的根本原因。其余字符中必须至少有一个小写字母或数字保证名字不是纯全大写。这一步解释了为什么YMCA全大写默认报错而CSSTransitionGroup、BetterThanCSS能通过——它们都包含小写字母。有意思的是testUpperCase的写法char upperCase upperCase ! char.toLowerCase()天然兼容 Unicode 大写字符因此Éurströmming /、Søknad /这类带变音符号的命名可以通过校验。全大写判定testAllCaps当开启allowAllCaps后规则用 lib/rules/jsx-pascal-case.js 中的testAllCaps做补充校验首字符必须是大写字母或数字中间所有字符索引 1 到length - 2必须是大写字母、数字或下划线末字符必须是大写字母或数字。这正是TEST_COMPONENT合法而TEST_COMPONENT_末位下划线、TEST-COMPONENT连字符非法的原因。命名空间与分隔符处理源码对:与.两种分隔符都做了处理lib/rules/jsx-pascal-case.js名字含:时按冒号分割对应 JSX 命名空间语法如Modal:Header /名字含.时按点分割对应成员表达式如Modal.Header /、Typography.P /。分割后的每一段都会独立校验且默认情况下所有段都必须通过只有开启allowNamespace才跳过后续段。单字符段splitName.length 1会被直接放行这也是T /、$ /、_ /不会报错的原因。规则定位与启用方式在 规则注册表 中jsx-pascal-case被注册为jsx-pascal-case。它的meta.docs声明了category: Stylistic Issues——属于代码风格类规则recommended: false——不在 recommended 预设配置中需要团队显式开启。由于它未被纳入 configs/all.js、configs/recommended.js 的默认预设启用方式是在 ESLint 配置文件中显式声明。传统 eslintrc 格式rules: { react/jsx-pascal-case: [error, { allowAllCaps: false, allowNamespace: false, allowLeadingUnderscore: false, ignore: [] }] }扁平化flat config格式export default [ { files: [**/*.{js,jsx,ts,tsx}], plugins: { react: reactPlugin }, rules: { react/jsx-pascal-case: [error, { allowAllCaps: false }], }, }, ];规则在仓库中的演进也值得关注。CHANGELOG 记录了一系列针对性修复支持 Unicode 字符、修复H1误报H1是合法 HTML 标签不应被当作自定义组件、支持 minimatchignore、新增allowNamespace、新增allowLeadingUnderscore、单字符命名空间组件处理等。这些历史变更说明该规则在真实项目中经过了长期打磨边界情况数字、Unicode、成员表达式、命名空间、单字符都已有测试覆盖。何时不使用此规则如果你没有使用 JSX例如纯 JavaScript 项目、或使用其他模板语言则该规则没有任何意义可以直接关闭。此外如果团队项目中有大量既有的非 PascalCase 组件命名且短期无法重构可以先通过ignore数组逐步豁免或暂时降级为warn观察期再逐步收紧为error。小结jsx-pascal-case用一条简单但严谨的规则将 JSX 自定义组件命名统一到 PascalCase充分利用了 React 首字母大小写区分组件与 DOM 标签的语义约定避免了Test_component、TEST_COMPONENT这类容易引发混淆的命名。通过allowAllCaps、allowNamespace、allowLeadingUnderscore与ignore四个选项它又能灵活适配 styled-components、命名空间组件、全大写常量组件等真实场景是值得在每个 React 项目中启用的一条低成本高收益的代码风格规则。赞分享开发工具代码质量静态分析【免费下载链接】eslint-plugin-reactReact-specific linting rules for ESLint项目地址https://gitcode.com/gh_mirrors/es/eslint-plugin-react点击查看免费下载相关推荐使用 eslint-plugin-react 的 react/require-render-return 规则强制类组件 render 方法返回 JSX使用 eslint plugin react 的 react/require render return 规则强制类组件 render 方法返回 JSX re开发工具代码质量静态分析eslint-plugin-react 的 react/self-closing-comp 规则强制无子元素 JSX 组件使用自闭合标签eslint plugin react 的 react/self closing comp 规则强制无子元素 JSX 组件使用自闭合标签 本篇技术指南围绕 e开发工具代码质量静态分析用 Takumi 构建 GitHub PR 代码审查工作流以 Umi 仓库的 review 命令为例用 Takumi 构建 GitHub PR 代码审查工作流以 Umi 仓库的 review 命令为例 导读 本文围绕 Umi 仓库内 .takumi/comm开发工具代码质量静态分析上一篇Wand-Enhancer终极指南3步免费解锁WeMod完整功能下一篇5分钟打造Windows任务栏全能监控中心TrafficMonitor插件完全指南创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表