ESLint array-bracket-newline 规则详解掌控数组方括号内换行排版【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint本篇技术指南围绕 ESLint 核心仓库中的array-bracket-newline规则展开该规则用于强制或禁止在数组方括号[之后与]之前添加换行符是团队统一数组字面量与解构赋值排版风格的关键 layout 类规则。读完本文你将完整掌握其字符串选项always/never/consistent与对象选项multiline/minItems的全部语义、默认值、判定逻辑与自动修复行为并能够结合源码理解其底层实现。规则概览许多风格指南会要求或禁止在数组方括号内部出现换行。array-bracket-newline规则正是为此而生它强制在开方括号之后与闭方括号之前执行换行策略。规则类型layout排版布局类在 lib/rules/array-bracket-newline.js 中声明可自动修复fixable: whitespace即所有报错均可通过eslint --fix自动修正适用节点同时作用于ArrayExpression数组字面量与ArrayPatternES6 解构赋值模式见 lib/rules/array-bracket-newline.js默认行为未配置任何选项时等价于{ multiline: true }即元素或元素之间出现换行时括号内也需要换行关联规则array-bracket-spacing控制方括号内部空格两者常配合使用详见 docs/src/rules/array-bracket-spacing.md。注意该规则自 ESLintv8.53.0起被标记为废弃deprecated原因与理由见下文当前仓库中的废弃状态一节。选项详解本规则接受字符串选项或对象选项两种形式。字符串选项选项含义always要求方括号内部必须有换行never禁止方括号内部出现换行consistent要求每一对方括号的换行使用保持一致若一对括号中某一侧有换行而另一侧没有则报错对象选项对象选项采用任一条件满足则要求换行否则禁止换行的组合逻辑属性默认值含义multilinetrue若元素内部或元素之间存在换行则要求括号内换行设为false时该条件禁用minItemsnull当元素数量达到给定整数时要求括号内换行设为0时行为与always相同设为null默认时该条件禁用字符串选项实战always配置方式/*eslint array-bracket-newline: [error, always]*/不正确的代码/*eslint array-bracket-newline: [error, always]*/ const a []; const b [1]; const c [1, 2]; const d [1, 2]; const e [function foo() { dosomething(); }];正确的代码/*eslint array-bracket-newline: [error, always]*/ const a [ ]; const b [ 1 ]; const c [ 1, 2 ]; const d [ 1, 2 ]; const e [ function foo() { dosomething(); } ];可以看到always强制每个数组包括空数组[]都在[之后和]之前换行。测试用例 tests/lib/rules/array-bracket-newline.js 验证了var foo [[1,2]]与var foo []在always下会自动修复为逐层换行的形式。never配置方式/*eslint array-bracket-newline: [error, never]*/不正确的代码/*eslint array-bracket-newline: [error, never]*/ const a [ ]; const b [ 1 ]; const c [ 1, 2 ]; const d [ 1, 2 ]; const e [ function foo() { dosomething(); } ];正确的代码/*eslint array-bracket-newline: [error, never]*/ const a []; const b [1]; const c [1, 2]; const d [1, 2]; const e [function foo() { dosomething(); }];never与always完全相反括号必须紧贴元素元素内部自身换行不受限制例如[function foo() {\n...\n}]中的函数体换行是允许的只要[与函数开头、函数结尾与]在同一行即可。consistent配置方式/*eslint array-bracket-newline: [error, consistent]*/不正确的代码括号两侧换行不一致/*eslint array-bracket-newline: [error, consistent]*/ const a [1 ]; const b [ 1]; const c [function foo() { dosomething(); } ] const d [ function foo() { dosomething(); }]正确的代码/*eslint array-bracket-newline: [error, consistent]*/ const a []; const b [ ]; const c [1]; const d [ 1 ]; const e [function foo() { dosomething(); }]; const f [ function foo() { dosomething(); } ];consistent的核心思想是开括号后换行则闭括号前也必须换行左侧[之后有换行而右侧]之前没有或反之即为违规。测试 tests/lib/rules/array-bracket-newline.js 覆盖了空数组、单元素数组以及嵌套数组等多种形态。对象选项实战multiline配置方式/*eslint array-bracket-newline: [error, { multiline: true }]*/这也是规则的默认行为不正确的代码/*eslint array-bracket-newline: [error, { multiline: true }]*/ const a [ ]; const b [ 1 ]; const c [ 1, 2 ]; const d [1, 2]; const e [function foo() { dosomething(); }];正确的代码/*eslint array-bracket-newline: [error, { multiline: true }]*/ const a []; const b [1]; const c [1, 2]; const d [ 1, 2 ]; const e [ function foo() { dosomething(); } ];注意这里的微妙之处{ multiline: true }只要求当数组内容本身跨行即首尾元素之间不在同一行时括号才需要换行。因此[1, 2]单行数组 → 不要求换行正确[\n1\n]单元素数组虽然内容只有一行但括号换行了而内容没有跨行反而被判定为不正确——因为元素之间没有换行括号却换行了此时规则要求移除多余换行[\n1,\n2\n]内容跨行 → 必须换行正确。也就是说multiline: true检查的是换行是否必要内容未跨行时多余的括号换行会被报错并自动移除。这一点从源码的判定条件可以清楚看出见下文实现解析。minItems配置方式/*eslint array-bracket-newline: [error, { minItems: 2 }]*/不正确的代码/*eslint array-bracket-newline: [error, { minItems: 2 }]*/ const a [ ]; const b [ 1 ]; const c [1, 2]; const d [1, 2]; const e [ function foo() { dosomething(); } ];正确的代码/*eslint array-bracket-newline: [error, { minItems: 2 }]*/ const a []; const b [1]; const c [ 1, 2 ]; const d [ 1, 2 ]; const e [function foo() { dosomething(); }];minItems: 2的含义是元素数量达到 2 个及以上时要求括号内换行少于 2 个时禁止括号内换行。因此[]与[1]元素数量 2→ 必须单行书写[1, 2]、[1,\n2]元素数量 ≥ 2→ 必须写成[\n1, 2\n]或[\n1,\n2\n]形式[function foo() {...}]虽然元素只有 1 个但元素数量未达阈值括号必须贴紧函数体内部换行不受影响。multiline 与 minItems 组合配置方式/*eslint array-bracket-newline: [error, { multiline: true, minItems: 2 }]*/不正确的代码/*eslint array-bracket-newline: [error, { multiline: true, minItems: 2 }]*/ const a [ ]; const b [ 1 ]; const c [1, 2]; const d [1, 2]; const e [function foo() { dosomething(); }];正确的代码/*eslint array-bracket-newline: [error, { multiline: true, minItems: 2 }]*/ const a []; const b [1]; const c [ 1, 2 ]; const d [ 1, 2 ]; const e [ function foo() { dosomething(); } ];组合使用时采用或逻辑multiline条件或minItems条件任一满足即要求换行。因此示例中的e虽只有 1 个元素但因函数体跨行使multiline条件成立括号必须换行。默认行为未配置选项不写选项时规则等价于{ multiline: true }。其源码归一化逻辑位于 lib/rules/array-bracket-newline.js当option为空时multiline true、minItems Number.POSITIVE_INFINITY即minItems条件永远不触发。测试 tests/lib/rules/array-bracket-newline.js 的 valid 用例验证了默认情况下[]、[1]、[1, 2]均为合法而[\n1, 2\n]这类内容跨行的写法必须保持括号换行。源码级实现解析选项归一化字符串如何映射为对象normalizeOptionValue函数lib/rules/array-bracket-newline.js将各种选项形态统一归一化为{ consistent, multiline, minItems }三要素传入选项consistentmultilineminItems未传falsetrueInfinityalwaysfalsefalse0neverfalsefalseInfinityconsistenttruefalseInfinity{ minItems: 0 }falsefalse0{ multiline: true }等对象falseBoolean(option.multiline)option.minItems \|\| Infinity关键设计always与{ minItems: 0 }殊途同归——minItems归零意味着元素数量 ≥ 0 恒成立即永远要求换行never与consistent都将minItems设为Infinity阈值永不可达两者差异仅在于consistent标志位option.minItems || Number.POSITIVE_INFINITY这一写法使得minItems: null也会落到Infinity与文档所述默认值一致。判定逻辑什么时候需要换行核心判定在check函数lib/rules/array-bracket-newline.js中完成needsLinebreaks为真时要求括号换行为假时禁止换行const needsLinebreaks elements.length options.minItems || (options.multiline elements.length 0 firstIncComment.loc.start.line ! lastIncComment.loc.end.line) || (elements.length 0 firstIncComment.type Block firstIncComment.loc.start.line ! lastIncComment.loc.end.line firstIncComment lastIncComment) || (options.consistent openBracket.loc.end.line ! first.loc.start.line);四个条件逐一解读元素数量达到minItems阈值multiline: true且元素数 0 且首尾 token含注释跨行——这是默认模式的核心判定空数组但包含跨行的块注释如[/* \n多行注释\n */]此时视为内容跨行要求括号换行consistent模式下开括号行尾与首个 token 行首不在同一行——即开括号后换行了则闭括号前也必须换行。实现中特意区分了判断是否多行与判断是否需要换行所用的 token 集合注释被计入多行判定但换行必要性判定只基于真实 token。源码注释中的示例说明这一设计允许以下写法在[后紧跟行注释再换行var arr [ // eslint-disable-line foo a ]自动修复插入与删除换行四条报告路径对应四个messageId全部支持自动修复lib/rules/array-bracket-newline.jsmessageId触发场景修复动作unexpectedOpeningLinebreak[之后不应有换行fixer.removeRange删除[与下一 token 之间空白unexpectedClosingLinebreak]之前不应有换行fixer.removeRange删除上一 token 与]之间空白missingOpeningLinebreak[之后缺少换行fixer.insertTextAfter(token, \n)插入换行missingClosingLinebreak]之前缺少换行fixer.insertTextBefore(token, \n)插入换行值得注意的边界处理在删除换行时如果紧邻的 token 是注释通过astUtils.isCommentToken判断见 lib/rules/utils/ast-utils.js修复函数会返回null放弃修复——这是为了避免删除注释与其所属代码之间的换行导致注释错位。测试 tests/lib/rules/array-bracket-newline.js 中对嵌套数组的 autofix 输出如var foo [[2,\n3]]→var foo [\n[\n2,\n3\n]\n]精确验证了每一层括号的修复结果。覆盖 ArrayPattern解构赋值同样受控check同时挂载在ArrayPattern与ArrayExpression上因此解构赋值同样适用本规则/*eslint array-bracket-newline: [error, always]*/ // 正确 var [ a, b ] foo;测试文件在 tests/lib/rules/array-bracket-newline.js 中为ArrayPattern场景需ecmaVersion: 6逐一验证了默认、always、consistent、{ multiline: true }等选项。与 array-bracket-spacing 配合使用array-bracket-newline的关联规则array-bracket-spacing见 docs/src/rules/array-bracket-spacing.md控制的是空格而非换行两者互补array-bracket-newline控制[后与]前是否换行array-bracket-spacing控制[后与]前是否留空格。一个常见的组合是允许换行但不允许空格——array-bracket-spacing: [error, never]的默认内置例外就允许括号内换行这是常见书写模式而换行的具体策略交给array-bracket-newline裁决。例如// array-bracket-spacing: [error, never] array-bracket-newline: [error, multiline] var arr [ foo, bar ]; // 正确无多余空格内容跨行故括号换行何时不使用此规则如果你不关心数组方括号前后是否换行或者项目已经采用 Prettier 等格式化工具统一排版可以关闭本规则。文档原话为If you dont want to enforce line breaks after opening and before closing array brackets, dont enable this rule.兼容性该规则的前身来自 JSCS 的 validateNewlineAfterArrayElements 检查项ESLint 将其纳入核心规则集并扩展出always/never/consistent及对象选项等更丰富的配置形态。当前仓库中的废弃状态从源码元数据看该规则自ESLint v8.53.0起被标记为废弃lib/rules/array-bracket-newline.js废弃原因是格式化类规则正在移出 ESLint 核心并计划在 v11.0.0 之前从核心移除。官方建议的迁移路径是使用 ESLint Stylistic 项目维护的stylistic/eslint-plugin插件其中的array-bracket-newline规则提供了同名替代实现。因此在现有新代码库中更推荐直接采用stylistic/eslint-plugin的对应规则来管理数组括号换行风格。参考路径规则文档docs/src/rules/array-bracket-newline.md规则实现lib/rules/array-bracket-newline.js规则测试tests/lib/rules/array-bracket-newline.js辅助工具lib/rules/utils/ast-utils.js关联规则文档docs/src/rules/array-bracket-spacing.md【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考