LegacySharedOptions<sync>

用于 render 和 renderSync 的选项，这些选项在 LegacyFileOptions 和 LegacyStringOptions 之间共享。

已弃用

这仅适用于旧版 render 和 renderSync API。使用 Options 与 compile、compileString、compileAsync 和 compileStringAsync 代替。

类型参数

sync extends "sync" | "async"

这允许 TypeScript 检查器验证 LegacyAsyncImporter 和 LegacyAsyncFunction 没有传递给 renderSync。

层次结构

LegacySharedOptions
- LegacyFileOptions
- LegacyStringOptions

索引

输入

`可选` includePaths

includePaths?: string[]

Dart Sass: 自 1.15.0 起
Node Sass: 自 3.9.0 起

早期版本的 Dart Sass 和 Node Sass 不支持 SASS_PATH 环境变量。

此字符串数组选项提供了加载路径，Sass 将在这些路径中查找样式表。较早的加载路径优先于较晚的加载路径。

sass.renderSync({
  file: "style.scss",
  includePaths: ["node_modules/bootstrap/dist/css"]
});

加载路径也从 SASS_PATH 环境变量加载（如果设置）。此变量应为用 ;（在 Windows 上）或 :（在其他操作系统上）分隔的路径列表。来自 includePaths 选项的加载路径优先于来自 SASS_PATH 的加载路径。

$ SASS_PATH=node_modules/bootstrap/dist/css sass style.scss style.css

输出

`可选` charset

charset?: boolean

Dart Sass: 自 1.39.0 起
Node Sass: ✗

默认情况下，如果 CSS 文档包含非 ASCII 字符，Sass 会添加一个 @charset 声明（在扩展输出模式下）或一个字节顺序标记（在压缩模式下）来指示其编码给浏览器或其他使用者。如果 charset 为 false，则会省略这些注释。

`可选` indentType

indentType?: "space" | "tab"

Dart Sass: ✓
Node Sass: 自 3.0.0 起

生成的 CSS 是否应使用空格或制表符进行缩进。

const result = sass.renderSync({
  file: "style.scss",
  indentType: "tab",
  indentWidth: 1
});

result.css.toString();
// "h1 {\n\tfont-size: 40px;\n}\n"

默认值

'space'

`可选` indentWidth

indentWidth?: number

Dart Sass: ✓
Node Sass: 自 3.0.0 起

在生成的 CSS 中，每个缩进级别应使用多少个空格或制表符（取决于 indentType）。它必须介于 0 到 10 之间（含）。

默认值

2

`可选` 换行符

linefeed?: "cr" | "crlf" | "lf" | "lfcr"

Dart Sass: ✓
Node Sass: 自 3.0.0 起

在生成的 CSS 中每一行的末尾使用哪个字符序列。它可以有以下值

'lf' 使用 U+000A 换行.
'lfcr' 使用 U+000A 换行后面跟着 U+000D 回车.
'cr' 使用 U+000D 回车.
'crlf' 使用 U+000D 回车后面跟着 U+000A 换行.

默认值

'lf'

`可选` 输出样式

outputStyle?: "expanded" | "compact" | "compressed" | "nested"

编译后的 CSS 的输出样式。有四种可能的输出样式

"expanded" （Dart Sass 的默认值）将每个选择器和声明写入单独的行。
"compressed" 删除尽可能多的额外字符，并将整个样式表写入一行。
"nested" （Node Sass 的默认值，Dart Sass 不支持）缩进 CSS 规则以匹配 Sass 源代码的嵌套。
"compact" （Dart Sass 不支持）将每个 CSS 规则放在单独的一行。

示例

const source = `
h1 {
  font-size: 40px;
  code {
    font-face: Roboto Mono;
  }
}`;

let result = sass.renderSync({
  data: source,
  outputStyle: "expanded"
});
console.log(result.css.toString());
// h1 {
//   font-size: 40px;
// }
// h1 code {
//   font-face: Roboto Mono;
// }

result = sass.renderSync({
  data: source,
  outputStyle: "compressed"
});
console.log(result.css.toString());
// h1{font-size:40px}h1 code{font-face:Roboto Mono}

