stylelint 的 import-notation 规则：统一 `@import` 字符串与 url() 写法

stylelint 的 import-notation 规则统一import字符串与 url() 写法【免费下载链接】stylelintA mighty CSS linter that helps you avoid errors and enforce conventions.项目地址: https://gitcode.com/gh_mirrors/st/stylelintimport-notation是 stylelint 提供的一类“写法规范化”规则它强制项目中的import规则统一使用**字符串string**或 **url()函数URL**其中一种记号避免同一代码库中两种写法混用。本文以 import-notation/README.md 为骨架结合 规则实现 与 测试用例 深入讲解两种选项的判定标准、自动修复行为、消息参数用法以及底层实现原理帮助你在自己的 stylelint 配置中直接落地这一规则。规则概述它检查什么import-notation的职责是规范import规则的参数写法。在 CSS 中导入外部样式表有两种等价写法import url(x.jpg); /* URL 写法 */ import x.jpg; /* 字符串写法 */规则默认不生效只有在你显式配置string或url后它才会检查每一处import并报告与目标写法不符的代码。如下面这条不符合配置的代码规则会定位到url(...)这个位置import url(x.jpg); /** ↑ * This notation */该规则是**可自动修复fixable**的在 文档中明确说明 了fixable: true的元信息。启用 fix 选项 后所有被该规则报告的问题都可以自动修复无需手改。此外该规则支持2 个消息参数message arguments分别是当前的导入值unfixed和期望的写法fixed。这意味着你可以用自定义消息函数精确指出“import url(x.jpg)应当写成x.jpg”这样的差异详见下文“自定义消息”一节。配置与快速上手在 stylelint 配置文件的rules对象中加入该规则即可。规则接受两个枚举值之一配置非法时会被 validateOptions 拒绝possible: [string, url]并在结果中报告配置错误。{ rules: { import-notation: string } }或{ rules: { import-notation: url } }规则已在 lib/rules/index.mjs 中注册因此无需任何额外加载步骤配置即可生效。选项string必须使用字符串写法配置import-notation: string后所有import规则必须使用字符串写法单引号或双引号均可不允许使用url()函数。{ import-notation: string }以下写法被视为问题违反规则import url(foo.css);import url(foo.css);import url(foo.css);以下写法不被视为问题符合规则import foo.css;import foo.css;从测试用例 lib/rules/import-notation/tests/index.mjs 可以看到字符串模式对带媒体查询、supports()条件的导入同样适用例如import foo.css screen;与import foo.css supports(display: flex) screen and (max-width: 400px);均为合法写法。选项url必须使用 URL 写法配置import-notation: url后所有import规则必须使用url()函数写法。{ import-notation: url }以下写法被视为问题违反规则import foo.css;import foo.css;以下写法不被视为问题符合规则import url(foo.css);import url(foo.css);import url(foo.css);在url模式下url()内部的写法相当宽松允许不带引号url(foo.css)、单引号url(foo.css)和双引号url(foo.css)三种形式测试用例 lib/rules/import-notation/tests/index.mjs 进一步证明函数名大小写url、uRl、URL以及括号内空白url( foo.css )都不影响通过且带print、screen、supports(display: flex)等后续条件的导入也合法。自动修复一条命令统一全部写法该规则的核心卖点是完全可自动修复。根据 fix 选项文档stylelint 提供两种修复模式strict默认使用 PostCSS Parser仅在源码无语法错误时执行修复lax使用 postcss-safe-parser即使存在语法错误也尽可能修复。CLI 用法stylelint src/**/*.css --fixNode.js API 用法启用fix: true后自动修复后的代码会出现在返回对象的code属性中import stylelint from stylelint; const result await stylelint.lint({ files: src/**/*.css, config: { rules: { import-notation: url } }, fix: true, }); // result.code 为修复后的完整代码修复行为的具体表现可以参考测试断言lib/rules/import-notation/tests/index.mjsimport foo.css;在url模式下被修复为import url(foo.css);修复区间为[8, 17]即只替换导入值本身import foo.css print;被修复为import url(foo.css) print;后续条件原样保留import uRl(foo.css);在string模式下被修复为import foo.css;import url(foo.css);在string模式下被修复为import foo.css;自动补上引号。修复只作用于import的参数部分import名称、分号以及后置的媒体查询、supports()条件都不受影响保证修复后语义不变。自定义消息利用 2 个消息参数与多数 stylelint 规则不同import-notation会向消息模板注入2 个参数规则源码unfixed当前的导入写法例如url(foo.css)fixed期望的目标写法例如foo.css。默认消息为Expected ${unfixed} to be ${fixed}。你可以通过 configure.md 的 message 选项 覆盖默认文案例如{ rules: { import-notation: [url, { message: 请统一使用 url() 写法当前为 \%s\期望为 \%s\ }] } }也可以使用函数形式将两个参数用于计算或动态生成消息{ rules: { import-notation: [string, { message: (unfixed, fixed) import 参数应使用字符串写法将 ${unfixed} 改为 ${fixed}, }], }, }两个参数同样可用于函数形式的severity如 configure.md 所述实现按差异内容动态调整告警级别。源码剖析规则是如何判定与修复的实现集中在 lib/rules/import-notation/index.mjs整个流程可分为四个阶段。1. 遍历目标节点规则通过root.walkAtRules(atRuleRegexes.importName, ...)遍历整棵 PostCSS ASTindex.mjs。importName定义于 lib/utils/regexes.mjsimportName: /^import$/i,注意该正则带有i标志说明规则对IMPORT这类大小写变体同样生效即大小写不敏感地匹配 at-rule 名。2. 快速短路判定在深入解析参数之前规则先用正则做一次快速判断index.mjsif (primary string !/url\(/i.test(params)) return; if (primary url /url\(/i.test(params)) return;string模式下若参数里没有url(大小写不敏感直接放行url模式下若参数里有url(直接放行。这样大多数“已经符合要求”的导入可以零成本跳过后续解析。3. 用 postcss-value-parser 精确解析需要深入检查时规则调用valueParser(params)解析参数index.mjs并借助 lib/utils/typeGuards.mjs 中的类型守卫区分节点类型isValueFunctionurl(...)函数节点isValueWord无引号的裸词如foo.cssisValueString带引号的字符串节点isValueSpace空白节点。在string模式下规则寻找url()函数节点将整个函数、其参数分别字符串化后把无引号参数补上双引号作为修复目标index.mjs。在url模式下规则则寻找裸词或字符串节点将其包装为url(...)保留原有引号风格作为修复目标index.mjs。4. 定位与修复位置信息通过 lib/utils/nodeFieldIndices.mjs 的atRuleParamIndex计算——即与 at-rule 名长度之和加上raws.afterName的空白长度从而得到参数在源码中的精确起始索引。修复器fixerindex.mjs只替换参数中导入值对应的那一段它取出node.params.slice(index)用期望写法拼接剩余参数后写入节点。写入过程经由 lib/utils/setAtRuleParams.mjs该工具会优先写入raws.params.raw保留注释等原始内容否则写回atRule.params读取时则使用 lib/utils/getAtRuleParams.mjs 的raws.params?.raw ?? atRule.params逻辑保证修复基于源码原文而非规范化后的文本。这正是“修复后print、supports(...)等后缀原样保留”的实现基础。测试覆盖边界情况一览测试文件 lib/rules/import-notation/tests/index.mjs 覆盖了两组配置[url]与[string]下的 accept / reject 用例可作为理解规则行为的权威参照模式通过accept报告并修复rejecturlurl(foo.css)、uRl(foo.css)、URL(foo.css)、url( foo.css )、带print/supports(...)后缀foo.css、foo.css、foo.css print、带supports(...)的字符串写法stringfoo.css、foo.css、foo.css screen、带supports(...)的字符串写法url(foo.css)、uRl(foo.css)、URL(foo.css)、url( foo.css )、url(foo.css)、url(foo.css) print、带supports(...)的 url 写法测试还同时开启了fix: true与computeEditInfo: true断言了每个修复的精确区间与替换文本如range: [8, 17]、text: url(foo.css)以及报告的行列位置line、column、endLine、endColumn说明该规则与 stylelint 的编辑信息计算编辑器的 Quick Fix 等场景完全兼容。使用建议选择依据如果项目代码风格偏好简洁、接近 CSS 语法糖的写法选string如果偏好显式函数化写法、或与大量使用url()的代码风格保持一致选url。两者在浏览器语义上等价选择完全取决于团队约定。配合--fix使用由于该规则修复完全无损保留引号风格、后续条件强烈建议在 CI 或提交钩子中启用--fix让机器统一写法、杜绝人工争议。注意禁用注释的边界根据 fix 选项文档若源码中存在/* stylelint-disable import-notation */之类的禁用注释被禁用的范围内的问题不会被自动修复——这一点适用于所有可修复规则。与其他导入类规则互补stylelint 还提供了no-duplicate-at-import-rules等导入相关规则见 lib/rules/index.mjs 中的注册列表它们分别负责“重复导入检测”等其他维度import-notation专注写法统一可一并启用形成完整的导入规范。综上import-notation是一个配置成本极低、自动化收益高的规范化规则两种枚举选项覆盖了全部判定逻辑配合--fix与消息参数可以零人工地将整个项目的import写法收敛为单一风格。【免费下载链接】stylelintA mighty CSS linter that helps you avoid errors and enforce conventions.项目地址: https://gitcode.com/gh_mirrors/st/stylelint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考