玩转StyleLint

本文最后更新于：5 个月前

本文由浅入深，依次介绍了Stylelint的入门使用、进阶配置、常用实践。适合新手小白快速上手Stylelint的使用

玩转StyleLint（新手向）

在网上查找学习StyleLint资料的时候，发现很多文章将Stylelint和ESLint、Prettier等其它工具混在一起讲，这并不利于较为系统完整地了解Stylelint这个工具。于是就有了这篇专门讲解StyleLint入门的比较全面一点的文章

一、基本用法

1. 使用介绍

第一步，安装依赖模块和官方的standard配置文件

1
2
npm install --save-dev stylelint stylelint-config-standard
# 安装stylelint依赖模块和standard配置文件

第二步，创建.stylelintrc配置文件，然后输入

1
2
3
{
  "extends": "stylelint-config-standard"
}

第三步（但是通常我们不这么做，而是跳到第四步，直接使用插件），在命令行中输入以下命令，即可检查所有css文件

1
2
# 需要在项目目录中输入命令，根目录或者根目录下的子目录都可以
npx stylelint "**/*.css"

如果想要再检查的同时，根据配置规则对代码进行修复，加上--fix参数即可（并不是所有规则都能修改，不能自动修改的部分，会输出到命令行）

1
npx stylelint .\common.css --fix

第四步，安装VSCode插件Stylelint，这样在编辑过程中即可实时看到检查结果，方便及时修改。

image-20230618105932912 image-20230618110101562

然后再结合上VSCode的【保存时自动修复】

setting.json

image-20231006154259986

这样每次保存文件时，就会自动完成stylelint的修复（而不需要手动输入命令了！）

2. 使用须知

  • Stylelint所有的规则默认都是关闭的，所以如果不设置extends、plugins、rules等任一属性时，Stylelint是没有任何作用的！
  • 自动修复并不是对所有rules都管用的！，具体规则是否支持自动修复，可以查询规则 | Stylelint 中文网。
image-20231006222055476
  • Stylelint默认的检查范围是当前项目下所有css文件，除了node_modules/。

二、自定义配置

1. 配置文件类型

stylelint 支持多种形式的配置文件，按照优先级由高到低排列依次如下：

  • .stylelintrc文件（最常用），加或者不加后缀均可。可添加的后缀包括：.yaml（或.yml）、.json
  • stylelint.config.js文件
  • 在package.json文件中添加stylelint属性并添加规则

下面给出示例：

.stylelintrc文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
// .stylelintrc（不带后缀，使用的是json语法）
{
    "extends": [
        "stylelint-config-standard",
        "stylelint-config-recommended-vue"
    ],
    "plugins": [
        "stylelint-less",
        "stylelint-order"
    ],
    "ignoreFiles": [
        "** /*.js",
        "**/*.jsx",
        "** /*.tsx",
        "**/*.ts"
    ],
    "overrides": [
        {
            "files": [
                "**/*.vue"
            ],
            "customSyntax": "postcss-html"
        },
        {
            "files": [
                "**/*.less"
            ],
            "customSyntax": "postcss-less"
        }
    ],
    "rules": {
        "indentation": 2,
        "custom-property-pattern": null,
    }
}

stylelint.config.js文件

1
2
3
4
5
6
7
8
9
10
11
// .stylelintrc.js
module.exports = {
  plugins: ['stylelint-order'],

  extends: ['stylelint-config-standard'],

  rules: {
    // 颜色值要小写 
    'color-hex-case': 'lower','number-leading-zero': 'always',
  },
};

package.json中的stylelint属性（暂时没找到案例，待补充！！）

1
2
// package.json
待补充！！

2. 配置属性