result = sass.renderSync({
  data: source,
  outputStyle: "nested"
});
console.log(result.css.toString());
// h1 {
//   font-size: 40px; }
//   h1 code {
//     font-face: Roboto Mono; }

result = sass.renderSync({
  data: source,
  outputStyle: "compact"
});
console.log(result.css.toString());
// h1 { font-size: 40px; }
// h1 code { font-face: Roboto Mono; }

插件

`可选` 函数

functions?: {
[key: string]: LegacyFunction<sync>;
}

所有样式表中可用的额外内置 Sass 函数。此选项接受一个对象，其键是 Sass 函数签名，其值是 LegacyFunction。每个函数应接受与其签名相同的参数。

函数传递 LegacyValue 的子类，并且必须返回相同的值。

⚠️ 注意！

编写自定义函数时，务必确保所有参数都是您期望的类型。否则，用户的样式表可能会以难以调试的方式崩溃，或者更糟的是，编译成毫无意义的 CSS。

示例

sass.render({
  data: `
h1 {
  font-size: pow(2, 5) * 1px;
}`,
  functions: {
    // This function uses the synchronous API, and can be passed to either
    // renderSync() or render().
    'pow($base, $exponent)': function(base, exponent) {
      if (!(base instanceof sass.types.Number)) {
        throw "$base: Expected a number.";
      } else if (base.getUnit()) {
        throw "$base: Expected a unitless number.";
      }

      if (!(exponent instanceof sass.types.Number)) {
        throw "$exponent: Expected a number.";
      } else if (exponent.getUnit()) {
        throw "$exponent: Expected a unitless number.";
      }

      return new sass.types.Number(
          Math.pow(base.getValue(), exponent.getValue()));
    },

    // This function uses the asynchronous API, and can only be passed to
    // render().
    'sqrt($number)': function(number, done) {
      if (!(number instanceof sass.types.Number)) {
        throw "$number: Expected a number.";
      } else if (number.getUnit()) {
        throw "$number: Expected a unitless number.";
      }

      done(new sass.types.Number(Math.sqrt(number.getValue())));
    }
  }
}, function(err, result) {
  console.log(result.css.toString());
  // h1 {
  //   font-size: 32px;
  // }
});

类型声明

[key: string]: LegacyFunction<sync>

`可选` 导入器

importer?: LegacyImporter<sync> | LegacyImporter<sync>[]

Dart Sass: ✓
Node Sass: 自 3.0.0 起

3.0.0 之前的 Node Sass 版本不支持导入器数组，也不支持返回 Error 对象的导入器。

2.0.0 之前的 Node Sass 版本不支持 importer 选项。

Dart Sass: 从 1.20.2 开始
Node Sass: ✗

1.20.2 之前的 Dart Sass 版本优先使用 includePaths 解析导入，然后再使用自定义导入器解析。

目前所有版本的 Node Sass 都在将导入加载到出现 @import 的文件所在的目录之前将导入传递给导入器。此行为被认为是不正确的，不应该依赖，因为它违反了局部性原则，该原则指出应该能够在不了解整个系统设置的情况下对样式表进行推理。如果用户尝试相对于另一个样式表导入样式表，该导入应该始终有效。不应该允许其他地方的某些配置破坏它。

当遇到 @use 规则或 @import 规则时，用于加载文件的附加处理程序。它可以是单个 LegacyImporter 函数，也可以是 LegacyImporter 数组。

导入器接受 @import 或 @use 规则的 URL，并返回一个 LegacyImporterResult，指示如何处理该规则。有关更多详细信息，请参阅 LegacySyncImporter 和 LegacyAsyncImporter。

加载按以下顺序解析

从磁盘加载一个相对于出现 @use 或 @import 的文件的文件。
每个自定义导入器。
加载一个相对于当前工作目录的文件。
includePaths 中的每个加载路径。
在 SASS_PATH 环境变量中指定的每个加载路径，它应该在 Windows 上用分号分隔，在其他地方用冒号分隔。

示例

