Sass 的 JavaScriptAPI

1. 简介

前面我们讲解的所有内容,基本都是在使用 Sass 为我们提供的扩展功能,在使用 Sass 的语法,一般来说这些代码都是写在 .scss 为后缀的文件中的。而 Sass 还提供了一些 API 接口使得我们在 JS 中可以调用,也就是在 .js 为后缀的文件中去调用这些 API 。

这种方式在写样式中很不常用,但我们还是单独拿出一个章节来讲解它,以便你对 Sass 有一个更全面的认识。另外

2. 什么是 Sass 的 JavaScriptAPI

API 指的是应用程序接口,Sass 中提供了一系列供 javascript 调用的应用程序接口。

3. 如何使用

在两个主要的 Sass 库 node-sass 和 dart-sass 中都支持 JavaScriptAPI ,并且它们的 API 语法都是相同的,本节内容我们使用的是 node-sass 。使用的时候需要加载 Sass 并赋给一个变量,然后就可以调用 API 了,我们举例看下:

var sass = require("node-sass");
sass.render({
  file: "style.scss"
}, function(err, result) {
  // ...
});

上面的代码就是使用的方式,其实就是普通的 Javascript 语法,下面我们看下 Sass 都为我们提供了什么 API 。

4. 常用 API 举例

4.1 render() 和 renderSync()

render() 函数是将 Sass 文件异步编译为 CSS ,并在渲染完成时调用传入的回调函数,它接收一个 options 参数和一个回调函数,options 参数是一个 Object 类型,它必须有 file 或 data 选项。我们举例来看下:

var sass = require('node-sass'); 
sass.render({
  file: "style.scss"
}, function(err, result) {
  // 回调函数,在渲染完调用此函数
});

renderSync() 函数的作用与 render() 函数是相同的,唯一不同的是 renderSync() 函数是同步的,这需要你对 javascript 中的同步异步有深入的了解,所以对于同步函数,如果执行失败我们需要捕获错误并抛出,我们举例看下:

var sass = require('node-sass'); 
try {
  var result = sass.renderSync({file: "style.scss"});
} catch(e) {
  throw new Error(e.message)
}

上面我们可以看到调用 renderSync() 或者 render() 函数都会返回 result ,返回的 result 是一个 Object,它都包含什么呢?我们下面讲解下。

4.1.1 result.css

编译为 css 后的内容,是一段 Buffer ,我们可以通过调用 JS 的 toString() 方法来解析它,如下所示:

var sass = require('node-sass'); 
try {
  var result = sass.renderSync({file: "style.scss"});
  // 编译的 CSS
  console.log(result.css.toString())
} catch(e) {
  throw new Error(e.message)
}

4.1.2 result.map

这个返回的是编译后的 CSS 到源文件的一个映射,它是一个 Buffer,你可以理解为这就是一个 SourceMap

4.1.3 result 中其他的属性值

result 中还存了很多很多的属性和值,为了你能更好的了解,我下面直接列出一个表格来展示这些:

result 中的属性 返回值
result.stats.includedFiles 返回编译期间加载的所有Sass文件的绝对路径的数组
result.stats.entry 返回作为file选项传递的输入文件的绝对路径
result.stats.start 返回Sass编译开始的毫秒数
result.stats.end 返回Sass编译结束的毫秒数
result.stats.duration 返回编译 Sass 文件所用的毫秒数,也就是 result.stats.start 减 result.stats.end

4.1.4 error

renderSync() 或者 render() 函数也就返回 error ,这个 error 也是一个 Object ,同样下边我以表格的形式将 error 中的属性值列出来:

error 中的属性 返回值
error.formatted 返回字符串类型的错误消息
error.file 返回字符串类型的样式表
error.line 返回出现错误的位置
error.column 返回出现错误的列
error.status 返回出现错误程序退出时的退出状态

4.2 info

这个 API 通过字面意思我们就知道,可以用它来获取 Sass 的相关信息,包括使用的 Sass 的版本等等,我们举例看下:

var sass = require('node-sass'); 
console.log(sass.info);

这个 API 很简单,就是获取到一些版本和当前使用的 Sass 的信息,来供你处理或者做一些判断逻辑。

5. 小结

本节内容中我们列举了几个 Sass 的 JavascriptAPI ,根据下图回忆一下吧:
图片描述
这个章节的内容是为了让你更全面的认识 Sass ,在实际的业务项目中,几乎永远不会这么用。熟练的使用这些 API 还需要你拥有良好的 javascript 功底,所以当你需要使用这些 API 的时候,相信你已经是前端大牛了,开始利用这些 API 来扩展 Sass 为你所用,在本系列的入门教程中,这部分是作为了解的知识,并不是特别重要。