設定

Stylelint 預期會有一個設定物件，並在

stylelint.config.js 或 .stylelintrc.js 檔案中尋找
- 要使用哪個模組系統取決於您在 Node.js 中的預設模組系統設定（例如，package.json 中的 "type": "module"）。
使用 export default（ES 模組）的 stylelint.config.mjs 或 .stylelintrc.mjs 檔案
使用 module.exports（CommonJS）的 stylelint.config.cjs 或 .stylelintrc.cjs 檔案
.stylelintrc.json、.stylelintrc.yml 或 .stylelintrc.yaml 檔案
JSON 或 YAML 格式的 .stylelintrc 檔案
- 建議新增副檔名（例如 .json），以協助編輯器提供語法檢查和重點標示。
package.json 中的 stylelint 屬性

ES 模組範例

/** @type {import('stylelint').Config} */
export default {
  rules: {
    "block-no-empty": true
  }
};

注意

@type JSDoc 註解可讓 Typescript 自動完成並進行類型檢查。

CommonJS 範例

module.exports = {
  rules: {
    "block-no-empty": true
  }
};

JSON 範例

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

從目前的工作目錄開始，Stylelint 會在找到下列其中一項時停止搜尋。或者，您可以使用 --config 或 configFile 選項來短路搜尋。

組態物件具有下列屬性

`rules`

規則會決定 linter 尋找和抱怨的內容。Stylelint 內建超過 100 個規則。預設未啟用任何規則。

rules 屬性是其金鑰為規則名稱，而值為規則組態的物件。例如

{
  "rules": {
    "color-no-invalid-hex": true
  }
}

每個規則組態都符合下列格式之一

null（關閉規則）
單一值（主要選項）
包含兩個值的陣列（[主要選項，次要選項]）

指定主要選項會啟用規則。

許多規則提供次要選項以進行進一步自訂。若要設定次要選項，請使用兩個成員的陣列。例如

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

您可以新增任意數量的金鑰到物件。例如，您可以

關閉 block-no-empty
使用主要選項啟用 unit-allowed-list
使用主要和次要選項啟用 alpha-value-notation

{
  "rules": {
    "block-no-empty": null,
    "unit-allowed-list": ["em", "rem", "%", "s"],
    "alpha-value-notation": ["percentage", { "exceptProperties": ["opacity"] }]
  }
}

某些規則和選項接受正規表示法。您可以強制執行下列常見案例

kebab-case：^([a-z][a-z0-9]*)(-[a-z0-9]+)*$
lowerCamelCase：^[a-z][a-zA-Z0-9]+$
snake_case：^([a-z][a-z0-9]*)(_[a-z0-9]+)*$
UpperCamelCase：^[A-Z][a-zA-Z0-9]+$

或使用正向後視 regex 強制使用前綴。例如，(?<=foo-) 以 foo- 作為前綴。

`disableFix`

您可以設定 disableFix 次要選項，以停用自動修正針對每個規則。

例如

{
  "rules": {
    "color-function-notation": ["modern", { "disableFix": true }]
  }
}

`message`

您可以使用 message 次要選項，在規則遭到違反時傳送自訂訊息。

例如，下列規則組態會替換為自訂訊息

{
  "rules": {
    "custom-property-pattern": [
      "^([a-z][a-z0-9]*)(-[a-z0-9]+)*$",
      {
        "message": "Expected custom property name to be kebab-case"
      }
    ]
  }
}

或者，如果您需要嚴格自訂，您可以撰寫自訂格式器以獲得最大控制權。

實驗性功能：有些規則支援訊息引數。例如，在組態 color-no-hex 規則時，十六進位顏色可以用於訊息字串

.stylelintrc.js:

{
  'color-no-hex': [true, {
    message: (hex) => `Don't use hex colors like "${hex}"`,
  }]
}

.stylelintrc.json:

{
  "color-no-hex": [true, {
    "message": "Don't use hex colors like \"%s\""
  }]
}

對於不支援函式（例如 JSON）的格式，您可以使用類似 printf 的格式（例如 %s）。另一方面，使用 JS 格式時，您可以同時使用類似 printf 的格式和函式。

`reportDisables`

您可以設定 reportDisables 次要選項，以回報此規則的任何 stylelint-disable 註解，有效禁止作者選擇退出。

例如

{
  "rules": {
    "color-no-invalid-hex": [true, { "reportDisables": true }]
  }
}

回報會被視為程式碼檢查錯誤。

`severity`

您可以使用 severity 次要選項調整任何特定規則的嚴重性。

severity 可用的值為

"warning"
"error" (預設)

例如

{
  "rules": {
    "number-max-precision": [
      2,
      {
        "ignoreUnits": ["em"],
        "severity": "warning"
      }
    ]
  }
}

回報器可以使用這些嚴重性等級來顯示問題或以不同的方式結束程序。

實驗性功能：有些規則支援訊息引數。對於這些規則，可以對 severity 使用函式，它會接受這些引數，讓您可以根據這些引數調整嚴重性。

