JavaScript API

简单地使用 require 模块，并使用给定的 Stylus 代码字符串和（可选的）options 对象调用 render()。

使用 Stylus 的框架应该传递 filename 选项以提供更好的错误报告。

var stylus = require("stylus");

stylus.render(str, { filename: "nesting.css" }, function (err, css) {
  if (err) throw err;
  console.log(css);
});

我们也可以以更渐进的方式完成相同的事情：

var stylus = require("stylus");

stylus(str)
  .set("filename", "nesting.css")
  .render(function (err, css) {
    // logic
  });

.set(setting, value)

应用设置，例如 filename 或导入 paths：

.set('filename', __dirname + '/test.styl')
.set('paths', [__dirname, __dirname + '/mixins'])

.include(path)

.include() 是 .set('paths',...) 的渐进式替代方案。当暴露外部 Stylus 库并公开路径时，这是理想的选择。

stylus(str)
  .include(require('nib').path)
  .include(process.env.HOME + '/mixins')
  .render(...)

.import(path)

延迟导入给定的 path 直到执行评估。下面的示例本质上与在您的 Stylus 表格中执行 @import 'mixins/vendor' 相同。

var stylus = require("../"),
  str = require("fs").readFileSync(__dirname + "/test.styl", "utf8");

stylus(str)
  .set("filename", __dirname + "/test.styl")
  .import("mixins/vendor")
  .render(function (err, css) {
    if (err) throw err;
    console.log(css);
  });

.define(name, node[, raw])

通过传递一个 Node，我们可以定义一个全局变量。当根据另一个可用性公开条件功能时，这对于在库中使用非常有用。例如，Nib 扩展库有条件地支持 node-canvas，提供图像生成。

但是，这并不总是可用的，因此 Nib 可能会定义：

.define('has-canvas', stylus.nodes.false);
.define('some-setting', new stylus.nodes.String('some value'));

当可能时，Stylus 还将 JavaScript 值转换为其 Stylus 等效项。以下是一些示例：

.define('string', 'some string')
.define('number', 15.5)
.define('some-bool', true)
.define('list', [1,2,3])
.define('list', [1,2,[3,4,[5,6]]])
.define('list', { foo: 'bar', bar: 'baz' })
.define('families', ['Helvetica Neue', 'Helvetica', 'sans-serif'])

注意：默认情况下，JavaScript 对象变量将强制转换为元组-a。

数组式表达式。例如 { foo: 'bar', bar: 'baz' } 将变成表达式 (foo 'bar') (bar 'baz')。如果你想要返回一个 哈希对象，请将 raw 设置为 true。

同样的规则也适用于 JavaScript 函数的返回值：

.define('get-list', function(){
  return ['foo', 'bar', 'baz'];
})

.define(name, fn)

这个方法允许你提供一个在 JavaScript 中定义的函数给 Stylus 使用。可以将其视为 JavaScript 到 C++ 的绑定。当你在 Stylus 中无法完成某些操作时，可以在 JavaScript 中定义它！

在这个例子中，我们定义了四个函数：add()、sub()、image-width() 和 image-height()。这些函数必须返回一个 Node，这个构造函数和其他节点可以通过 stylus.nodes 访问。

var stylus = require("../"),
  nodes = stylus.nodes,
  utils = stylus.utils,
  fs = require("fs");

function add(a, b) {
  return a.operate("+", b);
}

function sub(a, b) {
  return a.operate("-", b);
}

function imageDimensions(img) {
  // assert that the node (img) is a String node, passing
  // the param name for error reporting
  utils.assertType(img, "string", "img");
  var path = img.val;

  // Grab bytes necessary to retrieve dimensions.
  // if this was real you would do this per format,
  // instead of reading the entire image :)
  var data = fs.readFileSync(__dirname + "/" + path);

  // GIF
  // of course you would support.. more :)
  if ("GIF" == data.slice(0, 3).toString()) {
    var w = data.slice(6, 8),
      h = data.slice(8, 10);
    w = (w[1] << 8) | w[0];
    h = (h[1] << 8) | h[0];
  }

  return [w, h];
}

function imageWidth(img) {
  return new nodes.Unit(imageDimensions(img)[0]);
}

function imageHeight(img) {
  return new nodes.Unit(imageDimensions(img)[1]);
}

stylus(str)
  .set("filename", "js-functions.styl")
  .define("add", add)
  .define("sub", sub)
  .define("image-width", imageWidth)
  .define("image-height", imageHeight)
  .render(function (err, css) {
    if (err) throw err;
    console.log(css);
  });

更多参考资料（直到文档完整为止）请参见以下文件：

- `lib/nodes/*`
- `lib/utils.js`

.use(fn)

调用时，给定的 fn 将使用渲染器调用，允许使用上面的所有方法。这使得插件可以轻松地暴露自己，定义函数、路径等等。

var mylib = function(style){
  style.define('add', add);
  style.define('sub', sub);
};

stylus(str)
  .use(mylib)
  .render(...)

当使用带有选项的 render() 方法时，可以将 use 选项赋予一个函数或函数数组，以便与渲染器一起调用。

stylus.render(str, { use: mylib }, function(err, css){
  if (err) throw err;
  console.log(css);
});

.deps()

返回依赖项（导入文件）的数组：

stylus('@import "a"; @import "b"')
  .deps();

// => ['a.styl', 'b.styl']

另请参见 --deps CLI 标志。

stylus.resolver([options])

可选的内置函数，可用于解析导入文件中的相对 URL：

stylus(str)
  .define('url', stylus.resolver())
  .render(function(err, css) {

  });

另请参见 --resolve-url CLI 标志。

选项：

- `paths` additional resolution path(s)
- `nocheck` don't check file existence