JavaScript API

只需对模块进行 require，然后使用给定的 Stylus 代码字符串和（可选）options 对象调用 render()。

¥Simply require the module, and call render() with the given string of Stylus code, and (optional) options object.

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

¥Frameworks utilizing Stylus should pass the filename option to provide better error reporting.

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.render(str, { filename: 'nesting.css' }, function(err, css){
  if (err) throw err;
  console.log(css);
});

我们还可以以更渐进的方式做同样的事情：

¥We can also do the same thing in a more progressive manner:

var stylus = require('stylus');

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

var stylus = require('stylus');

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

.set(setting, value)

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

¥Apply a setting such as a filename, or import paths:

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

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

.include(path)

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

¥A progressive alternative to .set('paths',...) is .include(). This is ideal when exposing external Stylus libraries which expose a path.

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

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

.import(path)

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

¥Defer importing of the given path until evaluation is performed. The example below is essentially the same as doing @import 'mixins/vendor' within your Stylus sheet.

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

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，提供图片生成。

¥By passing a Node, we may define a global variable. This is useful when exposing conditional features within your library depending on the availability of another. For example the Nib extension library conditionally supports node-canvas, providing image generation.

然而，这并不总是可用，因此 Nib 可以定义：

¥However, this is not always available, so Nib may define:

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

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

如果可能，Stylus 还会将 JavaScript 值转换为其 Stylus 等效项。这里有一些例子：

¥Stylus also casts JavaScript values to their Stylus equivalents when possible. Here are a few examples:

.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'])

.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 对象变量将强制转换为类似元组数组的表达式。例如，{ foo: 'bar', bar: 'baz' } 将变成表达式 (foo 'bar') (bar 'baz')。如果你想获得哈希对象返回，请将 raw 设置为 true。

¥Note: In default, The JavaScript object variable will coerce to a tuple-array-like expression. For example { foo: 'bar', bar: 'baz' } would become the expression (foo 'bar') (bar 'baz'). If you want to get a hash object return, please set raw to true.

这些相同的规则也适用于 js 函数中的返回值：

¥These same rules apply to return values in js functions as well:

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

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

.define(name, fn)

此方法允许你向 Stylus 提供 JavaScript 定义的函数。将它们视为 JavaScript 到 C++ 的绑定。当你无法在 Stylus 中执行某些操作时，请在 JavaScript 中定义它！

¥This method allows you to provide a JavaScript-defined function to Stylus. Think of these as you would JavaScript-to-C++ bindings. When there's something you cannot do in Stylus, define it in JavaScript!

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

¥In this example, we define four functions: add(), sub(), image-width(), and image-height(). These functions must return a Node, this constructor and the other nodes are available via 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);
  });

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

如需进一步参考（直到文档完成），请参阅以下文件：

¥For further reference (until documentation is complete) please see the following files:

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

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

.use(fn)

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

¥When called, the given fn is invoked with the renderer, allowing all of the methods above to be used. This allows for plugins to easily expose themselves, defining functions, paths etc.

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

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

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

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

当使用选项调用 render() 方法时，可以为 use 选项提供要通过渲染器调用的函数或函数数组。

¥When calling the render() method with options, the use option can be given a function or array of functions to be invoked with the renderer.

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

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

.deps()

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

¥Returns array of dependencies (import files):

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

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

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

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

另见 --deps CLI 标志。

¥See also --deps CLI flag.

stylus.resolver([options])

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

¥Optional built-in function which may be used to resolve relative urls inside imported files:

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

  });

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

  });

另见 --resolve-url CLI 标志。

¥See also --resolve-url CLI flag.

选项：

¥Options:

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

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

JavaScript API #

.set(setting, value) #

.include(path) #

.import(path) #

.define(name, node[, raw]) #

.define(name, fn) #

.use(fn) #

.deps() #

stylus.resolver([options]) #