JavaScript API

两种主要的Sass实现都支持相同的JavaScript API。Dart Sass作为纯JavaScript sass软件包分发，而LibSass作为该node-sass软件包的本机扩展分发。

用法永久链接用法

Sass模块提供了两个具有相似API的功能。

renderSync（）永久链接`renderSync()`

此函数将Sass文件同步编译为CSS。如果成功，则返回结果，如果失败，则抛出错误。它带有一个options对象，该对象必须具有fileoption或dataoption 集。

var sass = require('sass'); // or require('node-sass');

var result = sass.renderSync({file: "style.scss"});
// ...

render（）永久链接`render()`

Dart·Sass（Dart Sass）: ✓
节点Sass: 从 3.0.0开始

此函数将Sass文件异步编译为CSS，并在渲染完成时调用标准Node回调，并返回结果或错误。它带有一个options对象，该对象必须具有fileoption或dataoption 集。

Head️抬头！

使用Dart Sass时，由于使整个评估过程异步的开销，renderSync()几乎render()是默认速度的两倍。为避免这种性能下降，您可以将fiber选项传递给 render()。

var sass = require('sass'); // or require('node-sass');

sass.render({
  file: "style.scss"
}, function(err, result) {
  // ...
});

信息永久链接`info`

Dart·Sass（Dart Sass）: ✓
节点Sass: 从 2.0.0开始

该info属性包含一个字符串，其中包含有关Sass实现的制表符分隔的信息。对于Dart Sass，这是Dart Sass的版本，是用于将其编译为JavaScript 的dart2js编译器的版本；对于LibSass，它是LibSass的版本和包装它的Node Sass的版本。

console.log(sass.info);
// dart-sass    1.26.8  (Sass Compiler) [Dart]
// dart2js  2.0.0   (Dart Compiler) [Dart]

结果对象永久链接结果对象

当renderSync()或render()成功，他们提供了一个包含编译信息的结果对象。该对象具有以下属性：

result.css永久链接`result.css`

编译后的CSS，作为Buffer。可以通过调用将其转换为字符串Buffer.toString()。

var result = sass.renderSync({file: "style.scss"});

console.log(result.css.toString());

result.map永久链接`result.map`

源映射，用于将已编译的CSS映射到作为Buffer生成源代码的源文件。可以通过调用将其转换为字符串Buffer.toString()。

这是null或undefined除非

该sourceMap选项是一个字符串；要么
该sourceMap选项是true 并且该outFile选项已设置。

源映射使用绝对file:URL链接到Sass源文件，除非源文件来自该data选项，在这种情况下，源文件将其URL列出为 stdin。

var result = sass.renderSync({
  file: "style.scss",
  sourceMap: true,
  outFile: "style.css"
})

console.log(result.map.toString());

result.stats.includedFiles永久链接`result.stats.includedFiles`

编译期间加载的所有Sass文件的绝对路径的数组。如果样式表是从一个加载进口商返回的样式表的内容，的原始字符串@use或@import该加载的样式表被包括此数组英寸

result.stats.entry永久链接`result.stats.entry`

输入的文件的绝对路径作为fileoption传递，或者 "data"是否传递了dataoption。

result.stats.start永久链接`result.stats.start`

毫秒的1970年1月1日之间在00:00:00的数量UTC和其Sass编译开始的时间。

result.stats.end永久链接`result.stats.end`

从1970年1月1日UTC到Sass编译结束的时间之间的毫秒数。

result.stats.duration永久链接`result.stats.duration`

编译Sass文件所花费的毫秒数。这始终等于result.stats.start减result.stats.end。

错误对象永久链接错误对象

如果renderSync()还是render()失败，他们提供了一个Error对象，其中包含有关编译的信息。除标准Error 属性外，此对象还具有以下属性：

错误格式的固定链接`error.formatted`

错误的字符串表示形式。在Node Sass中，这比error.toString()或更详细error.message。在Dart Sass中，它提供了相同的信息。

error.file永久链接`error.file`

发生错误的样式表。如果错误发生在从磁盘加载的样式表中，则这是该样式表的绝对路径。如果错误发生在从导入器加载的样式表中，该进口商返回了样式表的内容，则这是@use或@import 加载该样式表的原始字符串。如果它出现在data选项的内容中，则为字符串 "stdin"。

error.line永久链接`error.line`

error.file发生错误的行。

error.column永久链接`error.column`

发生错误的error.linein 的列error.file。

error.status永久链接`error.status`

