StyleLint 使用指南

StyleLint 是『一个强大的、现代化的 CSS 检测工具』, 与 ESLint 类似, 是通过定义一系列的编码风格规则帮助我们避免在样式表中出现错误.

安装stylelint

npm install -d -save-dev stylelint

安装stylint-config-standard和stylelint-order

npm install stylelint-config-standard stylelint-order --save-dev

其中，stylelint是运行工具，stylelint-config-standard是stylelint的推荐配置，stylelint-order是CSS属性排序插件(先写定位，再写盒模型，再写内容区样式，最后写 CSS3 相关属性)。

配置方式：

按顺序查找，任何一项有值，就会结束查找

• 在 package.json 中的stylelint属性指定规则

• 在 .stylelintrc 文件中指定，文件格式可以是JSON或者YAML。也可以给该文件加后缀，像这样： .stylelintrc.json , .stylelintrc.yaml , .stylelintrc.yml , .stylelintrc.js

• stylelint.config.js 文件，该文件 exports 一个配置对象

语法格式：

rules优先级大于extends，建议采用extends方式统一管理

module.exports = {
  processors: [],
  plugins: [],
  extends: "stylelint-config-standard", // 这是官方推荐的方式
  rules: {
    "at-rule-empty-line-before": "always"|"never",
    "at-rule-name-case": "lower"|"upper",
    "block-no-empty": true,
  }
};

配置项解析

rules

rules是一个对象，属性名为规则名称，属性值为规则取值，它告诉stylelint该检查什么，该怎么报错。所有规则默认都是关闭的。

所有stylelint的规则详情戳这里。

规则名称

• 由连字符组成的小写单词
• 由两个部分组成：
  • 第一部分描述该规则应用于什么东西
  • 第二部分表示该规则检查了什么

"number-leading-zero"
// ↑          ↑
// the thing  what the rule is checking

规则应用于整个样式表时只包含，第二个部分：

"no-eol-whitespace"
"indentation"
//    ↑
// what the rules are checking

规则取值

规则类型不同，支持的值也不同，所有取值戳这里，以下是几个示例：

{
  "rules": {
    "at-rule-blacklist": string|[],
    "at-rule-empty-line-before": "always"|"never",
    "at-rule-name-case": "lower"|"upper",
    "block-no-empty": true
    ...
  }
}

值为 null 时表示禁用该规则：

{
  "rules": {
    "block-no-empty": null
  }
}

除了规则本身的取值之外，stylelint还支持一些自定义配置，给规则传递一个数组即可，数组第一项是规则值，第二项是自定义配置。

"selector-pseudo-class-no-unknown": [true, {
  "ignorePseudoClasses": ["global"]
}]

通过配置项，你可以指定：

• severity，错误级别，取值"warning"或者"error"。默认情况下，所有规则的错误级别都是"error"，通过defaultSeverity可以修改此默认值。不过，需要针对某规则修改错误级别就需要用到该属性。

"indentation": [2, {
  "severity": "warning"
}]

• message，自定义错误信息。

"color-hex-case": ["lower", {
    "message": "Lowercase letters are easier to distinguish from numbers"
}]

如果你需要严格的定制，写一个自定义格式化器会给你最大控制权

extends 扩展插件

stylelint的配置可以 extend 一个已存在的配置文件(无论是你自己的还是第三方的配置)。当一个配置继承了里一个配置，它将会添加自己的属性并覆盖原有的属性。

你也可以将extends设置为一个数组，每一项都是一个独立的stylelint配置项，后一项将会覆盖前一项，而接下来你自己书写的 rules 规则可以覆盖他们所有。

以下示例中，rules中的indentation和number-leading-zero将会覆盖stylelint-config-standard中对应的规则。

{
  "extends": "stylelint-config-standard",
  "rules": {
    "indentation": "tab",
    "number-leading-zero": null
  }
}

以下，./myExtendableConfig中的配置将会覆盖stylelint-config-standard中的对应配置，而rules中的indentation将会覆盖./myExtendableConfig中对应的规则。

{
  "extends": [
    "stylelint-config-standard",
    "./myExtendableConfig"
  ],
  "rules": {
    "indentation": "tab"
  }
}

说清楚优先级之后，我们来详细了解一下extends的取值情况。

extends的值实际上一个定位器（或者一个包含若干定位器的数组），所有可以通过require来使用的资源都可以作为extends的值。因此，可以使用 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 插件列表：

插件一般是由社区提供的，对stylelint已有规则进行扩展，一般可以支持一些非标准的css语法检查或者其他特殊用途。一个插件会提供一个或者多个检查规则。

plugins是一个数组，包含一组插件的定位器，这些定位器的取值跟extends一致。

plugins声明后还需要在rules中使用它，具体规则名称以及可能的取值需要去查看每个插件的文档。

{
  "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 处理器列表：

你还可以在stylelint的处理流中加入自己的处理函数，就是这里的processors。

processors只能作为  命令行  和  Node API  使用，PostCss的插件会忽略它们。

通过processors，我们可以让styleline去处理html中style标签里面的css代码，MarkDown里面的css代码块或者js里面一段包含css的字符串。

使用方法如下：

{
  "processors": [
    "stylelint-html-processor",
    [ "some-other-processor", { "optionOne": true, "optionTwo": false } ]
  ],
  "rules": {..}
}

processors的每一项也是一个定位器，需要额外的参数时，可以传递一个数组，第一项是定位器，第二项是需要的参数。

获取更多处理器。

defaultSeverity

所有在第二个选项中没有指定严重级别的规则的默认严重级别。severity 可用的值为：

• "warning"
• "error"

ignoreFiles

一个文件匹配规则，或者一组文件匹配规则，来指定需要忽略的文件。

更高效的忽略文件的方法是通过 .stylelintignore 文件或者调整一下你的文件匹配规则。

ignoreFiles方式

// .stylelintignore
*.js
*.png
*.eot
*.ttf
*.woff

片段禁用规则

/* stylelint-disable */
/* （请说明禁止检测的理由）前端组件限制类名 */
  .cropper_topContainer .img-preview {
    border:  none;
  }
/* stylelint-enable */

fix方式

• stylelint --fix 就能搞定 更多语法规则

一键fix

在 package.json 中的 scripts 添加指令，然后 npm run lintcss 即可

{
  "scripts": {
    "lintcss": "stylelint 'src/**/*.css' --fix",
  }
}

手动fix

不放心的话，就针对指定文件自己执行， 文件一定要用""括起来

stylelint "src/less/bulma-cloud.less" --fix

问题排除：

错误提示：

Unexpected unknown at-rule "@function" (at-rule-no-unknown) 

Unexpected unknown at-rule "@each" (at-rule-no-unknown) 

Unexpected unknown at-rule "@if" (at-rule-no-unknown) 

Unexpected unknown at-rule "@return" (at-rule-no-unknown)

最开始只安装了官方推荐的定义规则"stylelint-config-standard",我想是不是我缺少插件的问题，所以我就多安装了一个"stylelint-scss"插件，错误已然存在，最后通过"stylelint-scss"的github找到了答案，就是需要添加排除规则。具体内容请点击访问

添加排除规则之后就好了。

{
  "extends": [
    "stylelint-config-standard",
    "stylelint-config-css-modules"
  ],
  "plugins": [
    "stylelint-scss"
  ],
  "rules": {
    "at-rule-no-unknown": [ true, {
      ignoreAtRules: ['extend', 'at-root', 'debug', 'warn', 'error', 'if', 'else', 'for', 'each', 'while', 'mixin', 'include', 'content', 'return', 'function']
    }]
  }
}

参考：