跳至主要內容

撰寫規則

請協助我們建立、增強和除錯我們的規則！

新增規則​

您應該準備好貢獻程式碼。

定義規則​

規則必須

  • 僅適用於標準 CSS 語法
  • 普遍適用；不受特殊模式約束

並且具有

  • 明確的完成狀態
  • 單一目的，不與其他規則重疊

其名稱分為兩部分

  • 規則適用的項目，例如 at-rule
  • 規則檢查的內容，例如 disallowed-list

除非適用於整個來源，否則沒有第一部分。

撰寫測試​

您應該為所有模式新增測試案例，這些模式

  • 被視為問題
  • 不被視為問題

你應該使用

  • 實際的 CSS，避免使用省略號
  • 盡可能最少的程式碼，例如在目標選擇器時使用空規則
  • 空規則使用 {}，而不是 { }
  • 預設 a 類型選擇器
  • 預設 @media at 規則
  • 預設 color 屬性
  • 預設 red 值
  • 預設 (min-)width 媒體功能
  • 名稱使用 foo、bar 和 baz，例如 .foo、#bar、--baz

你應該

  • 在測試中變更欄和行位置
  • 包含至少一個有 2 個警告的測試
  • 在 isStandardSyntax* 程式中測試非標準語法，而不是在規則本身中測試

常被忽略的邊界情況​

你應該問自己規則如何處理

  • 變數（例如 var(--custom-property)）？
  • CSS 字串（例如 content: "anything goes";）？
  • CSS 註解（例如 /* anything goes */）？
  • 空函式（例如 var()）？
  • url() 函式，包括資料 URI（例如 url(anything/goes.jpg)）？
  • 供應商前綴（例如 @-webkit-keyframes name {}）？
  • 大小寫敏感（例如 @KEYFRAMES name {}）？
  • 偽類別結合偽元素（例如 a:hover::before）？
  • 巢狀（例如你會解析 & a {}，還是照原樣檢查它？）？
  • 空白和標點符號（例如比較 rgb(0,0,0) 和 rgb(0, 0, 0)）？

撰寫規則​

撰寫規則時，你應該

  • 預設讓規則嚴格
  • 加入次要的 ignore 選項，讓規則更寬鬆
  • 不包含特定於語言擴充功能（例如 SCSS）的程式碼

你應該使用

  • PostCSS API
  • 特定於建構的解析器
  • 程式功能

PostCSS API​

使用 PostCSS API 瀏覽和分析 CSS 語法樹。我們建議使用 walk 迭代器（例如 walkDecls），而不是使用 forEach 來迴圈節點。

在節點上使用陣列方法時，例如 find、some、filter 等，您應該在嘗試存取其他屬性之前明確檢查節點的 type 屬性。例如

const hasProperty = nodes.find(
  ({ type, prop }) => type === "decl" && prop === propertyName
);

從 PostCSS AST 存取原始字串時，使用 node.raws 而不是 node.raw()。

架構特定解析器​

根據規則，我們也建議使用

與其使用正規表示法或 indexOf 搜尋（即使它們並不總是效能最佳的方法），使用這些解析器有顯著的好處。

實用程式函式​

Stylelint 有 實用程式函式，這些函式用於現有規則，對您來說可能也很有用。請瀏覽這些函式，以便了解有哪些可用的函式。（如果您有新的函式，您認為可能對大家有幫助，讓我們將其新增到清單中！）。

使用

  • validateOptions() 實用程式警告使用者有關無效選項
  • isStandardSyntax* 實用程式忽略非標準語法

新增選項​

每個規則都可以接受主要選項和一個可選的次要選項。

只有在選項解決 要求的 使用案例時，才將選項新增到規則，以避免使用未使用的功能污染工具。

主要​

每個規則 必須 有主要選項。例如，在

  • "font-weight-notation": "numeric" 中，主要選項是 "numeric"
  • "selector-max-type": [2, { "ignoreTypes": ["custom"] }] 中，主要選項是 2

規則的命名方式鼓勵明確的主要選項。例如，font-weight-notation: "numeric"|"named-where-possible" 而不是 font-weight-numeric: "always"|"never"。由於 font-weight-named: "never" 暗示 永遠是數字，而 font-weight-notation: "numeric" 則使其 明確。

次要​

