Sass 外掛

外掛套件	@rushstack/heft-sass-plugin
外掛名稱	sass-plugin 由 SassPlugin.ts 執行
外掛設定檔	sass.json
heft設定檔選項	(無)

此外掛為 CSS 樣式產生 TypeScript 型別。它支援三種不同的樣式表格式

• .css 為標準的 層疊樣式表
• .scss 以 Syntactically Awesome Style Sheet (Sass) 專案定義的前置處理器巨集擴充 CSS 檔案格式
• .sass 較舊的 排版縮進語法，因為有些人偏愛此語法，因此仍獲得支援

何時使用

對於任何使用 CSS 風格的 TypeScript 網路應用程式，我們建議使用 Sass。由於 .scss 檔案格式的語法是純粹 CSS 的適當超集，因此此格式是建議的選項。

運作方式

假設你的 CSS 風格定義於下列檔案中

src/my-styles.scss

$marginValue: 20px;

.label {
  margin-bottom: $marginValue;
}

在 Heft 呼叫 TypeScript 編譯器之前，sass-plugin 可產生包含型別宣告的暫時檔案

temp/sass-ts/styles.scss.d.ts

// This file was generated by a tool. Modifying it will produce unexpected behavior
export interface IExportStyles {
  label: string;
}
declare const strings: IExportStyles;
export default strings;

這會啟用，使 styles.label 樣式能夠像這樣匯入

src/ExampleApp.tsx

import * as React from 'react';
import styles from './my-styles.scss';

export class ExampleApp extends React.Component {
  public render(): React.ReactNode {
    return <p className={styles.label}>Example text</p>;
  }
}

create-react-app 等工具鏈所使用的典型手法，會產生未型別化的 styles 物件。這可能會導致錯誤。Heft 產生的 .d.ts 檔案可提供樣式名稱完整的 IntelliSense，並使編譯器能夠偵測到常見的錯誤，例如錯誤拼寫的識別項。

.d.ts 檔案使用 @rushstack/typings-generator 產生。您可以重複使用這個函式庫，實作除了 CSS 以外，針對其他資源產生鍵入的客製化 Heft 外掛程式。

sass-plugin 會自動產生任何位於 src 資料夾且具有支援的副檔名 (.css、.scss 和 .sass) 檔案的鍵入。可以使用 sass.json 設定檔自訂其行為，但在大多數情況下，預設行為就已足夠。

build-tests/heft-sass-test 專案提供了 .css、.scss 和 .sass 匯入的範例。

package.json 相依性

如果您使用的是 @rushstack/heft-web-rig，那麼 Sass 會被自動載入並設定好。

否則，您需要將外掛程式套件新增到專案

Rush

# If you are using Rush, run this shell command in your project folder:
rush add --package @rushstack/heft-sass-plugin --dev

NPM

# If you are using vanilla NPM, run this shell command in your project folder:
npm install @rushstack/heft-sass-plugin --save-dev

由於外掛程式只會產生 TypeScript 鍵入，您的專案需要額外的組態才能呼叫 Sass 處理器來轉譯樣式。具體情況取決於您的綑綁組態。如要取得使用 Webpack 的完整範例，請參閱 heft-web-rig 專案資料夾。

組態

如果 rig 尚未提供 Sass，您的 heft.json 組態檔案 應像此範例一樣呼叫它

<專案資料夾>/config/heft.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json",

  . . .
  "phasesByName": {
    "build": {
      "cleanFiles": [
        { "sourcePath": "dist" },
        { "sourcePath": "lib" },
        { "sourcePath": "lib-amd" },
        { "sourcePath": "lib-commonjs" },
        { "sourcePath": "lib-es6" }
      ],
      "tasksByName": {
        "sass": {
          "taskPlugin": {
            "pluginPackage": "@rushstack/heft-sass-plugin"
          }
        },
        "typescript": {
          "taskDependencies": ["sass"],
          "taskPlugin": {
            "pluginPackage": "@rushstack/heft-typescript-plugin"
          }
        },
        "webpack": {
          "taskDependencies": ["typescript"],
          "taskPlugin": {
            "pluginPackage": "@rushstack/heft-webpack5-plugin"
          }
        }
      }
    }
    . . .
  }
}

透過將 temp/sass-ts 新增到編譯器組態中的 rootDirs 設定來參照產生的鍵入

tsconfig.json

{
  "$schema": "http://json.schemastore.org/tsconfig",

  "compilerOptions": {
    "rootDirs": ["src/", "temp/sass-ts/"],
  . . .

請確定您 typescript.json 檔案中的 staticAssetsToCopy 設定組態為複製 .css、.scss 和 .sass 檔案副檔名。

另請參閱

• config/sass.json 適用於 Heft 的組態檔案
• 語法上超棒的樣式表 (Sass)