dart sass

Sass 的 Dart 實作。 Sass 讓 CSS 變得有趣。

• 使用 Dart Sass

• sass_api包

• 瀏覽器中的 Dart Sass

• 舊版 JavaScript API

• 將 Sass 與 Jest 結合使用

• 來自 Chocolatey 或 Scoop (Windows)

• 來自自製軟體 (macOS)

• 獨立式

• 來自 npm

• 來自酒吧

• 從源頭

• 在 Docker 中

• 為什麼是達特？

• 相容性政策

• 瀏覽器相容性

• Node.js 相容性

• 無效的CSS

• 嵌入式 Dart Sass

• 用法

• 與 Ruby Sass 的行為差異

使用 Dart Sass

有幾種不同的方法來安裝和運行 Dart Sass，具體取決於您的環境和需求。

來自 Chocolatey 或 Scoop (Windows)

如果您使用 Windows 的 Chocolatey 套件管理器或 Scoop 套件管理器，則可以透過執行來安裝 Dart Sass

 choco 安裝 sass

或者

舀安裝 sass

這將在命令列上為您提供一個sass可執行文件，該可執行文件將運行 Dart Sass。有關詳細信息，請參閱 CLI 文件。

從 Homebrew（macOS 或 Linux）

如果您使用 Homebrew 套件管理器，則可以透過執行來安裝 Dart Sass

沖泡安裝 sass/sass/sass

這將在命令列上為您提供一個sass可執行文件，該可執行文件將運行 Dart Sass。

獨立式

您可以從 GitHub 發布頁面下載適用於您的作業系統的獨立 Dart Sass 存檔，其中包含 Dart VM 和可執行檔的快照。解壓縮它，將目錄添加到您的路徑中，重新啟動終端， sass可執行檔就可以運行了！

來自 npm

Dart Sass 可以作為 npm 套件編譯為 JavaScript。您可以使用npm install -g sass全域安裝它，這將提供對sass可執行檔的存取。您也可以使用npm install --save-dev sass將其新增至您的專案。這提供了可執行檔和庫：

 const sass = require('sass');const result = sass.compile(scssFilename);// OR// 注意，`compileAsync()` 比`compile()` 慢得多。 ( scss檔名);

請參閱 Sass 網站以取得完整的 API 文件。

瀏覽器中的 Dart Sass

sass npm 套件也可以直接在瀏覽器中運作。只要您停用重新命名（例如 esbuild 中的--keep-names ），它就與所有主要的 Web 捆綁程式相容。您也可以直接從瀏覽器將其作為 ECMAScript 模組匯入，無需任何捆綁（假設也提供了node_modules ）：

 <腳本類型=「匯入映射」>
  {“導入”：{“不可變”：“./node_modules/immutable/dist/immutable.es.js”，”sass”：“./node_modules/sass/sass.default.js”}
  }</script><!-- 支援 Safari 16.3 等瀏覽器，不支援匯入地圖。 --><script async src="https://unpkg.com/es-module-shims@^1.7.0" crossorigin="anonymous"></script><script type="module">
  從 'sass' 導入 * as sass；

  console.log(sass.compileString(` .box { width: 10px + 15px; } `));</script>