如果此错误导致封闭程序退出，应使用的退出状态。

选项永久链接选项

输入固定链接输入

这些选项控制Sass如何加载它的输入文件。

文件永久链接`file`

Dart·Sass（Dart Sass）: 从 1.11.0开始
节点Sass: 部分的

Node Sass和较旧版本的Dart Sass支持加载扩展名为的文件.css，但与规范相反，它们被视为SCSS文件，而不是被解析为CSS。此行为已在Node Sass中弃用，并且正在进行更新以将其加载为纯CSS 。

所有版本的Node Sass和Dart Sass均支持以下file选项。

此字符串选项是Sass加载和编译的文件的路径。如果文件的扩展名是.scss，它将被解析为SCSS。如果是.sass，它将被解析为缩进语法；如果是.css，它将被解析为纯CSS。如果没有扩展名，它将被解析为 SCSS。

如果同时传递了file选项和data选项，则该 file选项将用作错误报告的样式表的路径，但该 data选项将用作样式表的内容。在这种情况下， file选项的扩展名不用于确定样式表的语法。

sass.renderSync({file: "style.scss"});

数据永久链接`data`

此字符串选项提供要编译的样式表的内容。除非也传递了该file选项，否则样式表的URL将设置为"stdin"。

默认情况下，此样式表被解析为SCSS。可以使用indentedSyntaxoption进行控制。

sass.renderSync({
  data: `
h1 {
  font-size: 40px;
}`
});

缩进语法永久链接`indentedSyntax`

此标志控制是否将data选项解析为缩进语法。默认为false。它对使用fileoption加载的样式表没有影响。

sass.renderSync({
  data: `
h1
  font-size: 40px`,
  indentedSyntax: true
});

includePaths永久链接`includePaths`

Dart·Sass（Dart Sass）: 从 1.15.0开始
节点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

输出固定链接输出

这些选项控制Sass如何生成输出文件。

outputStyle永久链接`outputStyle`

此字符串选项控制所得CSS的输出样式。有四种可能的输出样式：

"expanded" （Dart Sass的默认设置）将每个选择器和声明写在自己的行上。
"compressed" 删除尽可能多的多余字符，并将整个样式表写在一行上。
"nested"（Node Sass的默认设置，Dart Sass不支持）缩进 CSS规则以匹配Sass源的嵌套。
compact（不受Dart Sass支持），将每个CSS规则放在自己的一行上。

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

var 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; }

精密固定链接`precision`

Dart·Sass（Dart Sass）: ✗
节点Sass: ✓

由于性能原因，Dart Sass不允许自定义精度。它始终支持10位数字精度。

此整数选项确定生成包含数字的CSS时将使用的精度。Node Sass的默认值为5。

var result = sass.renderSync({
  data: `
h1 {
  font-size: (100px / 3);
}`,
  precision: 20
});

console.log(result.css.toString());
// h1 {
//  font-size: 33.333333333333336px; }

indentType永久链接`indentType`

Dart·Sass（Dart Sass）: ✓
节点Sass: 从 3.0.0开始

此字符串选项确定生成的CSS是否应使用空格（带有值"space"）或制表符（带有值"tab"）进行缩进。默认为 "space"。

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

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

indentWidth永久链接`indentWidth`

Dart·Sass（Dart Sass）: ✓
节点Sass: 从 3.0.0开始

此整数选项控制在生成的CSS中每个缩进级别应使用多少空格或制表符（取决于indentTypeoption）。它的默认值为2，并且必须介于0到10（含）之间。

var result = sass.renderSync({
  file: "style.scss",
  indentWidth: 4
});

console.log(result.css.toString());
// h1 {
//    font-size: 40px;
// }

换行永久链接`linefeed`

Dart·Sass（Dart Sass）: ✓
节点Sass: 从 3.0.0开始

此字符串选项控制在生成的CSS中每一行的末尾使用什么字符序列。它可以具有以下值：

lf（默认）使用U + 000A LINE FEED。
lfcr采用U + 000A LINE FEED其次U + 000D CARRIAGE RETURN。
cr（默认）使用U + 000D CARRIAGE RETURN。
crlf使用U + 000D CARRIAGE RETURN其次U + 000A LINE FEED。

var result = sass.renderSync({
  file: "style.scss",
  linefeed: "crlf"
});

console.log(result.css.toString());
// "h1 {\r\n  font-size: 40px;\r\n}\r\n"

sourceComments永久链接`sourceComments`