此函式必須傳回 "error"、"warning" 或 null。當它傳回 null 時，會使用 defaultSeverity。

例如，給定

{
	rules: {
		'selector-disallowed-list': [
			['a > .foo', '/\\[data-.+]/'],
			{
				severity: (selector) => {
					return selector.includes('a > .foo') ? 'error' : 'warning';
				},
			},
		],
	},
}

下列模式會回報為錯誤

a > .foo {}

但以下範例會回報警告

a[data-auto="1"] {}

`extends`

您可以延伸現有的設定檔（無論是您自己的或第三方的）。設定檔可以捆綁外掛程式、自訂語法、選項和設定規則。它們也可以延伸其他設定檔。

例如，stylelint-config-standard 是我們官方設定檔之一，您可以延伸它。

當一個設定檔延伸另一個設定檔時，它會從另一個設定檔的屬性開始，然後新增和覆寫現有的設定。

例如，要延伸 stylelint-config-standard，然後將 alpha 值變更為數字並關閉 selector-class-pattern 規則

{
  "extends": "stylelint-config-standard",
  "rules": {
    "alpha-value-notation": "number",
    "selector-class-pattern": null
  }
}

您可以延伸現有設定檔的陣列，陣列中的每個項目優先於前一個項目（因此第二個項目會覆寫第一個項目的規則，第三個項目會覆寫第一個和第二個項目的規則，依此類推，最後一個項目會覆寫所有其他項目）。

例如，使用 stylelint-config-standard，然後在上面加上 myExtendableConfig，然後覆寫 alpha-value-notation 規則

{
  "extends": ["stylelint-config-standard", "./myExtendableConfig"],
  "rules": {
    "alpha-value-notation": "number"
  }
}

"extends" 的值是「定位器」（或「定位器」陣列），最終會 require()。它可以符合任何與 Node 的 require.resolve() 演算法相符的格式。這表示「定位器」可以是

node_modules 中模組的名稱（例如 stylelint-config-standard；該模組的 main 檔案必須是有效的 JSON 設定檔）
具有 .js 或 .json 副檔名的檔案的絕對路徑（如果您在 Node.js 環境中建立 JS 物件並傳遞它，這樣做是有意義的）。
具有 .js 或 .json 副檔名的檔案的相對路徑，相對於參考設定檔（例如，如果 configA 有 extends: "../configB"，我們會在 configA 中尋找 configB）。

您可以在 Awesome Stylelint 中找到更多設定檔。

`plugins`

外掛程式是客製化規則或客製化規則組，用來支援方法論、工具組、非標準 CSS 功能或非常特定的使用案例。

例如，stylelint-order 是熱門外掛程式套件，用來排序宣告區塊內的屬性等內容。

外掛程式通常包含在共用設定檔中，您可以延伸這些設定檔。例如，stylelint-config-standard-scss 設定檔包含 stylelint-scss 外掛程式。

如需直接使用外掛程式，請在設定檔中新增 "plugins" 陣列，其中包含外掛程式物件或識別您要使用的外掛程式的「定位器」。與上述 extends 相同，「定位器」可以是

npm 模組名稱
絕對路徑
相對於呼叫設定檔的路徑

宣告外掛程式後，您需要在 "rules" 物件中新增該外掛程式規則的選項，就像任何標準規則一樣。查看外掛程式的文件，以了解規則名稱為何。

{
  "plugins": ["../special-rule.js"],
  "rules": {
    "plugin-namespace/special-rule": "everything"
  }
}

「外掛程式」可以提供單一規則或規則組。如果您使用的外掛程式提供規則組，請在 "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"
  }
}

您可以在 Awesome Stylelint 中找到更多外掛程式。

`customSyntax`

指定要使用於程式碼的客製化語法。更多資訊。

`overrides`

使用 overrides 屬性，您可以指定要套用設定檔的檔案子集。

例如，如需使用

postcss-scss 語法，套用於所有 .scss 檔案
percentage 表示法，套用於 components 和 pages 目錄中所有 .css 檔案中的所有 alpha 值

{
  "rules": {
    "alpha-value-notation": "number"
  },
  "overrides": [
    {
      "files": ["*.scss", "**/*.scss"],
      "customSyntax": "postcss-scss"
    },
    {
      "files": ["components/**/*.css", "pages/**/*.css"],
      "rules": {
        "alpha-value-notation": "percentage"
      }
    }
  ]
}

overrides 屬性的值是物件陣列。每個物件

必須包含 files 屬性，此屬性是 glob 模式陣列，用來指定要套用設定檔的檔案
應包含至少一個其他常規設定檔屬性，例如 customSyntax、rules、extends 等。

customSyntax 屬性將會被取代，而 plugins、extends、rules 等將會被附加。

