移轉至 16.0.0
此版本包含重大或破壞性變更。
我們已將我們的原始碼移轉至 ECMAScript 模組 (ESM) — 歷時一年的努力，以允許 ESM 外掛程式、自訂語法和格式化程式，並朝著更新我們的純 ESM 相依項邁進。
為了給社群時間移轉至 ESM，我們將發布一個混合套件，以支援（現已不建議使用的）CommonJS Node.js API，直到我們的下一個主要版本。
重大變更
我們已
- 新增對 ESM 外掛程式的支援
- 新增對 ESM 自訂語法的支援
- 新增對 ESM 自訂格式化程式的支援
- 不建議使用 CommonJS Node.js API
- 重新編排以在內部使用
.mjs和.cjs副檔名
新增對 ESM 外掛程式的支援
您現在可以建立 ESM 外掛程式。
例如
import stylelint from "stylelint";
const {
createPlugin,
utils: { report, ruleMessages, validateOptions }
} = stylelint;
const ruleName = "foo-org/foo-bar";
const messages = ruleMessages(ruleName, {
rejected: (selector) => `Unexpected "foo"`
});
const meta = {
url: "https://foo.org/foo-bar"
};
const ruleFunction = (primary, secondaryOptions) => {
return (root, result) => {
const validOptions = validateOptions(/* .. */);
if (!validOptions) return;
/* .. */
report({
/* .. */
});
};
};
ruleFunction.ruleName = ruleName;
ruleFunction.messages = messages;
ruleFunction.meta = meta;
export default createPlugin(ruleName, ruleFunction);
我們已更新我們的 外掛程式開發人員指南，提供更多 ESM 語法的範例。
新增對 ESM 自訂語法的支援
現在您可以建立 ESM 自訂語法。
例如
import postcss from "postcss";
function parse(css, opts) {
/* .. */
}
function stringify(node, builder) {
/* .. */
}
export default { parse, stringify };
請參閱我們的開發人員指南中的 自訂語法區段 以取得更多範例。
新增對 ESM 自訂格式器的支援
現在您可以建立 ESM 自訂格式器。
例如
export default function yourOwnFormatter(results) {
/* .. */
}
請參閱我們的開發人員指南中的 自訂格式器區段 以取得更多範例。
已棄用的 CommonJS API
我們已棄用 CommonJS Node.js API，並將在下一個主要版本中移除它，以便我們可以更新我們的純 ESM 相依性。
如果您是外掛作者或使用 stylelint.lint() 來檢查檔案，則此棄用將會影響您。自訂語法和格式器不受影響，因為它們不會使用 Node.js API。
若要移轉至 ESM，您應該
- 將所有
require()/module.export替換為import/export - 如果您未使用
.mjs副檔名，請將"type": "module"新增至package.json - 僅對匯入使用完整的相對檔案路徑，例如，
import x from '.';→import x from './index.js';
我們也建議您
- 將
package.json中的"engines"欄位更新為"node": ">=18.12.0" - 從所有檔案中移除
'use strict'; - 在
package.json中新增"exports": "./index.js" - 對 Node.js 內建匯入使用
node:協定
有關更多詳細資訊，請參閱 Node.js 文件 以取得 ESM。
外掛
例如，若要將您的外掛移轉至使用 import 和 export
-const stylelint = require("stylelint");
+import stylelint from "stylelint";
const {
createPlugin,
utils: { report, validateOptions },
} = stylelint;
const ruleFunction = (primary, secondaryOptions) => { /* .. */ };
ruleFunction.ruleName = ruleName;
ruleFunction.messages = messages;
ruleFunction.meta = meta;
-module.exports = createPlugin(ruleName, ruleFunction);
+export default createPlugin(ruleName, ruleFunction);
如果您使用我們的 testRule 架構測試您的外掛，您可以
- 更新至我們
jest-preset-stylelint套件的最新版本 - 試用我們新的
stylelint-test-rule-node套件，它使用node:test|assert
jest-preset-stylelint
此預設值需要 --experimental-vm-modules Node.js 旗標來支援 ESM。您可以使用 cross-env 套件在 npm-run-script 中設定 NODE_OPTIONS 環境變數
{
"scripts": {
- "test": "jest",
+ "test": "cross-env NODE_OPTIONS=\"--experimental-vm-modules --no-warnings\" jest --runInBand",
}
}
(cross-env 處於維護模式，因為它 被認為已完成。)
如果您收到錯誤訊息（例如在 Node.js 18 上執行預設值時發生分段錯誤），您可以嘗試在 Jest 設定中使用 jest-light-runner
export default {
preset: "jest-preset-stylelint",
setupFiles: ["./jest.setup.js"],
+ runner: "jest-light-runner",
};
執行器有有限的涵蓋範圍支援。
stylelint-test-rule-node
要嘗試我們新的 stylelint-test-rule-node 套件，您應該將它匯入您的測試檔案
+import { testRule } from "stylelint-test-rule-node";
testRule({
/* .. */
});
並更新您的 npm-run-script
{
"scripts": {
- "test": "jest"
+ "test": "node --test"
}
}
此套件使用 node:test，這是 Node.js 18 中的實驗性功能，但在 20 中是穩定的。涵蓋範圍支援也是實驗性的。
如果您有其他 Jest 測試，您需要調整它們以使用 node:test，例如 expect() 會變成 assert()。
stylelint.lint()
例如，要將使用 stylelint.lint() 的程式碼移轉為使用 import 和頂層 await
-const stylelint = require("stylelint");
+import stylelint from "stylelint";
-stylelint.lint(options).then((result) => { console.log(result); });
+const result = await stylelint.lint(options);
+console.log(result);
您可以在 使用者指南 中找到有關 ESM Node.js API 的更多詳細資訊。
使用 CommonJS Node.js API 會觸發不建議使用的警告。如果您還沒有準備好移轉到 ESM，您可以使用 quietDeprecationWarnings 選項來隱藏警告。
const stylelint = require("stylelint");
const resultPromise = stylelint.lint({
/* .. */
+ quietDeprecationWarnings: true
});
重新整理以在內部使用 .mjs 和 .cjs 副檔名
我們現在在內部使用 .mjs 和 .cjs 副檔名來支援混合套件。此變更不會影響我們的公開 API，但如果您的外掛程式 require 內部檔案，它將會影響您。
我們建議將檔案複製到您的專案中，而不是匯入它們，因為我們會在下一個主要版本中移除對它們的存取權。
但是，您可以在下一個主要版本之前透過更新匯入繼續不安全地 import 或 require 檔案
// ESM
-import('stylelint/lib/utils/typeGuards.js');
+import('stylelint/lib/utils/typeGuards.mjs');
// CommonJS
-require('stylelint/lib/utils/typeGuards.js');
+require('stylelint/lib/utils/typeGuards.cjs');
重大變更
我們已
- 移除不建議使用的風格規則
- 移除對 Node.js 低於 18.12.0 的支援
- 變更 Node.js API 傳回已解析的物件
- 變更 Node.js API
stylelint.formatters物件 - 變更 Node.js API
stylelint.rules物件 - 變更 Node.js API
stylelint.utils.checkAgainstRule()函式 - 變更 CLI 以將問題列印至 stderr
- 變更 CLI 退出碼以取得旗標錯誤
- 變更預設語法行為，不論副檔名為何，皆使用 safe-parser 搭配
fix
移除已棄用的風格規則
我們已移除在 15.0.0 中已棄用的風格規則。
您應該從設定物件中移除這些規則。請參閱 15.0.0 移轉指南 以取得更多詳細資訊。
移除對低於 18.12.0 的 Node.js 支援
Node.js 14 和 16 已達使用期限。我們已移除對它們的支援以更新某些相依性。
您應該使用 18.12.0 或更高版本的 Node.js。
變更 Node.js API 回傳的已解決物件
我們已變更 stylelint.lint() 回傳的 Promise 的已解決物件，因此新的
我們已棄用 output 屬性，改用新的 report 和 code 屬性，並將在下一主要版本中移除它。
如果您使用 stylelint.lint() 來檢查來源字串，且 fix 選項為 true，則 report 屬性將包含格式化的問題，而 code 屬性將包含已修正的程式碼。
const result = await stylelint.lint({
code: "a {}",
fix: true
});
-const fixedCode = result.output;
+const formattedProblems = result.report;
+const fixedCode = result.code;
如果您使用 stylelint.lint() 來檢查檔案，則 code 屬性將永遠為 undefined。
變更 Node.js API stylelint.formatters 物件
我們已變更 Node.js API 中的 stylelint.formatters 物件，讓每個格式化程式都成為 Promise 函式。
-const formatter = stylelint.formatters.json;
+const formatter = await stylelint.formatters.json;
變更 Node.js API stylelint.rules 物件
我們已變更 Node.js API 中的 stylelint.rules 物件，讓每個規則都成為 Promise 函式。
-const rule = stylelint.rules['block-no-empty'];
+const rule = await stylelint.rules['block-no-empty'];
已變更 Node.js API stylelint.utils.checkAgainstRule() 函式
我們已變更 Node.js API 中的 stylelint.utils.checkAgainstRule() 函式，使其成為非同步函式。
-checkAgainstRule({ /* .. */ });
+await checkAgainstRule({ /* .. */ });
已變更 CLI 以將問題列印至 stderr
我們已變更 CLI，將問題列印至 stderr，而非 stdout。
如果您使用 --fix 和 --stdin 選項，CLI 會將修正後的程式碼列印至 stdout，並將任何問題列印至 stderr。
如果您使用 > 將標準輸出重新導向，例如從自訂格式化程式，您可以改用 --output-file 旗標
-npx stylelint "*.css" --custom-formatter custom-formatter.js > output.txt
+npx stylelint "*.css" --custom-formatter custom-formatter.js --output-file output.txt
已變更 CLI 退出碼以供旗標錯誤
我們已將 CLI 旗標錯誤的退出碼從 2 變更為 64，以便保留 2 以供程式碼檢查問題使用。
如果您是使用 CLI 的編輯器整合的作者，您現在可以區分旗標錯誤和程式碼檢查問題。
已變更預設語法行為，以在修正時始終使用 safe-parser，而不論副檔名
我們已變更預設語法行為，以在自動修正 CSS 程式碼時始終使用 postcss-safe-parser，而不論檔案的副檔名。先前，只有 .css、.pcss 或 .postcss 檔案會使用 postcss-safe-parser 自動修正。