eslint-plugin-react 的 react/jsx-first-prop-new-line 规则详解：统一 JSX 首个属性的换行位置

开发工具代码质量静态分析【免费下载链接】eslint-plugin-reactReact-specific linting rules for ESLint项目地址https://gitcode.com/gh_mirrors/es/eslint-plugin-react点击查看免费下载本篇技术指南围绕 eslint-plugin-react 中的react/jsx-first-prop-new-line规则展开讲解它如何强制规定 JSX 元素第一个属性与组件开标签的相对换行位置并完整覆盖always、never、multiline、multiprop、multiline-multiprop五种配置模式及默认行为。读完本文你将掌握该规则的判定逻辑、自动修复--fix能力与边界不含缩进修复并能根据团队代码风格精准配置这一样式类规则。规则概述解决什么问题react/jsx-first-prop-new-line是 eslint-plugin-react 提供的一条可自动修复fixable: code的样式类规则文档定义在 docs/rules/jsx-first-prop-new-line.md实现位于 lib/rules/jsx-first-prop-new-line.js并在 lib/rules/index.js 中注册。它的作用是检查每个 JSX 元素的第一个属性property是否被放置在正确的位置即第一个属性应该与组件开标签同行还是另起一行。该规则属于 Stylistic Issues风格问题类别meta.docs.recommended为false因此它不在默认的 recommended 配置中需要团队显式开启。从 configs/recommended.js 的规则集合可以看出recommended 仅聚焦正确性问题而这类纯格式规则需要按团队约定自行启用。规则的错误消息定义在源码顶部lib/rules/jsx-first-prop-new-line.js共两条propOnNewLineProperty should be placed on a new line属性应换行放置propOnSameLineProperty should be placed on the same line as the component declaration属性应与组件声明保持同行五种配置模式与默认值规则通过schema限定合法的选项值lib/rules/jsx-first-prop-new-line.jsreact/jsx-first-prop-new-line: always | never | multiline | multiprop | multiline-multiprop各模式的含义如下配置值行为always第一个属性总是另起一行never第一个属性绝不另起一行即始终与组件开标签保持同一行multiline当 JSX 标签占据多行时第一个属性应另起一行multiprop除非存在多个属性否则第一个属性不换行多个属性时才要求第一个属性换行multiline-multiprop当 JSX 标签占据多行且存在多个属性时第一个属性应另起一行。这是默认值其中multiline-multiprop是默认配置源码中const configuration context.options[0] || multiline-multiprop;lib/rules/jsx-first-prop-new-line.js表明即使不传任何选项规则也会以该模式生效。多行标签的判定依据所谓占据多行源码中通过节点位置信息判定lib/rules/jsx-first-prop-new-line.jsfunction isMultilineJSX(jsxNode) { return jsxNode.loc.start.line jsxNode.loc.end.line; }即 JSX 开标签JSXOpeningElement的起始行号小于结束行号就视为多行标签。一个典型的反例是当属性值本身是跨行的对象字面量如foo{{ ... }}写成多行时即使属性与标签名同行整个节点也是多行的——这一点在下面的multiline与multiline-multiprop示例中会反复体现。配置always总是换行当配置为always时第一个属性必须另起一行。规则会在JSXOpeningElement的访问器中无条件触发第一分支源码 lib/rules/jsx-first-prop-new-line.js 中的|| (configuration always)。不正确的代码Hello personal{true} / Hello personal{true} foobar /正确的代码Hello personal / Hello personal /注意always的判定是无条件的只要第一个属性与开标签同行就报错即使标签整体只有一行如Hello personal{true} /也不例外这与默认模式的行为差异明显。配置never总是同行当配置为never时第一个属性必须与组件开标签保持同一行。只要标签存在属性node.attributes.length 0且第一个属性起始行号大于开标签起始行号就触发propOnSameLine报告源码 lib/rules/jsx-first-prop-new-line.js。不正确的代码Hello personal / Hello personal /正确的代码Hello personal{true} / Hello personal{true} foobar /在never模式下后续属性第二个及以后可以自由换行只有第一个属性被约束。配置multiline多行标签时换行当配置为multiline时只有 JSX 标签整体占据多行时才要求第一个属性换行。不正确的代码Hello personal prop /Hello foo{{ }} /第二个例子值得注意foo属性的值是一个跨行的对象字面量导致整个 JSX 节点loc.start.line loc.end.line被判定为多行标签因此第一个属性foo必须换行。正确的代码Hello personal{true} / Hello personal{true} foobar /配置multiprop多属性时换行当配置为multiprop时规则按属性数量分两路处理对应源码中的两个分支当属性数量大于 1node.attributes.length 1时要求第一个属性换行当属性数量小于等于 1 且标签是多行时要求第一个属性与标签名同行第二个分支configuration multiprop isMultilineJSX(node) node.attributes.length 1见 lib/rules/jsx-first-prop-new-line.js。也就是说单个属性即使把标签写成多行也会被拉回同一行而多个属性则要求第一个属性另起一行。不正确的代码Foo propOneone propTwotwo /正确的代码Foo propOneone propTwotwo /测试用例中也覆盖了单属性多行的反例tests/lib/rules/jsx-first-prop-new-line.jsFoo\nbar /会被修复为Foo bar /Foo\n{...this.props} /会被修复为Foo {...this.props} /均报propOnSameLine。这说明展开属性spread props同样被当作属性参与计数与判定。配置multiline-multiprop默认多行且多属性时换行这是规则的默认配置同时要求多行标签与多个属性两个条件成立才强制第一个属性换行。触发条件在源码中为configuration multiline-multiprop isMultilineJSX(node) node.attributes.length 1不正确的代码Hello foo{{ }} bar /这里因为标签整体跨多行、且有两个属性foo、bar所以第一个属性foo必须换行。正确的代码Hello foo{{ }} / Hello foo{{ }} bar /第一个正确示例中虽然foo的值跨行使标签成为多行但只有一个属性不满足多属性条件因此不要求换行第二个示例两个属性均满足条件第一个属性换行后即合规。这一行为与multiline模式形成鲜明对比——multiline只看是否多行不看属性数量因此Hello foo{{ }} /这类单属性多行标签在multiline下反而是违规的见上文配置multiline的错误示例。自动修复机制与缩进边界规则声明了fixable: codelib/rules/jsx-first-prop-new-line.js因此可通过 ESLint 的--fix命令行选项自动修复。修复逻辑分为两类需要换行propOnNewLine将组件名称或类型参数结束位置到第一个属性开始位置之间的文本整体替换为换行符\nlib/rules/jsx-first-prop-new-line.jsfix(fixer) { const nodeTypeArguments propsUtil.getTypeArguments(node); return fixer.replaceTextRange([(nodeTypeArguments || node.name).range[1], decl.range[0]], \n); }需要同行propOnSameLine将组件名称结束位置到第一个属性开始位置之间的文本替换为单个空格 lib/rules/jsx-first-prop-new-line.jsfix(fixer) { return fixer.replaceTextRange([node.name.range[1], firstNode.range[0]], ); }关于修复区间起点源码优先使用propsUtil.getTypeArguments(node)来自 lib/util/props.js兼容typeArguments与typeParameters两种 AST 字段。这意味着带 TypeScript/Flow 泛型参数的 JSX 标签如DataTableItems fullscreen ... /也能被正确处理——修复区间从泛型参数之后开始而不是错误地从组件名之后开始。这一点有测试用例佐证tests/lib/rules/jsx-first-prop-new-line.js在multiline模式下DataTableItems fullscreen keyFieldid items{items} ... /会被修复为DataTableItems\nfullscreen keyFieldid items{items} ... /。重要的边界说明文档原文强调该规则的修复器不包含缩进处理。执行--fix后被换行或拉回同行的属性不会有正确的缩进例如always模式下修复输出形如Foo propOneone propTwotwo /第一行属性propOneone缺少缩进。这正是 tests/lib/rules/jsx-first-prop-new-line.js 中断言的修复结果。文档明确提示修复后请重新运行 lint由其他缩进类规则如react/jsx-indent-props、react/jsx-indent纠正缩进问题。因此在实际工作流中通常的做法是连续执行两次检查或与其他缩进规则协同配合。与相邻规则的配合react/jsx-first-prop-new-line只负责第一个属性是否换行这一件事缩进由其他规则负责。在 eslint-plugin-react 的规则体系中与之紧密配合的包括jsx-indent-props控制 JSX 属性缩进的空格数jsx-max-props-per-line限制每行最多放置的属性数量jsx-props-no-multi-spaces禁止属性间多余空格。这些规则相互独立、各司其职可共同构成完整的 JSX 属性排版约束。由于该规则不包含在 recommended 配置中启用方式是在 ESLint 配置文件的rules中显式声明{ rules: { react/jsx-first-prop-new-line: [error, multiline-multiprop] } }若团队希望让所有规则包括全部样式规则生效可参考 configs/all.js 提供的plugin:react/all配置但更常见的做法是按需开启并明确指定模式。何时不使用此规则文档给出的唯一禁用场景很直接如果你的项目不使用 JSX则无需启用该规则。此外从团队协作角度若项目已通过 Prettier 等格式化工具统一处理换行与缩进或团队对该格式无强一致要求也可以选择关闭此规则避免与自动格式化流程产生冲突。小结react/jsx-first-prop-new-line以五种模式覆盖了 JSX 首个属性换行位置的全部常见诉求从强制的always/never到依赖标签行数与属性数量的multiline/multiprop/multiline-multiprop默认。其判定完全基于 AST 节点的行号loc与属性数量逻辑清晰、可预测且支持--fix自动修复唯一需要注意的边界是修复器不生成缩进修复后需配合缩进类规则或再次运行 lint。若你正在为团队制定 React 代码风格规范这条规则是 JSX 属性排版约束链中不可缺失的一环。规则文档docs/rules/jsx-first-prop-new-line.md规则实现lib/rules/jsx-first-prop-new-line.js测试用例tests/lib/rules/jsx-first-prop-new-line.js属性工具函数lib/util/props.js规则注册入口lib/rules/index.js赞分享开发工具代码质量静态分析【免费下载链接】eslint-plugin-reactReact-specific linting rules for ESLint项目地址https://gitcode.com/gh_mirrors/es/eslint-plugin-react点击查看免费下载相关推荐eslint-plugin-react 的 jsx-max-props-per-line 规则详解限制 JSX 单行属性数量eslint plugin react 的 jsx max props per line 规则详解限制 JSX 单行属性数量 jsx max props pe开发工具代码质量静态分析eslint-plugin-react 的 jsx-one-expression-per-line 规则详解让 JSX 每行只容纳一个表达式eslint plugin react 的 jsx one expression per line 规则详解让 JSX 每行只容纳一个表达式 react/js开发工具代码质量静态分析eslint-plugin-react 规则详解react/jsx-no-duplicate-props 禁止 JSX 重复属性eslint plugin react 规则详解react/jsx no duplicate props 禁止 JSX 重复属性 react/jsx no d开发工具代码质量静态分析上一篇探索DXVK游戏在Linux上的新飞跃下一篇探索音乐新边界核能音乐播放器Nuclear创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考