Stylelint

2,041 阅读4分钟

前言

年前为公司升级了新的monorepo项目架构,近来不用加班,在家得闲。便想再搭个monorepo项目,随便记录一下。
用到以下pnpm + vite3 + vue3 + ESLint + Stylelint + TypeScriptmonorepe实战记录,此篇为其中一个的简单介绍。

Css规范以往都不太受重视,团队不同人编写的Css代码格式也是千差万别。因而容易出现问题,比如影响其他样式,乱用!important,样式名太长等。
Stylelint作为Css代码检查工具,可规避一些Css错误,并保持统一的编码风格。
感觉相对来说大家都更熟悉ESLint吧,StylelintESLint在功能和使用上较为相似的。

安装

安装stylelintstylelint-config-standard

pnpm add stylelint stylelint-config-standard -D

stylelint: 工具包,用于执行检测命令。
stylelint-config-standard: 标准规范配置。

配置文件

可以通过以下方式配置stylelint规则。

  • package.json中添加stylelint属性,例如。

    {
      "stylelint"{
        "extends": "stylelint-config-standard"
      }
    }
    
  • .stylelintrc.*文件,支持(.json,.yaml/.yml, .js)

  • style.config.js文件,当packge.json中指定"type": "module",后缀需为.cjs。导出一个js对象,例如。

    module.exports  = {
      extends: 'stylelint-config-standard'
    }
    

执行npx stylelint [文件]命令对进行校验,添加--fix参数可自动修复问题,例如

npx stylelint "**/*.css" --fix

一般推荐添加到scripts

{
  "scripts": {
    "lint:css": "npx stylelint \"**/*.css\" --fix"
  }
}

更多参数命令行参数请前往Stylelint 命令行参数

忽略文件

新建.stylelintignore文件,可以将一些第三方包文件,打包文件等不需要校验的文件加入其中。比如

# .stylelintignore stylelint忽略文件
/node_modules/*
/dist/*
/public/*

常用配置

extends

可以通过extends直接继承一个现有的配置(可以是npm配置包的包名或本地其他配置文件的路径),那么这个的配置规则可以直接作用于当前配置。 比如官方的标准规范配置。

module.exports  = {
  extends: 'stylelint-config-standard'
}

rules

rules配置是个对象,键为规则名,值为规则配置。 规则配置有以下格式:

  • null:表示关闭规则
    module.exports  = {
       rules: {
         'selector-class-pattern': null
       }
    }
    
  • 一个值: (主选项)
    module.exports  = {
       rules: {
         'max-empty-lines': 2,
         'unit-allowed-list': ['em', 'rem', '%', 's']
       }
    }
    
  • 只有两个值的数组([主选项,辅助选项])
    module.exports  = {
      rules: {
        'indentatio': ['tab', { except: ['value'] }],
      }
    }
    

Stylelint内置了170多个规则,默认这些规则都是关闭状态。必须将规则显示配置才生效。
也就是说需要将规则配置在rules中才生效,当然通过extends继承的规则也能生效。当前配置文件的规则优先级大于继承的规则,当存在相同的规则名,当前配置的规则会覆盖继承的规则。

plugins

插件是社区构建的支持方法、工具集、非标准 CSS 功能或非常具体的用例的规则或规则集。
使用插件可以扩展一些能力,要使用插件需将插件配置到plugins中(配置方式和extends一样),并在rules中为插件提供选项。比如通过stylelint-order可以在格式化时对样式属性进行排序。

// 需要先安装
pnpm add stylelint-order -D

// 配置文件 演示用的stylelint.config.cjs
module.exports = {
  extends: ['stylelint-config-standard'],
  plugins: ['stylelint-order'], // 使用插件
  rules: {
     // 为插件提供选项
    'order/properties-order': [
      'display',
      'position',
      'float',
      // ...篇幅有限,其他顺序先省略
    ],
  }
}

先试下插件效果,检测生效。 image.png 加上--fix,自动给调整了属性位置。 image.png

overrides

通过overrides属性,可以为某些样式使用特殊配置。例如

module.exports = {
  overrides: [
    {
      // 为scss文件指定语法解析器
      files: ['*.scss','**/*.scss'],
      customSyntax: 'postcss-scss'
    },
    {  
      // 为h5文件下的css设置嵌套最深3层
      files: [ 'h5/**/*.css'],  
      rules: {  
        'max-nesting-depth': 3  
      }
    }
  ]
}

以上便是比较常用的配置选项,更多配置选项请前往Stylelint中文官网,或Stylelint中文文档

VS Code添加Stylelint插件

通过Stylelint命令行工具可以检查样式风格,可以通过VS Code的Stylelint插件,在编写时给出提示,还可配置保存时自动格式化。

  • 编码提示
    安装Stylelint插件
    image.png
    vscode的Stylelint插件会根据配置文件校验样式,并给予提示。 image.png

  • 保存自动格式化
    修改settings.json文件,当我们保存文件时,stylelint就会自动修复一些规则。

    // settings.json
    {
        // ...
        "editor.codeActionsOnSave": {
            "source.fixAll.eslint": true, 
            "source.fixAll.stylelint": true, // 新增修改
        },
        "stylelint.validate": [ "css", "sass", "scss", "vue"] // 新增修改
    }
    

vite3 + vue3 + scss项目支持Stylelint

1, 安装并配置vite插件 vite-plugin-stylelint

pnpm add vite-plugin-stylelint -D
// vite.config.js
// ...
import stylelint from 'vite-plugin-stylelint'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    // ...
    stylelint({ fix: true })
  ],
})

2,安装配置vue的相关stylelint依赖

pnpm add postcss-html stylelint-config-standard-vue stylelint-config-standard-scss -D
  • postcss-html: vue文件样式解析器。
    不同的css扩展语言需使用不同的解析器,如下。
  • stylelint-scss: scss插件
  • stylelint-config-standard-vue[/scss]: vue标准配置,通过overrides选项调整了.vue文件样式规则,继承了stylelint-config-standard[-scss]stylelint-config-recommended-vue[/scss]规则。
  • stylelint-config-standard-scss: scss标准配置

修改stylelint.config.cjs配置

module.exports = {
  extends: [
    'stylelint-config-standard',
    'stylelint-config-standard-scss',
    'stylelint-config-standard-vue/scss'
  ],
  plugins: [
    'stylelint-order',  
    'stylelint-scss'
  ],
  // ...
}
// 对应版本
"postcss-html": "^1.5.0",
"stylelint": "^15.4.0",
"stylelint-config-standard": "^32.0.0",
"stylelint-config-standard-scss": "^7.0.1",
"stylelint-config-standard-vue": "^1.0.0",
"stylelint-order": "^6.0.3",
"stylelint-scss": "^4.6.0",

规则列表

stylelint中文规则列表

结合Prettier

安装pnpm add prettier stylelint-prettier stylelint-config-prettier -D

  • prettier:prettier工具
  • styleline-prettier: 基于 prettier 代码风格的 stylelint 规则
  • stylelint-config-prettier:禁用与prettier冲突的stylelint规则
module.exports = { 
  extends: [ 
    // ... 其他配置在前
    'stylelint-prettier/recommended',
    'stylelint-config-prettier',
  ], 
  plugins: [
   // ...
   'stylelint-prettier'
  ],
  // ... 
}