1
2
3
4
5
6
7
8
9
10
11
12
{
  "extends": [],     //数组形式，扩展的配置文件
  "plugins": [],     //数组形式，插件，是支持方法、工具集、非CSS功能的自定义规则集
  "rules": {},       //对象形式，用来配置具体的规则
	"overrides": [],   //数组形式，为指定范围的文件子集应用指定的配置
  "ignoreFiles": [], //数组形式，glob或glob数组，用来忽略指定范围的文件
  "allowEmptyInput": true,    //布尔类型，当glob模式不匹配任何文件（并且该值为true）时，Stylelint不抛出错误
  ”defaultSeverity“: "error", //所有规则默认的严重性级别。error、warning
  ”configurationComment“: "stylelint-disable",   // 指定配置注释以什么开头，eg：/* stylelint-disable */
  ”ignoreDisables“: false,    //忽略配置注释，例如/* stylelint-disable block-no-empty */这种
  ...                //还有其它一些不常用的，不在此介绍，有兴趣可自行查看官方文档
}

下面为每项配置列举一些例子

2.1 extends

extends属性接受一个字符串，或者一个字符串数组。这些字符串为：

  • 第三方配置名（需要安装对应的npm包）
  • 自定义配置文件的绝对路径/相对当前配置文件的路径
1
2
3
{
  "extends": "stylelint-config-standard",	// 扩展stylelint的一个官方配置
}
1
2
3
{
  "extends": ["stylelint-config-standard", "./myExtendableConfig"],	// 扩展多个配置文件
}

当同时扩展多个配置文件时，如果多个文件中有重复的规则属性，此时的覆盖关系为：后面文件中规则的覆盖前面文件中的规则。

同时，你还可以再当前的stylelint配置文件中，通过rules属性中规则，覆盖扩展配置文件中的对应规则。

2.2 plugins

plugins的作用也是扩展规则配置。

extends中指定的是标准的stylelint配置文件；plugins中指定的是插件，这些插件可以支持方法、非标准CSS功能来实现一些更复杂的功能。

plugins属性接受一个数组，数组元素可以是：

  • npm模块名
  • 插件的绝对路径/相对当前配置文件的路径
1
2
3
{
  "plugins": [”stylelint-order“, "../custom-rule.js"]
}

2.3 rules

rules属性接受一个对象，用于指定具体的规则

rules的值可以是以下形式之一：

  • 一个值：选项
  • 包含两个值的数组：主选项、辅助选项（通常用来配置补充属性）
  • null：关闭规则
1
2
3
4
5
6
7
8
9
10
11
{
  "rules": {
    "indentation": 2,                    //指定缩进为2个空格
    "selector-class-pattern": null,      //指定选择器的模式，此处为null，表示关闭这条规则
    "color-function-notation": "legacy", //为颜色函数指定为传统的表示法，eg：rgba(0,0,0,0.5)逗号分割是传统，空格分割是现代
    "order/order": [                     //官方文档中没有这个key
        "custom-properties",
        "declarations"
    ],
  }
}

【扩展链接】

2.4 overrides

使用 overrides 属性，你可以指定要应用配置的文件子集。

接受一个数组，数组对象：

  • 必须包含files属性，是一个glob模式数组，用于指定文件范围
  • 至少包含一个其它配置属性
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "overrides": [
    // 所有的.scss文件使用postcss-scss语法
    {
      "files": ["*.scss", "**/*.scss"],
      "customSyntax": "postcss-scss"
    },
    
    // components和pages目录下所有的.css文件的alpha值使用百分比表示法
    {
      "files": ["components/**/*.css", "pages/**/*.css"],
      "rules": {
        "alpha-value-notation": "percentage"
      }
    }
  ]
}

2.5 customSyntax

指定要在代码上使用的自定义语法，通常在需要检查多种不同的语言（如html、sass、less等）时，在overrides属性中使用。customSyntax | Stylelint

1
2
3
4
5
6
7
8
9
10
11
12
13
14
"overrides": [
      {
          "files": [
              "**/*.vue"
          ],
          "customSyntax": "postcss-html"
      },
      {
          "files": [
              "**/*.less"
          ],
          "customSyntax": "postcss-less"
      }
  ],

2.6 ignoreFiles

你可以提供一个 glob 或 glob 数组来忽略特定文件。