sass.render({
  file: "style.scss",
  importer: [
    // This importer uses the synchronous API, and can be passed to either
    // renderSync() or render().
    function(url, prev) {
      // This generates a stylesheet from scratch for `@use "big-headers"`.
      if (url != "big-headers") return null;

      return {
        contents: `
h1 {
  font-size: 40px;
}`
      };
    },

    // This importer uses the asynchronous API, and can only be passed to
    // render().
    function(url, prev, done) {
      // Convert `@use "foo/bar"` to "node_modules/foo/sass/bar".
      const components = url.split('/');
      const innerPath = components.slice(1).join('/');
      done({
        file: `node_modules/${components.first}/sass/${innerPath}`
      });
    }
  ]
}, function(err, result) {
  // ...
});

`可选` pkg导入器

pkgImporter?: NodePackageImporter

Dart Sass: 从 2.0 开始
Node Sass: ✗

如果此选项设置为 NodePackageImporter 的实例，Sass 将使用内置的 Node.js 包导入器解析具有 pkg: URL 方案的 Sass 文件。库作者和用户可以查看 NodePackageImporter 文档获取详细信息。

示例

sass.renderSync({
  data: '@use "pkg:vuetify";',
  pkgImporter: new sass.NodePackageImporter()
});

消息

`可选` 致命弃用

fatalDeprecations?: (DeprecationOrId | Version)[]

一组被视为致命的弃用。

如果在编译过程中遇到任何提供的类型的弃用警告，编译器将出错。

如果提供了 Version，则该编译器版本中所有处于活动状态的弃用都将被视为致命。

兼容性

dart: "1.78.0", node: false

`可选` 未来弃用

futureDeprecations?: DeprecationOrId[]

一组要提前选择的未来弃用。

在此传递的未来弃用将被编译器视为活动状态，并根据需要发出警告。

兼容性

dart: "1.78.0", node: false

`可选` 记录器

logger?: Logger

Dart Sass: 从 1.43.0 开始
Node Sass: ✗

用于处理 Sass 的警告和/或调试消息的对象。

默认情况下，Sass 将警告和调试消息输出到标准错误，但如果 warn 或 debug 被设置，则将改为调用它们。

特殊值 silent 可用于轻松地静默所有消息。

`可选` 静默依赖项

quietDeps?: boolean

Dart Sass: 从 1.35.0 开始
Node Sass: ✗

如果此选项设置为 true，Sass 将不会打印由依赖项引起的警告。 “依赖项”定义为通过 includePaths 或 importer 加载的任何文件。相对于入口点导入的样式表不被视为依赖项。

这对于静默你无法自行修复的弃用警告很有用。但是，请也通知你的依赖项有关弃用情况，以便他们能够尽快进行修复！

⚠️ 注意！

如果 render 或 renderSync 在没有 file 或 file 的情况下被调用，所有它加载的样式表都将被视为依赖项。由于它本身没有路径，所以它加载的所有内容都来自加载路径而不是相对导入。

默认值

false

`可选` silenceDeprecations

silenceDeprecations?: DeprecationOrId[]

一组要忽略的活动弃用。

如果在编译过程中遇到任何提供的类型的弃用警告，编译器将忽略它。

⚠️ 注意！

你所依赖的弃用功能最终会失效。

兼容性

dart: "1.78.0", node: false

`可选` verbose

verbose?: boolean

Dart Sass: 从 1.35.0 开始
Node Sass: ✗

默认情况下，Dart Sass 每次编译只会打印相同弃用警告的五个实例，以避免在控制台中出现大量噪音。如果你将 verbose 设置为 true，它将改为打印它遇到的每个弃用警告。

默认值

false

源映射

`可选` omitSourceMapUrl

omitSourceMapUrl?: boolean

如果为 true，Sass 不会从生成的 CSS 中添加指向源映射的链接。

const result = sass.renderSync({
  file: "style.scss",
  sourceMap: "out.map",
  omitSourceMapUrl: true
})
console.log(result.css.toString());
// h1 {
//   font-size: 40px;
// }

默认值

false

`可选` outFile

outFile?: string

