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: 0 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']
    }]
  }
}

 

 

 

參考：