1
2
3
{
  "ignoreFiles": ["**/*.js"]	//忽略所有JavaScript文件
}

注意：如果需要忽略较多文件，请使用 .stylelintignore 文件！

2.7 allowEmptyInput

当 glob 模式不匹配任何文件时，Stylelint 不会抛出错误。

1
2
3
{
  "allowEmptyInput": true
}

三、extends & plugins

1. 常用第三方配置

2. 常用插件

  • stylelint-order，css order插件，需要搭配rules属性中的order/order、order/properties-order使用
  • stylelint-less，Less特定的stylelint规则集合

四、常用rules

参考链接：规则 | Stylelint 中文网 (nodejs.cn)

rules的值可以是以下形式之一：

  • 一个值：选项
  • 包含两个值的数组：主选项、辅助选项（通常用来配置补充属性）
  • null：关闭规则
rule 说明 取值范围
no-descending-specificity 禁止「更高针对性的选择器」出现在「更低针对性的选择器」后面 true
length-zero-no-unit 不允许使用零长度单位 true
property-disallowed-list 指定不允许的属性列表 字符串、字符串数组、正则表达式
用于指定不允许出现的css属性
unit-disallowed-list 指定不允许的单位列表
comment-empty-line-before 要求或禁止注释前有空行 “always”——注释之前必须有空行
“never”——注释之前不能有空行
rule-empty-line-before 要求或禁止规则块前有空行 “always”——规则块之前必须有一个空行
“never”——不能有空行
selector-class-pattern 指定类选择器的模式 regex / 字符串（或被转换成regex）
不需要带前缀.

五、常用实践

1. 忽略stylelint检查

1.1 使用配置注释忽略

第一种，如果只声明 disable，不声明enable，那么将从声明disable处，忽略到文件末尾

1
2
3
4
5
6
/* stylelint-disable */
.flex_row{
  display: flex;
  justify-content: space-between;
  padding: 8px 0 ;
}

第二种，先后声明 disable和enable，忽略的范围在两者之间

第三种，使用disable + 具体规则的模式忽略指定的rule，例如：/* stylelint-disable selector-class-pattern */

1.2 使用.stylelintignore

匹配模式与.gitignore的语法一致

1
2
client/ui/side/app.css
vendor/**/*.css

1.3 使用 ignoreFiles属性

1
2
3
4
5
6
7
8
{
	"ignoreFiles": [
        "**/*.js",
        "**/*.jsx",
        "**/*.tsx",
        "**/*.ts"
    ],
}

1.4 关闭规则

直接在 stylelint 配置文件的 rules属性中使用 null 关闭指定的规则，对所有文件生效！

1
2
3
4
5
{
  "rules": {
    "custom-property-pattern": null,
  }
}

2. css声明顺序

注意，这里的「顺序」指的是css块内部的「属性顺序」，不包含「css选择器的顺序」（这个顺序可以通过ESLint来进行约束）

2.1 stylelint-config-recess-order

第一种方式，使用stylelint-config-recess-order，这个属于第三方配置，是Bootstrap使用的css order规则。

它有两层顺序，外层的顺序是关联规则块的顺序，eg：position->display->flexible mode等等；内层的顺序是规则块内部的顺序，以position block为例：position->top->right->bottom等等。

第一步，安装stylelint和stylelint-config-recess-order

1
npm install -D stylelint stylelint-config-recess-order

第二步，在.stylelintrc声明扩展配置文件

1
2
3
{
    "extends": ["stylelint-config-recess-order"]
}

第三步，配置VSCode的保存时自动修复

setting.json

image-20231006154259986

完成配置！如图，当顺序不符和规范时，会有报错提示。点击保存后，可以自动完成修复！

image-20231006234658345

2.2 stylelint-order

第二种方式，使用stylelint-order，它是plugins插件，需要搭配 rules 属性才能发挥作用

第一步，安装stylelint和stylelint-config-order

1
npm install -D stylelint stylelint-order