Dart·Sass（Dart Sass）: ✗
节点Sass: ✓

Dart Sass不支持此选项，因为建议将源映射作为确定样式规则定义位置的最佳方法。

此标志使Sass为每个样式规则发出注释，以指示每个样式规则在源样式表中的定义位置。默认为 false。

var result = sass.renderSync({
  file: "style.scss",
  sourceComments: true
});

console.log(result.css.toString());
// /* line 1, style.scss */
// h1 {
//   font-size: 40px;
// }

源地图永久链接源地图

源映射是告诉浏览器或使用CSS的其他工具的文件，该CSS 如何与生成CSS的Sass文件相对应。它们使您可以在浏览器中查看甚至编辑您的Sass文件。请参阅有关在Chrome和Firefox中使用源地图的说明。

Sass JS API使用该result.map字段可以使用源地图。

sourceMap固定链接`sourceMap`

该标志控制是否生成源映射。

如果此选项是字符串，则它是源映射预期被写入的路径，该路径用于从生成的CSS链接到源映射，以及从源映射链接到Sass源文件。请注意，如果sourceMap选项是字符串并且未传递outFile选项，则Sass假定如果传递了CSS，则CSS将与file选项写入同一目录。

如果此选项为true，则假定路径是添加到末尾的outFile选项.map。如果通过且未通过true该outFile选项，则它无效。

var 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 */

outFile永久链接`outFile`

该字符串选项是Sass希望将生成的CSS保存到的位置。它用于确定用于从生成的CSS链接到源映射以及从源映射链接到Sass源文件的URL。

Head️抬头！

尽管名字，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 */

omitSourceMapUrl永久链接`omitSourceMapUrl`

此标志使Sass不能从生成的CSS链接到源映射。

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

sourceMapContents永久链接`sourceMapContents`

该标志告诉Sass将有助于生成的CSS的Sass文件的全部内容嵌入到源映射中。这可能会产生非常大的源映射，但是无论源如何提供CSS，它都保证该源将可在任何计算机上使用。

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

嵌入的永久链接`sourceMapEmbed`

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

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

sourceMapRoot永久链接`sourceMapRoot`

此字符串选项位于从源映射到Sass源文件的所有链接之前。

插件永久链接插件

这些选项使用JavaScript回调来扩展Sass编译的功能。

光纤永久链接`fiber`

使用Dart Sass时，由于异步回调的开销，renderSync()其速度是的两倍以上render()。为了避免这种性能下降，render()可以使用该fibers程序包从同步代码路径中调用异步导入程序。要启用此功能，请将Fiber类传递给fiber 选项：

var sass = require("sass");
var Fiber = require("fibers");

sass.render({
  file: "input.scss",
  importer: function(url, prev, done) {
    // ...
  },
  fiber: Fiber
}, function(err, result) {
  // ...
});

使用Node Sass或使用该renderSync() 功能时，此选项是允许的，但无效。

功能永久链接`functions`

此选项定义所有样式表中都可用的其他内置Sass函数。这是一个对象，其键是Sass函数签名，其值是JavaScript函数。每个函数应采用与其签名相同的参数。如果签名采用任意参数，则JavaScript函数应采用单个参数。

函数是通过Sass值类型的 JavaScript表示形式传递的，并且必须返回相同的值。所有函数都可以同步返回，但是传递给异步render()函数的函数也可以接受附加的回调，它们可以在函数完成后异步传递函数的结果。

如果函数同步引发错误，则会将该错误报告给函数的调用者，并且样式表编译将失败。当前无法异步报告错误。

Head️抬头！

在编写自定义函数时，重要的是确保所有参数都是您期望的类型。否则，用户的样式表可能会以难以调试的方式崩溃，或者更糟的是编译为毫无意义的 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;
  // }
});

进口商永久链接`importer`

Dart·Sass（Dart Sass）: ✓
节点Sass: 从 3.0.0开始

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

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

Dart·Sass（Dart Sass）: 从 1.20.2开始
节点Sass: ✗

在1.20.2之前的Dart Sass版本中，首选使用加载路径（includePaths）解析导入，然后使用自定义导入器解析导入。

当前，Node Sass的所有版本都将导入传递给进口商，然后再相对于出现的文件加载它们@import。这种行为被认为是不正确的，因此不应该依靠，因为它违反了局部性原则，即说应该有可能对样式表进行推理，而不必了解整个系统的所有设置。如果用户尝试导入相对于另一个样式表的样式表，则该导入应始终有效。某些其他地方的配置不可能破坏它。

