Sass 插件

插件包	@rushstack/heft-sass-plugin
插件名称	sass-plugin 由 SassPlugin.ts 实现
插件配置文件	sass.json
heft.json 选项	(无)

此插件为 CSS 样式生成 TypeScript 类型定义。它支持三种不同的样式表格式

• .css 用于普通 层叠样式表
• .scss 通过 语法优美的样式表 (Sass) 项目定义的预处理器宏扩展了 CSS 文件格式
• .sass 较旧的 缩进语法 仍然受到支持，因为有些人更喜欢它

何时使用它

我们建议将 Sass 用于任何使用 CSS 样式的 TypeScript Web 应用程序。.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 生成的。您可以重复使用此库来实现自定义 Heft 插件，这些插件可以为除 CSS 之外的其他资源生成类型定义。

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 项目文件夹。

配置

如果 Sass 尚未由 Rig 提供，您的 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)