第二步，在.stylelintrc声明plugins和rules

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
	"plugins": [
		"stylelint-order"
	],
	"rules": {
		"order/order": [
			"custom-properties",	// 自定义属性在前，eg: --bar: 100px; 这叫自定义是属性
			"declarations"        // 标准声明在后，eg：display: flex; 这类叫标准声明
		],
    
    // 下面是配置声明规则的顺序，width在height前面
		"order/properties-order": [
			"width",
			"height"
		]
	}
}

第三步，配置VSCode的保存时自动修复

setting.json

image-20231006154259986

完成配置！如图，当顺序不符和规范时，会有报错提示。点击保存后，可以自动完成修复！

image-20231007001115020

3. css块之间空行隔开

相应属性：rule-empty-line-before | Stylelint 中文网 (nodejs.cn)

1
2
3
4
5
{
  "rules": {
    "rule-empty-line-before": "always"	// always——规则块之间必须（至少）有一个空行，never——规则块之间不能有空行
  }
}

通过以上配置，可以让css规则块之间有空行隔开，但无法控制只有一个空行，有多个空行也不会报错。同时，会将注释也用空行隔开（有时这并不是我们所期望的）

image-20231006220102985 
1
2
3
4
5
6
7
8
"rules": {
    "rule-empty-line-before": [
      "always",
      {
        "except": ["after-single-line-comment"]
      }
    ]
  }

通过设置辅助属性，可以改变这一状况

image-20231006220330399

3. 解决和Prettier的冲突

项目中如果同时存在 Stylelint 和 Prettier ，可能会存在rule冲突。为了解决这个问题，需要在Stylelint中安装一个扩展

1
npm install -D stylelint-config-prettier

并在stylelint配置文件中声明

1
2
3
{
  "extends": ["stylelint-config-prettier"]
}

如果，到这一步进行顺利，下面的内容可以跳过。如果在安装过程中出现报错，可以继续往下看

但是，在安装过程中，报错了，错误原因部分截图如下：

image-20230618160104823

大意是：Stylelint的版本超前了，styelint-config-prettier的版本更新没有跟上，导致版本冲突了，这里的解决思路是：降低Stylelint的版本。首先查看一下可用版本

1
npm view stylelint versions --json

不需要卸载，直接重装覆盖

1
npm install -D stylelint@14.16.1

但是，这又引发了新的问题，原本和stylelint@15.0.8搭配的stylelint-config-recess-order@4.2.0发生版本冲突了，所以需要把它也重装一遍

1
npm install -D stylelint-config-recess-order

运行以上命令后，你会发现，还是报错，原因也是版本冲突：stylelint-config-recess-order和stylelint版本冲突了，这里的原因是因为（敲重点了！）：npm install 默认只会安装package最新的版本，所以如果需要安装之前的版本，需要我们手动指定。

下一个问题来了：我也不知道哪个版本的stylelint-config-recess-order能够兼容stylelint@14.6.1呀？解决办法：到 stylelint-config-recess-order - npm (npmjs.com) 里面查看历史版本中下载次数最多，并且大概猜测能够和stylelint@14.6.1发行时间相近的那个版本，然后安装一下尝试一下，大概率是OK的！（如果不OK，换一个版本再试安装一次）

1
2
npm install -D stylelint-config-recess-order@3   
npm install -D stylelint-config-standard@29

最后，回到正题！

1
npm install -D stylelint-config-prettier

安装成功！

image-20230618163642348

参考资料

配置 | Stylelint 中文网 (nodejs.cn)

前端规范之CSS规范（Stylelint） - Yellow_ice - 博客园 (cnblogs.com)

Stylelint - 用户指南 - 插件 | Plugins - 开发者手册 - 腾讯云开发者社区-腾讯云 (tencent.com)

效率 > 规范化
玩转StyleLint
http://timegogo.top/2023/06/17/效率/规范化：玩转StyleLint/
作者
丘智聪
发布于
2023年6月17日
更新于
2023年10月23日
许可协议