此选项定义加载文件的一个或多个额外的处理程序时，一个@use规则或@import规则遇到。它可以是单个JavaScript函数，也可以是函数数组。这些函数总是传递两个参数：

的@use或@import规则的URL作为一个字符串，正是因为它出现在样式表。
一个字符串，用于标识包含@use 或的样式表@import。该标识符的格式取决于该样式表的加载方式：
- 如果样式表是从文件系统加载的，则是其文件的绝对路径。
- 如果样式表是从返回其内容的导入器加载的，则是加载该样式表的or 的URL。@use@import
- 如果样式表来自该data选项，则为字符串"stdin"。

进口商必须返回以下类型之一：

具有键的对象，contents其值是样式表的内容（使用SCSS语法）。这将导致Sass加载该样式表的内容。
具有键的对象，file其值是磁盘上的路径。这将导致Sass像直接导入文件一样加载该文件。
null，表示无法识别该网址，应尝试使用另一个导入器。
一个Errorobject，指示导入失败。

所有的导入程序都可以同步返回，但是传递给异步render()函数的导入程序也可以接受附加的回调，一旦完成导入，它们可以异步地将导入结果传递给该回调函数。

尝试按以下顺序解决导入问题：

相对于@use或@import 出现的文件加载文件。
每个自定义进口商。
相对于当前工作目录加载文件。
includePaths中的每个加载路径
在SASS_PATH环境变量中指定的每个加载路径，在Windows上应该用分号分隔，在其他位置则用冒号分隔。

sass.render({
  file: "style.scss",
  importer: [
    // This importer uses the synchronous API, and can be passed to either

JavaScript API

用法永久链接用法

renderSync（）永久链接renderSync()

render（）永久链接render()

Head️抬头！

信息永久链接info

结果对象永久链接结果对象

result.css永久链接result.css

result.map永久链接result.map

result.stats.includedFiles永久链接result.stats.includedFiles

result.stats.entry永久链接result.stats.entry

result.stats.start永久链接result.stats.start

result.stats.end永久链接result.stats.end

result.stats.duration永久链接result.stats.duration

错误对象永久链接错误对象

错误格式的固定链接error.formatted

error.file永久链接error.file

error.line永久链接error.line

error.column永久链接error.column

error.status永久链接error.status

选项永久链接选项

输入固定链接输入

文件永久链接file

数据永久链接data

缩进语法永久链接indentedSyntax

includePaths永久链接includePaths

输出固定链接输出

outputStyle永久链接outputStyle

精密固定链接precision

indentType永久链接indentType

indentWidth永久链接indentWidth

换行永久链接linefeed

sourceComments永久链接sourceComments

源地图永久链接源地图

sourceMap固定链接sourceMap

outFile永久链接outFile

Head️抬头！

omitSourceMapUrl永久链接omitSourceMapUrl

sourceMapContents永久链接sourceMapContents

嵌入的永久链接sourceMapEmbed

sourceMapRoot永久链接sourceMapRoot

插件永久链接插件

光纤永久链接fiber

功能永久链接functions

Head️抬头！

进口商永久链接importer

renderSync（）永久链接`renderSync()`

render（）永久链接`render()`

信息永久链接`info`

result.css永久链接`result.css`

result.map永久链接`result.map`

result.stats.includedFiles永久链接`result.stats.includedFiles`

result.stats.entry永久链接`result.stats.entry`

result.stats.start永久链接`result.stats.start`

result.stats.end永久链接`result.stats.end`

result.stats.duration永久链接`result.stats.duration`

错误格式的固定链接`error.formatted`

error.file永久链接`error.file`

error.line永久链接`error.line`

error.column永久链接`error.column`

error.status永久链接`error.status`

文件永久链接`file`

数据永久链接`data`

缩进语法永久链接`indentedSyntax`

includePaths永久链接`includePaths`

outputStyle永久链接`outputStyle`

精密固定链接`precision`

indentType永久链接`indentType`

indentWidth永久链接`indentWidth`

换行永久链接`linefeed`

sourceComments永久链接`sourceComments`

sourceMap固定链接`sourceMap`

outFile永久链接`outFile`

omitSourceMapUrl永久链接`omitSourceMapUrl`

sourceMapContents永久链接`sourceMapContents`

嵌入的永久链接`sourceMapEmbed`

sourceMapRoot永久链接`sourceMapRoot`

光纤永久链接`fiber`

功能永久链接`functions`

进口商永久链接`importer`