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)