Sass 期望生成的 CSS 保存到的位置。它用于确定从生成的 CSS 到源映射的链接URL，以及从源映射到 Sass 源文件。

⚠️ 注意！

尽管名字如此，Sass 不会将 CSS 输出写入此文件。调用者必须自行完成。

result = sass.renderSync({
  file: "style.scss",
  sourceMap: true,
  outFile: "out.css"
})
console.log(result.css.toString());
// h1 {
//   font-size: 40px;
// }
// /*# sourceMappingURL=out.css.map * /

`可选` sourceMap

sourceMap?: string | boolean

Sass 是否应该生成源映射。如果它确实生成了，源映射将作为 map 提供（除非 sourceMapEmbed 为 true）。

如果此选项是一个字符串，那么它就是源映射应该写入的路径，该路径用于从生成的 CSS 中链接到源映射，以及从源映射链接到 Sass 源文件。请注意，如果 sourceMap 是一个字符串，并且没有传递 outFile，Sass 假设 CSS 将被写入与文件选项相同的目录，如果它被传递。

如果此选项为 true，则路径被假定为 outFile，并在其末尾添加 .map。如果它为 true 且未传递 outFile，则它不会生效。

示例

let result = sass.renderSync({
  file: "style.scss",
  sourceMap: "out.map"
})
console.log(result.css.toString());
// h1 {
//   font-size: 40px;
// }
// /*# sourceMappingURL=out.map * /

result = sass.renderSync({
  file: "style.scss",
  sourceMap: true,
  outFile: "out.css"
})
console.log(result.css.toString());
// h1 {
//   font-size: 40px;
// }
// /*# sourceMappingURL=out.css.map * /

默认值

false

`可选` sourceMapContents

sourceMapContents?: boolean

是否在源映射中嵌入生成 CSS 的 Sass 文件的完整内容。这可能会生成非常大的源映射，但它保证了无论 CSS 如何被提供，源代码都将在任何计算机上可用。

示例

sass.renderSync({
  file: "style.scss",
  sourceMap: "out.map",
  sourceMapContents: true
})

默认值

false

`可选` sourceMapEmbed

sourceMapEmbed?: boolean

是否将源映射文件的内容嵌入生成的 CSS 中，而不是创建一个单独的文件并从 CSS 中链接到它。

示例

sass.renderSync({
  file: "style.scss",
  sourceMap: "out.map",
  sourceMapEmbed: true
});

默认值

false

`可选` sourceMapRoot

sourceMapRoot?: string

如果传递此参数，它将被追加到从源映射到 Sass 源文件的所有链接之前。

已弃用

类型参数

sync extends "sync" | "async"

层次结构

索引

输入

输出

插件

消息

源映射

输入

可选 includePaths

输出

可选 charset

可选 indentType

默认值

可选 indentWidth

默认值

可选 换行符

默认值

可选 输出样式

示例

插件

可选 函数

⚠️ 注意！

示例

类型声明

[key: string]: LegacyFunction<sync>

可选 导入器

示例

可选 pkg导入器

示例

消息

可选 致命弃用

兼容性

可选 未来弃用

兼容性

可选 记录器

可选 静默依赖项

⚠️ 注意！

默认值

可选 silenceDeprecations

⚠️ 注意！

兼容性

可选 verbose

默认值

源映射

可选 omitSourceMapUrl

默认值

可选 outFile

⚠️ 注意！

可选 sourceMap

示例

默认值

可选 sourceMapContents

示例

默认值

可选 sourceMapEmbed

示例

默认值

可选 sourceMapRoot

`可选` includePaths

`可选` charset

`可选` indentType

`可选` indentWidth

`可选` 换行符

`可选` 输出样式

`可选` 函数

`可选` 导入器

`可选` pkg导入器

`可选` 致命弃用

`可选` 未来弃用

`可选` 记录器

`可选` 静默依赖项

`可选` silenceDeprecations

`可选` verbose

`可选` omitSourceMapUrl

`可选` outFile

`可选` sourceMap

`可选` sourceMapContents

`可选` sourceMapEmbed

`可选` sourceMapRoot