模式會針對相對於設定檔目錄的檔案路徑套用。例如，如果您的設定檔路徑為 /project-foo/.stylelintrc.js，而您要檢查的檔案路徑為 /project-foo/components/bar.css，則 .stylelintrc.js 中提供的模式將會針對相對路徑 components/bar.css 執行。

覆寫優先於一般設定。同一個設定檔中的多個覆寫會依序套用。也就是說，設定檔中最後一個覆寫區塊永遠擁有最高的優先權。

`defaultSeverity`

你可以設定沒有在次要選項中指定嚴重性等級的所有規則的預設嚴重性等級。例如，你可以將預設嚴重性設定為 "warning"

{
  "defaultSeverity": "warning"
}

`report*`

這些 report* 屬性提供 stylelint-disable 註解額外的驗證。這有助於強制執行有用且有良好文件說明的停用。

可用的報告有

reportDescriptionlessDisables
reportInvalidScopeDisables
reportNeedlessDisables

它們的設定方式就像規則一樣。它們可以有三個值之一

null（關閉設定）
true 或 false（主要選項）
包含兩個值的陣列（[主要選項，次要選項]）

以下次要選項可用

"except" 接受一個規則名稱陣列，主要選項應針對這些規則名稱反轉。
"severity" 調整規則發出的錯誤等級，如上所述。

例如，這會針對除了 selector-max-type 之外的所有規則產生不必要的停用錯誤

{
  "reportNeedlessDisables": [true, { "except": ["selector-max-type"] }]
}

而這會針對沒有說明的 unit-allowed-list 停用發出警告

{
  "reportDescriptionlessDisables": [
    false,
    {
      "except": ["unit-allowed-list"],
      "severity": "warning"
    }
  ]
}

`reportDescriptionlessDisables`

報告沒有說明的 stylelint-disable 註解。一個 report* 屬性。

例如

{
  "reportDescriptionlessDisables": true
}

更多資訊.

`reportInvalidScopeDisables`

報告不符合設定物件中指定規則的 stylelint-disable 註解。一個 report* 屬性。

例如

{
  "reportInvalidScopeDisables": true
}

更多資訊.

`reportNeedlessDisables`

報告不符合任何需要停用的檢查的 stylelint-disable 註解。一個 report* 屬性。

例如

{
  "reportNeedlessDisables": true
}

更多資訊.

`configurationComment`

你可以設定 /* stylelint-disable */ 等設定註解的開頭。如果你使用多個具有不同設定的 Stylelint 執行個體，這會很有用。

例如，讓 Stylelint 執行個體停用規則，使用 /* stylelint-foo-instance-disable */ 而不是預設的 /* stylelint-disable */

{
  "configurationComment": "stylelint-foo-instance"
}

`ignoreDisables`

忽略 stylelint-disable (例如 /* stylelint-disable block-no-empty */) 註解。

例如

{
  "ignoreDisables": true
}

更多資訊.

`ignoreFiles`

您可以提供一個 glob 或 glob 陣列來忽略特定檔案。

例如，您可以忽略所有 JavaScript 檔案

{
  "ignoreFiles": ["**/*.js"]
}

Stylelint 預設忽略 node_modules 目錄。不過，如果設定 ignoreFiles，就會覆寫此設定。

如果 glob 是絕對路徑，就會照樣使用。如果是相對路徑，就會相對於下列路徑分析

configBasedir，如果已提供；
設定檔的檔案路徑，如果設定檔是 Stylelint 找到並載入的檔案；
或 process.cwd()。

注意

這不是忽略大量檔案的有效方法。如果您想要有效率地忽略大量檔案，請使用 .stylelintignore 或調整您的檔案 glob。

`allowEmptyInput`

當 glob 模式沒有符合任何檔案時，Stylelint 也不會傳回錯誤。

例如

{
  "allowEmptyInput": true
}

注意

此設定選項不應針對每個檔案個別覆寫。

更多資訊.

`cache`

儲存處理過檔案的結果，讓 Stylelint 只處理有變更的檔案。

例如

{
  "cache": true
}

注意

此設定選項不應針對每個檔案個別覆寫。

更多資訊.

`fix`

自動修復規則報告的問題（如果可能）。

例如

{
  "fix": true
}

注意

此設定選項不應針對每個檔案個別覆寫。

更多資訊.

設定

rules​

disableFix​

message​

reportDisables​

severity​

extends​

plugins​

customSyntax​

overrides​

defaultSeverity​

report*​

reportDescriptionlessDisables​

reportInvalidScopeDisables​

reportNeedlessDisables​

configurationComment​

ignoreDisables​

ignoreFiles​

allowEmptyInput​

cache​

fix​

`rules`

`disableFix`

`message`

`reportDisables`

`severity`

`extends`

`plugins`

`customSyntax`

`overrides`

`defaultSeverity`

`report*`

`reportDescriptionlessDisables`

`reportInvalidScopeDisables`

`reportNeedlessDisables`

`configurationComment`

`ignoreDisables`

`ignoreFiles`

`allowEmptyInput`

`cache`

`fix`