Stylelint 规则 `custom-property-empty-line-before`：自定义属性空行规范配置全解

Stylelint 规则custom-property-empty-line-before自定义属性空行规范配置全解【免费下载链接】stylelintA mighty CSS linter that helps you avoid errors and enforce conventions.项目地址: https://gitcode.com/gh_mirrors/st/stylelint导读custom-property-empty-line-before是 Stylelint 内置规则之一用于要求或禁止自定义属性CSS 变量声明如--foo: pink之前存在空行从而在样式表中统一自定义属性的排版节奏。它在设计系统变量分组、主题变量声明等场景中尤其有用。读完本文你将掌握该规则的全部主/次选项含义、except与ignore的细微差异、共享行注释shared-line comment的特殊处理以及其--fix自动修复能力与底层实现原理可直接在真实项目中落地配置。规则概览它检查什么该规则只作用于自定义属性声明即属性名以--开头的声明isCustomProperty.mjs 中实现为property.startsWith(--)并通过 isStandardSyntaxDeclaration.mjs 过滤掉 SCSS 变量、非标准语法等节点。规则要求自定义属性前面decl.raws.before中要么必须存在空行always要么必须不存在空行never。其核心判定逻辑位于 index.mjs先由主选项得出期望值再被except反向最后与hasEmptyLine(decl.raws.before)的实际值比对不一致即上报。a { top: 10px; /* ← */ --foo: pink; /* ↑ */ } /* ↑ */ /** ↑ * This line */上图中箭头指向的正是规则关注的“声明之前的空行”。该规则是可自动修复fixable的文档中声明meta.fixable trueindex.mjs配合fix选项 可自动为所有该规则报告的问题插入或删除空行。同时该规则没有消息参数message arguments与configure.md#message中的自定义消息机制不产生交互。主选项Primary Options主选项二选一分别对应两种排版风格。always要求空行{ custom-property-empty-line-before: always }以下写法视为问题相邻的自定义属性之间没有空行a { top: 10px; --foo: pink; --bar: red; }以下写法不视为问题每个自定义属性前都有空行a { top: 10px; --foo: pink; --bar: red; }never禁止空行{ custom-property-empty-line-before: never }以下写法视为问题存在多余空行包括块内第一个声明前有空行a { top: 10px; --foo: pink; --bar: red; }a { --foo: pink; --bar: red; }以下写法不视为问题a { top: 10px; --foo: pink; --bar: red; }a { --foo: pink; --bar: red; }注意never模式下块内首个声明前有换行导致的空行同样会被报告见上方第二个“视为问题”示例这与规则基于decl.raws.before判定的实现一致。次级选项except反向主选项except用于对特定上下文反转主选项的期望值。可取值共 4 个after-block、after-comment、after-custom-property、first-nested。底层通过 optionsMatches 匹配配置匹配时执行expectEmptyLineBefore !expectEmptyLineBeforeindex.mjs。{ except: [array, of, options] }after-block块之后的属性反转“紧跟在规则块或 at-rule 块之后的属性”的空行期望。{ custom-property-empty-line-before: [never, { except: [after-block] }] }以下写法不视为问题never本应禁止空行但after-block反转后允许a { a {} --foo: red; }a { media all {} --foo: red; }底层判定前一个节点是rule或at-rule即视为“在块之后”isAfterBlock.mjs。after-comment注释之后的属性反转“紧跟在注释之后的属性”的空行期望。共享行注释shared-line comment不触发本选项。{ custom-property-empty-line-before: [ always, { except: [after-comment] } ] }以下写法视为问题--bar前有空行但它在独立注释行之后期望被反转为“无空行”a { --foo: pink; /* comment */ --bar: red; }a { --foo: pink; /* comment */ --bar: red; }以下写法不视为问题a { --foo: pink; /* comment */ --bar: red; }a { --foo: pink; /* comment */ --bar: red; }注意上例中--foo: pink; /* comment */属于共享行注释场景--bar并不被视为“跟在注释之后”因此其空行仍按always要求处理。实现上isAfterComment.mjs 只有在“前一节点是注释且该注释不是共享行注释”时才返回true。after-custom-property另一自定义属性之后反转“紧跟在另一自定义属性之后的属性”的空行期望。共享行注释不影响本选项。{ custom-property-empty-line-before: [ always, { except: [after-custom-property] } ] }以下写法视为问题--bar前有空行但它是自定义属性之后期望被反转为“无空行”a { --foo: pink; --bar: red; }a { --foo: pink; /* comment */ --bar: red; }以下写法不视为问题a { --foo: pink; --bar: red; }a { --foo: pink; /* comment */ --bar: red; }底层判定见 isAfterCustomProperty通过 getPreviousNonSharedLineCommentNode.mjs 跳过共享行注释后若前一节点是声明且属性以--开头则命中。first-nested父节点首个嵌套子节点反转“作为其父节点第一个子节点且位于嵌套环境中的自定义属性”的空行期望。{ custom-property-empty-line-before: [ always, { except: [first-nested] } ] }以下写法视为问题--foo是a块内第一个嵌套子节点本不应有空行却存在空行a { --foo: pink; --bar: red; }以下写法不视为问题a { --foo: pink; --bar: red; }底层判定见 isFirstNested.mjs除“节点即parentNode.first”外还考虑与开括号同行注释的情况——若父节点首个节点是同行注释则其后第一个非该注释的节点仍被视为“首个嵌套子节点”。次级选项ignore跳过检查ignore与except不同命中后规则直接跳过该声明、不再检查而非反转期望值。可取值共 4 个after-comment、after-custom-property、first-nested、inside-single-line-block。{ ignore: [array, of, options] }after-comment忽略注释之后的属性{ custom-property-empty-line-before: [ always, { ignore: [after-comment] } ] }以下写法不视为问题--foo在注释之后被直接忽略a { /* comment */ --foo: pink; }after-custom-property忽略自定义属性之后的属性{ custom-property-empty-line-before: [ always, { ignore: [after-custom-property] } ] }以下写法不视为问题--bar跟在--foo之后被忽略而--foo前仍有空行满足alwaysa { --foo: pink; --bar: red; }first-nested忽略父节点首个嵌套子节点{ custom-property-empty-line-before: [ always, { ignore: [first-nested] } ] }以下写法不视为问题--foo是首个嵌套子节点被忽略--bar仍需遵守alwaysa { --foo: pink; --bar: red; }inside-single-line-block忽略单行块内的属性{ custom-property-empty-line-before: [ always, { ignore: [inside-single-line-block] } ] }以下写法不视为问题单行块内无从插空行整体忽略a { --foo: pink; --bar: red; }底层判定父节点为rule或at-rule且其整个块字符串是单行isSingleLineString 判断 blockString 结果时直接returnindex.mjs。各选项组合使用示例except与ignore均可多值组合且可同时使用。以下为测试中验证过的典型组合{ custom-property-empty-line-before: [ always, { except: [first-nested, after-comment, after-custom-property] } ] }{ custom-property-empty-line-before: [ never, { except: [first-nested, after-comment, after-custom-property] } ] }组合逻辑在源码中是顺序执行的先依次检查 4 个ignore任一命中即跳过再计算期望值并应用 4 个except反转index.mjs。从测试可见except: [first-nested, after-comment, after-custom-property]与always/never组合的复杂嵌套样式均可被正确接受见tests/index.mjs。自动修复--fix行为详解规则声明fixable: true--fix模式下会报告自动修复问题。修复由 fixEmptyLinesBefore.mjs 完成期望空行而缺失时action: add→ 调用 addEmptyLineBefore.mjs 在节点前插入一个空行期望无空行而存在时action: remove→ 调用 removeEmptyLinesBefore.mjs 删除空行修复使用context.newline作为换行符因此能保留原有的 LF / CRLF 风格。测试用例tests/index.mjs对fix与computeEditInfo均有断言例如always下a {\n--custom-prop: value;\n}被修复为a {\n\n--custom-prop: value;\n}且给出精确的编辑区间{ range: [3, 4], text: \n\n }never下a {\n\n --custom-prop: value;\n}被修复为a {\n --custom-prop: value;\n}CRLF\r\n场景同样有对应的 fixed 输出与编辑区间断言证明该规则在不同换行符环境下均可安全修复。若你不希望自动改动文件也可仅依赖报告结果手动调整或在 CLI 中不加--fix运行。源码实现要点该规则的完整实现位于 index.mjs关键流程如下选项校验通过 validateOptions 校验主选项仅可为always | never次选项键为except/ignore并限定各自允许值index.mjs校验失败直接返回不产生报告。遍历声明root.walkDecls遍历所有声明先过滤非标准语法与非自定义属性节点index.mjs。忽略判定依次检查ignore的 4 种情况。期望计算与报告计算期望值 → 比对hasEmptyLine→ 不匹配时通过 report 上报消息为Expected empty line before custom property或Expected no empty line before custom propertyindex.mjs并附带fix.apply回调供--fix使用。消息参数messageArgs: []为空数组印证文档所述“没有消息参数”。其中“空行”的判定来自 hasEmptyLine.mjs用正则/\n[\r\t ]*\n/检测节点raws.before中是否存在“两个换行之间只有空白”的片段因此空行行内允许存在空格与制表符。实际项目中的配置建议在.stylelintrc或stylelint.config.mjs中按需启用{ rules: { custom-property-empty-line-before: [always, { except: [first-nested] }] } }常见思路若你习惯将自定义属性集中在声明块顶部并分组可用[always, { except: [first-nested] }]块内首个变量无需空行其余自定义属性之间用空行分组若代码风格趋向紧凑可用never并要求变量组与普通声明之间手动空行混合 SCSS/Less 项目无需担心规则内部已通过isStandardSyntaxDeclaration过滤非标准声明SCSS 变量$var不会触发该规则测试中$var: value场景均在always下接受/正常修复。关于该规则与 Stylelint 其他*-empty-line-before系列规则如at-rule-empty-line-before、rule-empty-line-before、comment-empty-line-before的搭配使用可参考 rules 文档 了解完整规则清单。结语custom-property-empty-line-before通过“主选项定基调 except反转 ignore豁免”的三层设计把“自定义属性前是否有空行”这一看似简单的排版问题做到了细粒度可控且完全支持--fix自动修复兼容 LF/CRLF。结合本文对源码与测试的分析你现在可以针对自己的设计系统与变量组织风格精确配置这一规则并纳入 CI 校验。【免费下载链接】stylelintA mighty CSS linter that helps you avoid errors and enforce conventions.项目地址: https://gitcode.com/gh_mirrors/st/stylelint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考