或從 CDN：

 <腳本類型=「匯入映射」>
  {“導入”：{“不可變”：“https://unpkg.com/immutable@^4.0.0”，“sass”：“https://unpkg.com/sass@^1.63.0/sass. default .js"}
  }</script><!-- 支援 Safari 16.3 等瀏覽器，不支援匯入地圖。 --><script async src="https://unpkg.com/es-module-shims@^1.7.0" crossorigin="anonymous"></script><script type="module">
  從 'sass' 導入* as sass；

  console.log(sass.compileString(` .box { width: 10px + 15px; } `));</script>

或甚至與其所有依賴項捆綁在一起：

 <腳本類型=“模組”>
  從'https://jspm.dev/sass'導入*作為sass；

  console.log(sass.compileString(` .box { width: 10px + 15px; } `));</script>

由於瀏覽器無法存取檔案系統，因此無法使用compile()和compileAsync()函數。如果要載入其他文件，則需要將自訂導入器傳遞給compileString()或compileStringAsync() 。瀏覽器也不支援舊版 API。

舊版 JavaScript API

Dart Sass 也支援與 Node Sass 完全相容的舊版 JavaScript API（下面列出了一些例外），並支援render()和renderSync()函數。該 API 已被視為已棄用，並將在 Dart Sass 2.0.0 中刪除，因此在新專案中應避免使用。

Sass 對舊版 JavaScript API 的支援有以下限制：

• 僅支援outputStyle的"expanded"和"compressed"值。

• Dart Sass 不支援precision選項。 Dart Sass 預設為所有現有瀏覽器提供足夠高的精度，並且進行自訂將使程式碼效率大大降低。

• Dart Sass 不支援sourceComments選項。來源映射是定位生成選擇器來源的建議方法。

將 Sass 與 Jest 結合使用

如果您使用 Jest 來執行測試，請注意它有一個長期存在的錯誤，即它的預設測試環境會破壞 JavaScript 的內建instanceof運算子。 Dart Sass 的 JS 套件相當多地使用了instanceof ，因此為了避免破壞 Sass，您需要安裝jest-environment-node-single-context並將testEnvironment: 'jest-environment-node-single-context'添加到您的Jest配置中。

來自酒吧

如果您是 Dart 用戶，可以使用pub global activate sass全域安裝 Dart Sass，這將提供sass執行檔。您也可以將其新增至您的 pubspec 並將其用作庫。我們強烈建議使用前綴sass導入它：

導入 'package:sass/sass.dart' as sass;void main(List<String> args) { print(sass.compile(args.first));
}

有關詳細信息，請參閱 Dart API 文件。

sass_api包

Dart 用戶還可以透過sass_api包存取更深入的 API。這提供了對 Sass AST 和 API 的訪問，用於解析 Sass 負載，而無需運行完整編譯。它被分離到自己的包中，以便它可以獨立於主sass包來增加其版本號。

從源頭

假設您已經簽出此儲存庫：

1. 安裝飛鏢。如果您手動下載存檔而不是使用安裝程序，請確保 SDK 的bin目錄位於您的PATH中。

2. 安裝緩衝區。這用於為嵌入式編譯器建立協定緩衝區。

3. 在此儲存庫中，執行dart pub get 。這將安裝 Dart Sass 的依賴項。

4. 運行dart run grinder protobuf 。這將下載並建立嵌入式協定定義。

5. 執行dart bin/sass.dart path/to/file.scss 。

就是這樣！

在 Docker 中

您可以使用以下 Dockerfile 命令在 Docker 中安裝並執行 Dart Sass：

 # Dart stageFROM bufbuild/buf AS bufFROM dart:stable AS dart# 新增您的scss 檔案COPY --from=another_stage /app /app# 包含協定緩衝區二進位檔案COPY --from=buf /usr/local/bin/buf /usr/local/ bin/WORKDIR /dart-sassRUN git 克隆 https://github.com/sass/dart-sass.git 。 &&
   飛鏢酒吧獲取 &&
   dart rungrinderprotobuf# 這是您在 scss 檔案上執行 sass.dart 的地方RUN dart ./bin/sass.dart /app/sass/example.scss /app/public/css/example.css

為什麼是達特？

Dart Sass 已取代 Ruby Sass 成為 Sass 語言的規範實作。我們選擇 Dart 是因為它有許多優點：

• 速度很快。 Dart VM 經過高度最佳化，並且一直在變得越來越快（有關最新的效能數據，請參閱perf.md ）。它比 Ruby 快得多，並且與 C++ 接近。

• 它是便攜式的。 Dart VM 沒有外部依賴項，可以將應用程式編譯成獨立的快照文件，因此我們可以將 Dart Sass 分發為僅三個文件（VM、快照和包裝器腳本）。 Dart 也可以編譯為 JavaScript，這使得透過 npm 分發 Sass 變得很容易，我們的大多數使用者已經在使用 npm。

• 很容易寫。 Dart 是一種比 C++ 更高級的語言，這意味著它不需要太多記憶體管理和建置系統的麻煩。它也是靜態類型的，這使得比 Ruby 更容易自信地進行大型重構。

• 它對貢獻者更友好。 Dart 比 Ruby 更容易學習，尤其是 Google 中的許多 Sass 用戶已經熟悉它。更多的貢獻者意味著更快、更一致的開發。

相容性政策

在大多數情況下，Dart Sass 遵循語義版本控制。我們認為以下所有內容都是版本化 API 的一部分：

• Dart Sass 實作的 Sass 語言語意。

• 達特 API。

• JavaScript API。

• 命令列介面。

由於 Dart Sass 具有跨 Dart、JavaScript 和獨立發行版共享的單一版本，因此這可能意味著當一個或多個發行版實際上沒有重大變更時，我們會增加主版本號。但是，我們將嘗試限制所做的重大更改的數量，並將它們分組到盡可能少的版本中，以最大程度地減少客戶流失。我們強烈鼓勵使用者使用變更日誌來充分了解每個版本中的所有變更。

有一個例外，即可能在主要版本修訂之外進行重大更改。有時 CSS 會添加與現有 Sass 語法在某種程度上不相容的功能。由於 Sass 致力於完全相容於 CSS，因此我們有時需要破壞與舊 Sass 程式碼的兼容性，以保持與 CSS 的兼容性。

在這些情況下，我們將首先發布一個 Sass 版本，該版本會對任何行為將發生變化的樣式表發出棄用警告。然後，在發布包含這些棄用警告的版本至少三個月後，我們將發布一個對 Sass 語言語義進行重大更改的次要版本。

瀏覽器相容性

一般來說，我們認為對 Dart Sass 的 CSS 輸出進行的任何更改都會導致 CSS 在真實瀏覽器中停止工作，這都是重大更改。然而，在某些情況下，這種更改會帶來巨大的好處，並且只會對一小部分很少使用的瀏覽器產生負面影響。我們不想在主要版本發佈時阻止此類更改。

因此，如果某項變更會破壞與 StatCounter GlobalStats 統計的全球市佔率不到 2% 的瀏覽器的兼容性，我們可能會發布包含該變更的 Dart Sass 次要版本。

Node.js 相容性

只要Node.js 仍支援該版本，我們就認為放棄對給定版本的 Node.js 的支援是一項重大變更。這表示根據 Node.js 版本頁面，版本​​被列為「目前」、「活動 LTS」或「維護 LTS」。一旦 Node.js 版本不再支援 LTS，Dart Sass 就會認為自己可以在必要時中斷支援。

無效的 CSS

對產生無效 CSS 輸出的 Sass 樣式表行為的變更不被視為重大變更。在新增對新 CSS 功能的支援時，此類變更幾乎總是必要的，而將所有此類功能延遲到新的主要版本對大多數用戶來說會造成過度負擔。

例如，當 Sass 開始解析calc()表達式時，無效表達式calc(1 +)變成了 Sass 錯誤，而之前它是按原樣傳遞的。這不被認為是重大更改，因為calc(1 +)從一開始就不是有效的 CSS。

嵌入式 Dart Sass

Dart Sass 包含嵌入式 Sass 協定的編譯器端的實作。它被設計為嵌入到主機語言中，然後公開 API 供使用者呼叫 Sass 並定義自訂函數和導入器。

用法

• sass --embedded啟動嵌入式編譯器並監聽標準輸入。

• sass --embedded --version在 JSON 中列印id = 0的versionResponse並退出。

當您將 Dart Sass 安裝為 npm 套件時， --embedded命令列標誌不可用。 --embedded不支援其他命令列標誌。

與 Ruby Sass 的行為差異

Dart Sass 和 Ruby Sass 之間存在一些故意的行為差異。這些通常是 Ruby Sass 出現不良行為的地方，實現正確的行為比實現相容的行為要容易得多。這些都應該具有針對 Ruby Sass 的追蹤錯誤以更新參考行為。

1. @extend只接受簡單選擇器，就像selector-extend()的第二個參數一樣。請參閱第 1599 期。

2. 不支援主題選擇器。請參閱第 1126 期。

3. 偽選擇器參數被解析為<declaration-value> ，而不是進行更有限的自訂解析。請參閱第 2120 期。

4. 數字精度設定為 10。

5. 縮排語法解析器更靈活：它不需要整個文件的縮排一致。請參閱問題 2176。

6. 顏色不支援逐通道算術。請參閱第 2144 期。

7. 無單位數字不==具有相同值的單位數字。此外，映射鍵遵循與== -equality 相同的邏輯。請參閱第 1496 期。

8. 帶有百分比單位的rgba()和hsla() alpha 值被解釋為百分比。其他單位禁止。請參閱第 1525 期。

9. 傳遞給函數的可變參數過多是一個錯誤。請參閱問題 1408。

10. 如果在媒體查詢外部定義了相同的@extend ，則允許@extend到達媒體查詢外部。這不會被明確跟踪，因為當問題 1050 得到修復時，它將變得無關緊要。

11. 一些包含佔位符選擇器的偽選擇器將在 Ruby Sass 中不存在的地方進行編譯。這更好地匹配相關選擇器的語義，並且效率更高。請參閱第 2228 期。

12. 縮排語法不支援舊式:property value語法。請參閱第 2245 期。

13. 不支援參考組合器。請參閱第 303 期。

14. 通用選擇器統一是對稱的。請參閱問題 2247。

15. @extend如果符合但無法統一，則不會產生錯誤。請參閱第 2250 期。

16. Dart Sass 目前僅支援 UTF-8 文件。我們希望支援更多，但 Dart 目前不支援它們。例如，請參閱 dart-lang/sdk#11744。

免責聲明：這不是 Google 官方產品。