ESLint object-curly-newline 规则详解:统一对象字面量与解构赋值的大括号换行风格
ESLint object-curly-newline 规则详解:统一对象字面量与解构赋值的大括号换行风格
object-curly-newline 是 ESLint 核心库中的一条布局(layout)类规则,用于强制或禁止对象字面量、解构赋值、命名导入与命名导出中 { 与 } 两侧的换行行为。它服务于"同一种写法只允许一种形式"的团队风格诉求:当一组代码风格指南要求或禁止在大括号内部换行时,本规则可以自动检查并在多数场景下自动修复。读完本文,你将掌握该规则的全部选项语义(always、never、multiline、minProperties、consistent)、四种 AST 节点(对象字面量 / 解构模式 / 命名导入 / 命名导出)的分项配置方法,以及它与 object-curly-spacing、comma-spacing 等相邻规则的配合边界。
规则概览与适用场景
该规则要求或禁止在对象字面量或解构赋值的 { 与其后 token 之间、} 与其前 token 之间出现换行。典型场景包括:
- 风格指南规定"对象内每行一个属性"(如 Airbnb 风格对多行对象的处理),需要保证
{后与}前必须换行; - 风格指南规定"简短对象应保持单行",需要禁止多余的换行;
- 团队中同时存在多行对象与单行对象,但希望二者风格统一、互不混用。
从源码看,该规则实现在 lib/rules/object-curly-newline.js,其 meta 标注 type: "layout"、fixable: "whitespace"(可自动修复换行类问题)、recommended: false(不包含在 eslint:recommended 中),并在 conf/rule-type-list.json 中被归类到 layout 类型。需要说明的是,该规则自 ESLint v8.53.0 起被标记为 deprecated(availableUntil: "11.0.0"),官方在 meta.deprecated 中给出的迁移方案是由 @stylistic/eslint-plugin 的 object-curly-newline 规则继续维护;在当前仓库版本中它依然可用,但新项目可考虑直接采用 Stylistic 插件。
规则检查的四种节点
规则的 create 方法同时注册了四个 AST 节点的监听器(见 lib/rules/object-curly-newline.js 中 return { ObjectExpression, ObjectPattern, ImportDeclaration, ExportNamedDeclaration }):
| 节点类型 | 覆盖语法 | 示例 |
|---|---|---|
ObjectExpression |
对象字面量 | const a = {foo: 1} |
ObjectPattern |
解构赋值模式 | const {foo} = obj |
ImportDeclaration |
命名导入 | import {foo, bar} from 'foo-bar' |
ExportNamedDeclaration |
命名导出 | export {foo, bar} |
对于 ImportDeclaration 与 ExportNamedDeclaration,源码中会先过滤出 ImportSpecifier / ExportSpecifier 类型的 specifier,只有存在命名导入/导出(即存在 {} 花括号形式)时才参与检查;import 'foo' 这类纯副作用导入或 export default 不受影响。
选项配置详解
规则接受字符串选项或对象选项两种形式,也支持按节点类型分别配置。
字符串选项
"always":要求{之后与}之前必须有换行;"never":禁止{之后与}之前出现换行。
对象选项
"multiline": true:当属性内部或属性之间存在换行时要求换行,否则禁止换行;"minProperties":当属性数量达到给定整数时要求换行。默认情况下,对象实际含换行但属性数少于该整数时也会报错;但当"consistent": true时,后一种行为(属性不足却含换行)不再报错;"consistent": true(默认值):要求左右两个花括号要么都直接包含换行,要么都不包含。注意启用该选项会同时改变minProperties的行为(见上)。
按节点类型分项配置
可以为对象字面量、解构赋值、命名导入、命名导出分别指定不同选项:
{
"object-curly-newline": ["error", {
"ObjectExpression": "always",
"ObjectPattern": { "multiline": true },
"ImportDeclaration": "never",
"ExportDeclaration": { "multiline": true, "minProperties": 3 }
}]
}
"ObjectExpression":对象字面量的配置;"ObjectPattern":解构赋值对象模式的配置;"ImportDeclaration":命名导入的配置;"ExportDeclaration":命名导出的配置。
未显式配置的节点类型会回退到整体默认值。
源码中的参数归一化逻辑
理解选项语义最直接的方式是阅读源码。在 lib/rules/object-curly-newline.js 中,normalizeOptionValue 把任何形式的选项归一化为 { multiline, minProperties, consistent } 三元组:
| 传入选项 | multiline |
minProperties |
consistent |
|---|---|---|---|
| (未提供) | false |
Infinity |
true |
"always" |
false |
0 |
false |
"never" |
false |
Infinity |
false |
{ "multiline": true } |
true |
Infinity |
false |
{ "minProperties": 2 } |
false |
2 |
false |
{ "consistent": true } |
false |
Infinity |
true |
这解释了文档中的若干"反直觉"行为:
- 默认配置等价于
{ "consistent": true }:空对象{}与多行对象都被允许,但{foo: 1\n}(只有一侧换行)会被报错; "always"的实现是minProperties = 0:任何对象(包括空对象)都要求换行;"never"的实现是minProperties = Infinity:任何对象都禁止换行;minProperties的双重作用:areLineBreaksRequired中判断属性数 >= minProperties成立则要求换行;而属性不足时若对象已有换行,则由consistent决定是否报错(consistent: false时报"多余的换行",consistent: true时不报)。
normalizeOptions 会先判断传入选项是否为"节点特定选项"(对象或字符串),若是则分别归一化 ObjectExpression、ObjectPattern、ImportDeclaration、ExportDeclaration 四项,其中配置键 ExportDeclaration 在内部映射到 AST 节点类型 ExportNamedDeclaration。
always:强制花括号内侧换行
配置 ["error", "always"] 时,incorrect 代码示例:
/*eslint object-curly-newline: ["error", "always"]*/
let a = {};
let b = {foo: 1};
let c = {foo: 1, bar: 2};
let d = {foo: 1,
bar: 2};
let e = {foo() {
dosomething();
}};
let {} = obj;
let {f} = obj;
let {g, h} = obj;
let {i,
j} = obj;
let {k = function() {
dosomething();
}} = obj;
correct 代码示例:
/*eslint object-curly-newline: ["error", "always"]*/
let a = {
};
let b = {
foo: 1
};
let c = {
foo: 1, bar: 2
};
let d = {
foo: 1,
bar: 2
};
let e = {
foo: function() {
dosomething();
}
};
let {
} = obj;
let {
f
} = obj;
let {
g, h
} = obj;
let {
i,
j
} = obj;
let {
k = function() {
dosomething();
}
} = obj;
注意:"always" 只要求 { 后与 } 前换行,并不强制每个属性各占一行,因此 {\n foo: 1, bar: 2\n} 是合法写法。
never:禁止花括号内侧换行
配置 ["error", "never"] 时,incorrect 代码示例:
/*eslint object-curly-newline: ["error", "never"]*/
let a = {
};
let b = {
foo: 1
};
let c = {
foo: 1, bar: 2
};
let d = {
foo: 1,
bar: 2
};
let e = {
foo: function() {
dosomething();
}
};
let {
} = obj;
let {
f
} = obj;
let {
g, h
} = obj;
let {
i,
j
} = obj;
let {
k = function() {
dosomething();
}
} = obj;
correct 代码示例:
/*eslint object-curly-newline: ["error", "never"]*/
let a = {};
let b = {foo: 1};
let c = {foo: 1, bar: 2};
let d = {foo: 1,
bar: 2};
let e = {foo: function() {
dosomething();
}};
let {} = obj;
let {f} = obj;
let {g, h} = obj;
let {i,
j} = obj;
let {k = function() {
dosomething();
}} = obj;
同样,"never" 只约束花括号两侧:属性之间的换行(如 d、e)不受影响,函数体内的换行也属于函数自己的问题。
multiline:随内容多行而换行
配置 ["error", { "multiline": true }] 时,规则只在对象内容跨行时才要求花括号换行,单行内容则保持单行。
incorrect 代码示例:
/*eslint object-curly-newline: ["error", { "multiline": true }]*/
let a = {
};
let b = {
foo: 1
};
let c = {
foo: 1, bar: 2
};
let d = {foo: 1,
bar: 2};
let e = {foo: function() {
dosomething();
}};
let {
} = obj;
let {
f
} = obj;
let {
g, h
} = obj;
let {i,
j} = obj;
let {k = function() {
dosomething();
}} = obj;
correct 代码示例:
/*eslint object-curly-newline: ["error", { "multiline": true }]*/
let a = {};
let b = {foo: 1};
let c = {foo: 1, bar: 2};
let d = {
foo: 1,
bar: 2
};
let e = {
foo: function() {
dosomething();
}
};
let {} = obj;
let {f} = obj;
let {g, h} = obj;
let {
i,
j
} = obj;
let {
k = function() {
dosomething();
}
} = obj;
从源码看,"内容是否多行"由 areLineBreaksRequired 判定:multiline 为真且属性数大于 0 时,比较首属性起始行与末属性结束行(first.loc.start.line !== last.loc.end.line),跨行则要求花括号换行。注意空对象与单行对象在此选项下不被要求换行(对应上述 a、b、c 的 incorrect 情形),因为此时 multiline 分支要求属性数大于 0。
minProperties:属性数达标才换行
配置 ["error", { "minProperties": 2 }] 时,属性数达到 2 的对象要求换行;属性不足 2 时,默认(consistent: false)下若对象却含换行也会报错。
incorrect 代码示例:
/*eslint object-curly-newline: ["error", { "minProperties": 2 }]*/
let a = {
};
let b = {
foo: 1
};
let c = {foo: 1, bar: 2};
let d = {foo: 1,
bar: 2};
let e = {
foo: function() {
dosomething();
}
};
let {
} = obj;
let {
f
} = obj;
let {g, h} = obj;
let {i,
j} = obj;
let {
k = function() {
dosomething();
}
} = obj;
correct 代码示例:
/*eslint object-curly-newline: ["error", { "minProperties": 2 }]*/
let a = {};
let b = {foo: 1};
let c = {
foo: 1, bar: 2
};
let d = {
foo: 1,
bar: 2
};
let e = {foo: function() {
dosomething();
}};
let {} = obj;
let {f} = obj;
let {
g, h
} = obj;
let {
i,
j
} = obj;
let {k = function() {
dosomething();
}} = obj;
逐项对照可看出两条判定同时生效:
a(空对象换行)、b(单属性对象换行)、e(单属性但含换行)属于"属性不足 2 却含换行",在consistent: false下报错;c、d属于"属性数达到 2 但未换行",报错;g, h(两个属性)要求换行,故换行版本正确;k单属性且无花括号换行,正确。
consistent:左右花括号换行状态必须一致
默认配置 ["error", { "consistent": true }](与完全不传选项等价)要求左右花括号的换行状态对称:要么两侧都换行,要么两侧都不换行。
incorrect 代码示例:
/*eslint object-curly-newline: ["error", { "consistent": true }]*/
let a = {foo: 1
};
let b = {
foo: 1};
let c = {foo: 1, bar: 2
};
let d = {
foo: 1, bar: 2};
let e = {foo: function() {
dosomething();
}
};
let f = {
foo: function() {
dosomething();}};
let {g
} = obj;
let {
h} = obj;
let {i, j
} = obj;
let {k, l
} = obj;
let {
m, n} = obj;
let {
o, p} = obj;
let {q = function() {
dosomething();
}
} = obj;
let {
r = function() {
dosomething();
}} = obj;
correct 代码示例:
/*eslint object-curly-newline: ["error", { "consistent": true }]*/
let empty1 = {};
let empty2 = {
};
let a = {foo: 1};
let b = {
foo: 1
};
let c = {
foo: 1, bar: 2
};
let d = {
foo: 1,
bar: 2
};
let e = {foo: function() {dosomething();}};
let f = {
foo: function() {
dosomething();
}
};
let {} = obj;
let {
} = obj;
let {g} = obj;
let {
h
} = obj;
let {i, j} = obj;
let {
k, l
} = obj;
let {m,
n} = obj;
let {
o,
p
} = obj;
let {q = function() {dosomething();}} = obj;
let {
r = function() {
dosomething();
}
} = obj;
correct 示例清晰地展示了判定要点:空对象两种写法({} 与换行的 {\n})都允许;单行对象必须两侧都不换行(a、e、g、q);多行对象必须两侧都换行(b、d、f、h、k、r);而 m,\n n 这种仅属性间换行、花括号两侧不换行的写法也正确,因为 consistent 只关心花括号本身是否直接包围换行,不要求属性逐行。
与 minProperties 组合时,consistent: true 会关闭"属性不足却含换行"的报错分支——源码中 needsLineBreaks 为 false 时才会进入 consistent 检查,此时若两侧一致则放行。测试用例 tests/lib/rules/object-curly-newline.js 中 consistent 与 minProperties 的组合分组对此有专门覆盖。
ObjectExpression 与 ObjectPattern 分项配置
配置 ["error", { "ObjectExpression": "always", "ObjectPattern": "never" }] 时,对象字面量要求换行、解构模式禁止换行,二者互不干扰。
incorrect 代码示例:
/*eslint object-curly-newline: ["error", { "ObjectExpression": "always", "ObjectPattern": "never" }]*/
let a = {};
let b = {foo: 1};
let c = {foo: 1, bar: 2};
let d = {foo: 1,
bar: 2};
let e = {foo: function() {
dosomething();
}};
let {
} = obj;
let {
f
} = obj;
let {
g, h
} = obj;
let {
i,
j
} = obj;
let {
k = function() {
dosomething();
}
} = obj;
correct 代码示例:
/*eslint object-curly-newline: ["error", { "ObjectExpression": "always", "ObjectPattern": "never" }]*/
let a = {
};
let b = {
foo: 1
};
let c = {
foo: 1, bar: 2
};
let d = {
foo: 1,
bar: 2
};
let e = {
foo: function() {
dosomething();
}
};
let {} = obj;
let {f} = obj;
let {g, h} = obj;
let {i,
j} = obj;
let {k = function() {
dosomething();
}} = obj;
左侧对象字面量全部换行、右侧解构模式全部不换行,即为正确形态。这种"按语法场景区别对待"的配置适合项目中对赋值字面量与参数解构采用不同排版约定的情况。
ImportDeclaration 与 ExportDeclaration 分项配置
配置 ["error", { "ImportDeclaration": "always", "ExportDeclaration": "never" }] 时,命名导入要求换行、命名导出禁止换行。
incorrect 代码示例:
/*eslint object-curly-newline: ["error", { "ImportDeclaration": "always", "ExportDeclaration": "never" }]*/
import {foo, bar} from 'foo-bar';
import {foo as f, baz} from 'foo-bar';
import {qux,
foobar} from 'foo-bar';
export {
foo,
bar
};
export {
foo as f,
baz
} from 'foo-bar';
correct 代码示例:
/*eslint object-curly-newline: ["error", { "ImportDeclaration": "always", "ExportDeclaration": "never" }]*/
import {
foo,
bar
} from 'foo-bar';
import {
baz, qux
} from 'foo-bar';
import {
foo as f,
foobar
} from 'foo-bar';
export { foo, bar } from 'foo-bar';
export { foo as f, baz } from 'foo-bar';
注意两点细节:其一,import { baz, qux } 换行但属性同行是合法的,因为 "always" 只要求花括号两侧换行;其二,export ... from 'foo-bar' 这种带来源的再导出同样受规则约束。分项配置使项目可以做到"导入块多行展开、导出保持紧凑"的差异化风格。
自动修复能力与注释边界
规则在 meta.fixable 中声明为 "whitespace",绝大多数违规可通过 eslint --fix 自动修复:
- 需要换行时,修复器在
{后插入\n或在}前插入\n(fixer.insertTextAfter(openBrace, "\n")/fixer.insertTextBefore(closeBrace, "\n")); - 需要去换行时,修复器移除
{与首 token、或末 token 与}之间的空白区间(fixer.removeRange(...))。
但当 { 后或 } 前紧邻注释时,规则不会自动修复。源码中通过 hasCommentsFirstToken / hasCommentsLastToken 判断,命中注释则 fix 返回 null;同时,判断"是否多行"时会把注释 token 纳入考量,而判断"是否需换行"时只用纯 token——这样允许 var obj = { // eslint-disable-line foo 这类带行尾注释的写法在不被误修的前提下参与检查(见 lib/rules/object-curly-newline.js 中相关注释说明)。
测试用例对此有充分验证(tests/lib/rules/object-curly-newline.js):
{ /* comment */ }空对象含注释:报错但output: null(不自动修复);{ // comment\n};:报错但output: null;{\n a: 1, b: 2 // comment\n}:自动修复为{a: 1, b: 2 // comment\n}——行内注释会随属性一起被合并到单行,而注释本身保留。
何时不使用此规则
如果你不希望强制对象花括号内侧的换行一致性,禁用该规则是安全的("object-curly-newline": "off")。该规则属于纯风格(layout)约束,不涉及任何正确性检查,关闭不会带来任何功能性风险。需要说明的是:由于该规则在 ESLint v8.53.0 起进入弃用流程(计划于 11.0.0 移出核心),对于新项目也可以直接在 @stylistic/eslint-plugin 中启用同名的 object-curly-newline 规则以获得长期维护。
与其他规则的协同
原文档在 front matter 中声明了四条相关规则,它们共同构成对象与花括号排版规则族:
- object-curly-spacing:控制
{/}内侧是否需要空格({foo: 1}与{ foo: 1 }之争),与换行规则互补——先决定是否换行,再决定换行后是否加空格; - key-spacing:控制键与冒号、冒号与值之间的对齐与间距;
- comma-spacing:控制逗号前后的空格,配合
object-curly-newline的多行属性写法; - object-property-newline:强制或禁止属性之间的换行——注意
object-curly-newline的"always"并不要求属性逐行,若需要"每个属性一行"的严格风格,应叠加本规则。
兼容性
该规则继承自 JSCS 的两条规则:
- JSCS
requirePaddingNewLinesInObjects:要求对象内部有换行(对应"always"); - JSCS
disallowPaddingNewLinesInObjects:禁止对象内部换行(对应"never")。
从 JSCS 迁移到 ESLint 的项目可将上述两条规则分别映射为本规则的 "always" / "never" 字符串选项。
深入阅读指引
- 规则实现源码:lib/rules/object-curly-newline.js(含选项 schema、归一化逻辑、检查与修复逻辑、弃用元信息)
- 规则测试用例:tests/lib/rules/object-curly-newline.js(1765 行,覆盖全部选项组合、注释边界、Flow 类型标注场景、自动修复输出)
- 规则文档原文:docs/src/rules/object-curly-newline.md
- 规则分类定义:conf/rule-type-list.json(
layout类型)
Flow 相关测试还使用了 tests/fixtures/parsers 下的桩解析器验证带类型标注的解构场景(如 function foo({ a, b } : MyType) {}),说明该规则对 TS/Flow 类型注解下的 } 定位做了专门处理(通过 node.typeAnnotation 定位闭合花括号,见源码 check 函数)。