有些規則需要額外的彈性來處理特殊情況。這些規則可以使用一個可選的次要選項物件。例如，在

  • "font-weight-notation": "numeric" 沒有次要選項物件
  • "selector-max-type": [2, { "ignore": ["descendant] }]，次要選項物件為 { "ignore": ["descendant] }

最典型的次要選項為 "ignore": [] 和 "except": []。

關鍵字 "ignore" 和 "except"​

"ignore" 和 "except" 選項接受預定義關鍵字選項的陣列，例如 ["relative", "first-nested", "descendant"]

  • "ignore" 略過特定模式
  • "except" 為特定模式反轉主要選項
使用者定義的 "ignore*"​

有些規則接受要忽略的 使用者定義 清單。這採取 "ignore<Things>": [] 的形式，例如 "ignoreAtRules": []。

ignore* 選項讓使用者在 組態層級 忽略非標準語法。例如

  • CSS 模組中引入的 :global 和 :local 偽類別
  • SCSS 中引入的 @debug 和 @extend at 規則

方法論和語言擴充很快就會出現和消失，這種方法確保我們的程式碼庫不會充斥著過時事物的程式碼。

如果你的規則可以接受陣列作為其主要選項，你必須透過在規則函式上設定屬性 primaryOptionArray = true 來指定這一點。例如

function rule(primary, secondary) {
  return (root, result) => {
    /* .. */
  };
}

rule.primaryOptionArray = true;

module.exports = rule;

這裡有一個警告：如果你的規則接受主要選項陣列，它就不能也接受主要選項物件。只要有可能，如果你希望你的規則接受主要選項陣列，你應該讓陣列成為唯一的可能性，而不是允許各種資料結構。

新增問題訊息​

以以下形式新增問題訊息

  • "預期 [某事] [在某個脈絡中]"
  • "意外 [某事] [在某個脈絡中]"

如果規則具有自動修復功能，請使用

  • 對於短字串，'預期 "[未修復]" 為 "[已修復]"'
  • 對於長字串，'預期 "[主要]" ... 符號'

新增自動修復​

根據規則，透過使用 PostCSS API 變異 PostCSS AST (抽象語法樹)，有可能自動修復規則的問題。

將 meta.fixable = true 設定至規則

const meta = {
  url: /* .. */,
+ fixable: true,
};

將 context 變數新增至規則參數

-function rule(primary, secondary) {
+function rule(primary, secondary, context) {
  return (root, result) => {
    /* .. */
  };
}

context 是個物件，可能具有三個屬性

  • configurationComment(字串)：字串，用於設定組態註解的前置詞，例如 /* stylelint-disable */。
  • fix(布林值)：如果為 true，您的規則可以套用自動修正。
  • newline(字串)：目前已檢查檔案所使用的行尾字元。

如果 context.fix 為 true，則使用 PostCSS API 變更 root，並在呼叫 report() 之前提早傳回。

if (context.fix) {
  // Apply fixes using PostCSS API
  return; // Return and don't report a problem
}

report(/* .. */);

撰寫 README​

每個規則都附有一個 README，格式如下

  1. 規則名稱。
  2. 單行描述。
  3. 原型程式碼範例。
  4. 詳細描述（如有需要）。
  5. 選項。
  6. 範例模式，被視為問題（每個選項值）。
  7. 範例模式，不被視為問題（每個選項值）。
  8. 選用選項（如果適用）。

單行描述的格式為

  • no 規則為「禁止 ...」
  • max 規則為「限制 ...」
  • 接受 "always" 和 "never" 選項的規則為「要求 ...」
  • 其他所有規則為「指定 ...」

你應該

  • 從測試中挑選範例
  • 範例和選項中僅使用標準 CSS 語法
  • 新增最少的範例以傳達規則的意圖，而不是顯示邊緣案例
  • 在 css 程式碼區塊前使用 <!-- prettier-ignore -->
  • 使用「此規則」來指稱規則，例如「此規則忽略 ...」
  • 將原型程式碼範例中的箭頭與醒目結構的開頭對齊
  • 將原型程式碼範例中的文字盡可能左對齊

例如

 @media screen and (min-width: 768px) {}
/**                 ↑          ↑
  *       These names and values */

查看其他規則的 README，以收集更多慣例模式。

連接規則​

最後一步驟是在以下位置新增對新規則的參照

新增規則選項​

你應該

  1. 準備好貢獻程式碼。
  2. 新增單元測試來測試選項。
  3. 變更規則驗證以允許新選項。
  4. 在規則中新增（盡可能少）邏輯以通過測試。
  5. 新增關於新選項的文件。

修正規則中的錯誤​

你應該

  1. 準備好貢獻程式碼。
  2. 撰寫失敗的單元測試來舉例說明錯誤。
  3. 調整規則，直到這些新測試通過。

棄用規則​

很少會棄用規則。當您這麼做時，您必須

  1. 將 stylelintReference 連結指向 GitHub 網站上規則 README 的特定版本，以便隨時可以存取。
  2. 新增適當的元資料來標記規則為已棄用，例如 rule.meta = { deprecated: true }。

改善規則效能​

您可以使用以下方法對任何給定的規則執行基準測試，並使用任何有效的組態

npm run benchmark-rule -- ruleName ruleOptions [ruleContext]

如果 ruleOptions 參數不是字串或布林值，則它必須是包含在引號中的有效 JSON。

npm run benchmark-rule -- value-keyword-case lower
npm run benchmark-rule -- value-keyword-case '["lower", {"camelCaseSvgKeywords": true}]'

如果指定了 ruleContext 參數，則會套用相同的程序

npm run benchmark-rule -- value-keyword-case '["lower", {"camelCaseSvgKeywords": true}]' '{"fix": true}'

腳本載入 Bootstrap 的 CSS（從其 CDN）並透過已組態的規則執行它。

它最終會列印一些簡單的統計資料，如下所示

Warnings: 1441
Mean: 74.17598357142856 ms
Deviation: 16.63969674310928 ms

在撰寫新規則或重構現有規則時，請使用這些測量值來確定程式碼的效率。

Stylelint 規則可以重複其核心邏輯很多次（例如，檢查龐大 CSS 程式碼庫中每個宣告的每個值節點）。因此，值得注意效能，並盡我們所能來改善它！

改善規則效能是您想要一個快速小專案時，貢獻的絕佳方式。嘗試選擇一個規則，看看是否有任何方法可以加速它。

請務必在您的 pull request 中包含基準測試測量值！