stylelint · 前端笔记

[TOC] # 简介 * stylelint：兼容多种格式的css代码规范工具 * stylelint-config-standard：标准配置规则 * stylelint-order：定义样式的顺序 * stylelint-scss：解析scss规范 * stylelint-webpack-plugin：通过webpack启动 # 安装 ~~~ npm install stylelint stylelint-config-standard stylelint-order stylelint-scss stylelint-webpack-plugin -D ~~~ # 相关文件 * .stylelintrc、stylelint.config.js：配置文件 * .stylelintignore：忽略规则 * .stylelintcache：缓存文件 # 配置 stylelint 使用[cosmiconfig](https://github.com/davidtheclark/cosmiconfig)来完成查找和加载你的配置对象。从当前工作目录开始，它将按以下顺序查找尽可能的来源： * `package.json`中的`stylelint`属性 * `.stylelintrc`文件 * `stylelint.config.js`文件输出的 JS 对象 `.stylelintrc`文件（不带扩展名）可以是 JSON 或 YAML 格式的。或者，你可以添加一个文件扩展名，来区分 JSON，YAML 或 JS 格式：`.stylelintrc.json`，`.stylelintrc.yaml`，`.stylelintrc.js`。你可能想使用一个扩展名，这样你的文本编辑器可以更好的解释文件，以更好进行语法检查和高亮显示。 一旦发现它们中的任何一个，将不再继续进行查找，进行解析，将使用解析后的对象。 当使用`config`或`configFile`选项时，配置文件的搜索可能会停止。 ## 配置对象配置对象可以有以下属性。 ### `rules` 规则决定检测器要查找什么和要解决什么。stylelint 有[超过 150](http://stylelint.cn/user-guide/rules/)条规则。*所有规则默认都是关闭的*，所以，通过该选项你就可以开启相应规则，进行相应的检测。所有规则必须显式的进行配置，因为*没有默认值*。 `rules`属性是个对象，其键为规则名称，值为规则配置。每个规则配置符合以下形式之一： * 一个值 (主要选项) * 包含两个值的数组 (`[primary option, secondary options]`) * `null`(关闭规则) ### `extends` 你的配置可以*extend*一个已存在的配置文件(无论是你自己的还是第三方的配置)。当一个配置继承了里一个配置，它将会添加自己的属性并覆盖原有的属性。 你可以继承一个已存在的配置数组，数组中的每一项都优先于下一项(所以，第一项覆盖所有，第二项覆盖除了第一项之外的所有项，最后一项被其他所有项覆盖，等等)。 例如，继承[`stylelint-config-standard`](https://github.com/stylelint/stylelint-config-standard)，然后将缩进改为 tab 缩进，关闭`number-leading-zero`规则： ~~~javascript { "extends": "stylelint-config-standard", "rules": { "indentation": "tab", "number-leading-zero": null } } ~~~ 或者继承`stylelint-config-standard`和`myExtendableConfig`，并且覆盖缩进规则： ~~~javascript { "extends": [ "stylelint-config-standard", "./myExtendableConfig" ], "rules": { "indentation": "tab" } } ~~~ `"extends"`的值是个“定位器” (或 “定位器” 数组)，也是最终被`require()`的，因此，可以使用 Node 的`require.resolve()`算法适应任何格式。这意味着一个“定位器”可以是： * `node_modules`中的某个模块名称 (比如，`stylelint-config-standard`；模块的`main`文件必须是一个有效的 JSON 配置) * 一个带有`.js`或`.json`扩展名的文件 (which makes sense 如果你在 Node 上下文中创建了一个 JS 对象，并将它传入也是有效的)的绝对路径。 * 一个带有`.js`或`.json`扩展名的文件的相对路径，相对于引用的配置 (例如，如果 configA 是`extends: "../configB"`，我们将查找`configB`相对于 configA)。 * 正因为`extends`，你可以创建和使用可分享的 stylelint 配置。*如果你要发布你的配置到 npm，在你的`package.json`文件中使用`stylelint-config`关键字。 ### `plugins` 插件是由社区创建的规则或规则集，支持方法论、工具集，**非标准** 的 CSS 特性，或非常特定的用例。 * [`stylelint-csstree-validator`](https://github.com/csstree/stylelint-validator)：验证 CSS 的值是否匹配 W3C 标准和浏览器扩展。 * [`stylelint-declaration-strict-value`](https://github.com/AndyOGo/stylelint-declaration-strict-value)：指定变量(`$sass`，`@less`，`var(--cssnext)`)，函数或自定义的 CSS 关键字(`inherit`，`none`等) 的属性是否必须用来做它的值。 * [`stylelint-declaration-use-variable`](https://github.com/sh-waqar/stylelint-declaration-use-variable)：指定哪个变量的属性必须用作它的值 * [`stylelint-order`](https://github.com/hudochenkov/stylelint-order)：指定排序，比如声明的块内(插件包)属性的顺序。 * [`stylelint-rscss`](https://github.com/rstacruz/stylelint-rscss)：验证[RSCSS](http://rscss.io/)约定。 * [`stylelint-scss`](https://github.com/kristerkari/stylelint-scss)：执行各种各样的 SCSS语法特性检测规则(插件包) * [`stylelint-selector-bem-pattern`](https://github.com/davidtheclark/stylelint-selector-bem-pattern): 为选择器指定 BEM 模式(合并了[postcss-bem-linter](https://github.com/postcss/postcss-bem-linter))。 使用插件的话，在你的配置中添加一个`"plugins"`数组，包含“定位器”标识出你要使用的插件。同上面的`extends`，一个“定位器”可以是一个 npm 模块名，一个绝对路径，或一个相对于要调用的配置文件的路径。 一旦声明了插件，在你的`"rules"`对象中，你将需要为插件的规则添加选项，就像其他标准的规则一样。你需要查看插件的文档去了解规则的名称。 ~~~javascript { "plugins": [ "../special-rule.js" ], "rules": { "plugin/special-rule": "everything" } } ~~~ 一个插件可以提供一个规则或一组规则。如果你使用的插件提供了一组规则，就调用`"plugins"`值中的模块，并在`"rules"`中使用它的规则。例如： ~~~javascript { "plugins": [ "../some-rule-set.js" ], "rules": { "some-rule-set/first-rule": "everything", "some-rule-set/second-rule": "nothing", "some-rule-set/third-rule": "everything" } } ~~~ ### `processors` Processors 是 stylelint 的钩子函数，可以以它的方式修改代码，也可以在它们退出时修改结果。 *Processors 只能用在命令行和 Node API，不适用于 PostCSS 插件*(PostCSS 插件将忽略它们。) Processors 可以使 stylelint 检测非样式表文件中的 CSS。例如，你可以检测 HTML 内中`<style>`标签中的 CSS，Markdown文件中代码块或 JavaScript 中的字符串。 使用 processors 的话，在你的配置中添加一个`"processors"`数组，包含“定位器”标识出你要使用的 processors。同上面的`extends`，一个“定位器”可以是一个 npm 模块名，一个绝对路径，或一个相对于要调用的配置文件的路径。 ~~~javascript { "processors": ["stylelint-html-processor"], "rules": {..} } ~~~ 如果你的 processor 有选项，把它们放到一个数组里，第一项是“定位器”，第二项是选项对象。 ~~~javascript { "processors": [ "stylelint-html-processor", [ "some-other-processor", { "optionOne": true, "optionTwo": false } ] ], "rules": {..} } ~~~ ### `ignoreFiles` 提供一个 glob 或 globs 数组，忽略特定的文件。 (另一种方法是使用`.stylelintignore`文件，会在下面描述。) 如果 globs 是绝对路径，就直接使用它们。如果是相对路径，它们将相对： * `configBasedir`，如果有的话； * stylelint 使用的配置的文件路径。 * 或`process.cwd()`。 如果`ignoreFiles`属性被继承的配置移除：只有根配置可以忽略文件。 ### `defaultSeverity` 所有在第二个选项中没有指定严重级别的规则的默认严重级别。 * `"warning"` * `"warning"` * `"error"` * `"error"` 你可以使用一个`.stylelintignore`文件(或指定其他的忽略模式文件)忽略指定的文件。 (另一种方式是使用`config.ignoreFiles`，如上描述。) 你的`.stylelintignore`文件中的模式必须匹配[`.gitignore`语法](https://git-scm.com/docs/gitignore)。(在幕后使用[`node-ignore`](https://github.com/kaelzhang/node-ignore)来解析你的模式。) 这就意味着`*.stylelintignore*`*中模式总是相对于*`*process.cwd()*`*。* styleline 将在`process.cwd()`中查找`.stylelinti` ## 预处理器 linter支持当前和未来的CSS语法。这包括所有标准CSS以及使用标准CSS语法结构的特殊功能，例如特殊的规则，特殊属性和特殊功能。一些*类似*CSS的语言扩展 - 使用非标准语法结构的特性 - 因此受到支持; 然而，由于存在无限的处理可能性，因此linter不能支持所有内容。 您可以在css处理器之前或之后运行linter。根据您使用的处理器，每种方法都有警告： 1. *之前*：某些插件/处理器可能启用与linter不兼容的语法。 2. *之后*：某些插件/处理器可能会生成对您的linter配置无效的CSS，从而导致警告与原始样式表不对应。 **在这两种情况下，您都可以关闭不兼容的linter规则，或者停止使用不兼容的插件/处理器。** 您还可以处理插件/处理器作者并请求替代格式化选项，以使其插件/处理器与stylelint兼容。 默认情况下，linter可以使用特殊的PostCSS解析器*解析*任何以下非标准语法： * SCSS（使用[`postcss-scss`](https://github.com/postcss/postcss-scss)） * LESS（使用[`postcss-less`](https://github.com/webschik/postcss-less)） * SugarSS（使用[`sugarss`](https://github.com/postcss/sugarss)） *非标准语法可以自动从下列文件扩展名推断出：`**.less`，`**.scss`，和`**.sss`。* 但是，如果您需要指定非标准语法，则[CLI](http://stylelint.cn/user-guide/cli/)和[Node API都会](http://stylelint.cn/user-guide/node-api/)公开一个`syntax`选项。 * 如果您使用的是CLI，请使用以下`syntax`标志：`stylelint ... --syntax scss`。 * 如果您正在使用Node API，请传递以下`syntax`选项：`stylelint.lint({ syntax: "sugarss", ... })`。 此外，使用CLI或Node API时，stylelint可以接受与[PostCSS兼容](https://github.com/postcss/postcss#syntaxes)的自定义[语法](https://github.com/postcss/postcss#syntaxes)。对于自定义语法，请分别使用`custom-syntax`和`customSyntax`选项。 * 如果您使用的是CLI，请使用如下`custom-syntax`标志：`stylelint ... --custom-syntax custom-syntax-module`或`stylelint ... --custom-syntax ./path/to/custom-syntax-module`。 * 如果您正在使用Node API，请传递以下`customSyntax`选项：`stylelint.lint({ cus` ## 参考配置 ~~~ module.exports = { 'extends': 'stylelint-config-standard', 'plugins': ['stylelint-order', 'stylelint-scss'], 'rules': { // scss 语法提示 // 参考 https://github.com/stylelint/stylelint/issues/3190 'at-rule-no-unknown': null, 'scss/at-rule-no-unknown': true, // css书写顺序 'order/order': [ 'declarations', 'custom-properties', 'dollar-variables', 'rules', 'at-rules' ], 'order/properties-order': [ 'position', 'z-index', // 其他样式的顺序 ], // 其他规则 'no-empty-source': null, } } ~~~ # 关闭规则从CSS中关闭规则规则可以通过在你的 CSS 中使用特定的注释临时关闭。例如，你可以关闭所有的规则： ~~~javascript /* stylelint-disable */ a {} /* stylelint-enable */ ~~~ 或者你可以关闭个别的规则： ~~~javascript /* stylelint-disable selector-no-id, declaration-no-important */ #id { color: pink !important; } /* stylelint-enable */ ~~~ 你可以使用`/* stylelint-disable-line */`注释在个别的行上关闭规则，在其之后你不需要显式的重新开启它们： ~~~javascript #id { /* stylelint-disable-line */ color: pink !important; /* stylelint-disable-line declaration-no-important */ } ~~~ 你也可以使用`/* stylelint-disable-next-line */`注释在下一行上关闭规则，在其之后你不需要显式的重新开启它们： ~~~javascript #id { /* stylelint-disable-next-line declaration-no-important */ color: pink !important; } ~~~ 复杂、重叠的禁用和启用模式也是支持的： ~~~javascript /* stylelint-disable */ /* stylelint-enable foo */ /* stylelint-disable foo */ /* stylelint-enable */ /* stylelint-disable foo, bar */ /* stylelint-disable baz */ /* stylelint-enable baz, bar */ /* stylelint-enable foo */ ~~~ **警告：***选择器和值列表*中的注释目前是被忽略的。 # webpack 配置 ~~~ // webpack.common.js const StyleLintPlugin = require('stylelint-webpack-plugin') module.exports = { plugins: [ new StyleLintPlugin({ 'files': ['src/**/*.{html,vue,css,sass,scss}'], 'fix': false, 'cache': true }), ], } ~~~ # 参考资料 [stylelint](https://stylelint.io/) [如何为你的 Vue 项目添加配置 Stylelint](https://juejin.im/post/5c31c9a16fb9a049f8197000) [如何在Vue+Webpack下配置Stylelint](https://www.jianshu.com/p/8a33aa5e34b5) [Stylelint 中文开发手册 - 开发者手册 - 云+社区 - 腾讯云](https://cloud.tencent.com/developer/doc/1267)