重大變更：舊版 JS API

遷移用法遷移用法永久連結

進入點進入點永久連結

舊版 JS API 有兩個編譯 Sass 的進入點：`render` 和 `renderSync`，它們接受一個包含 `file`（用於編譯檔案）或 `data`（用於編譯字串）的選項物件。現代化 API 有四個：`compile` 和 `compileAsync` 用於編譯檔案，`compileString` 和 `compileStringAsync` 用於編譯字串。這些函式將路徑或原始碼字串作為第一個參數，然後將所有其他選項的物件作為第二個參數。與使用回呼的 `render` 不同，`compileAsync` 和 `compileStringAsync` 會返回一個 Promise。

有關更多詳細資訊，請參閱使用說明文件。

匯入器匯入器永久連結

在舊版 API 中，匯入器是由單一函式組成，它接受依賴規則 URL 和包含樣式表的 URL（以及用於非同步匯入器的 `done` 回呼），並返回一個物件，其中包含磁碟上的 `file` 路徑或要載入的樣式表的 `contents`。

現代 API 的 `Importer` 則包含兩個方法：`canonicalize`，它接受一個規則 URL 並返回該 URL 的標準形式；以及 `load`，它接受一個標準 URL 並返回一個包含已載入樣式表內容的物件。這種拆分確保相同的模組只載入一次，並且相對 URL 能夠一致地工作。非同步匯入器的這兩個方法都會返回 Promise。

還有一個特殊的 `FileImporter`，它將所有載入重定向到磁碟上的現有檔案，當從返回 `file` 而不是 `contents` 的舊版匯入器遷移時，應該使用它。

自訂函式自訂函式永久連結

在舊版 JS API 中，自訂函式為每個 Sass 參數接受一個單獨的 JS 參數，並為非同步自訂函式額外提供一個 `done` 回呼。在現代 API 中，自訂函式則接受單個 JS 參數，其中包含所有 Sass 參數的列表，非同步自訂函式會返回一個 Promise。

現代 API 也使用更強大的 `Value` 類別，它支援所有 Sass 值類型、類型斷言，以及方便的 Map 和 List 查找。

打包工具打包工具永久連結

如果您使用的是打包工具或其他呼叫 Sass API 的工具，而不是直接使用它，您可能需要更改傳遞給該工具的設定，以告知它使用現代 API。

Webpack 預設應該已經使用現代 API，但如果您收到警告，請將 `api` 設定為 `"modern"` 或 `"modern-compiler"`。詳情請參閱Webpack 的文件。

Vite 仍然預設使用舊版 API，但您同樣可以透過將 `api` 設定為 `"modern"` 或 `"modern-compiler"` 來切換它。詳情請參閱Vite 的文件。

對於其他工具，請查看其文件或問題追蹤器，以取得有關支援現代 Sass API 的資訊。

抑制警告抑制警告永久連結

雖然舊版 JS API 在 Dart Sass 1.45.0 中與現代 API 的發佈一起被標記為已棄用，但我們從 Dart Sass 1.79.0 開始發出使用它的警告。如果您還無法遷移到現代 API，但想暫時抑制警告，您可以在 `silenceDeprecations` 選項中傳遞 `legacy-js-api`。

const sass = require('sass');

const result = sass.renderSync({
  silenceDeprecations: ['legacy-js-api'],
  ...
});

這將暫時抑制警告，但舊版 API 將在 Dart Sass 2.0.0 中完全移除，因此您仍然應該計畫儘快遷移。