API 参考(API Reference)

¥API Reference

本页详细介绍了如何使用 JavaScript API 渲染 Pug。

¥This page details how to render Pug using the JavaScript API.

pug.render('p Hello world!');

选项(Options) ¶

¥Options

所有 API 方法都接受以下选项集：

¥All API methods accept the following set of options:

filename: string

The name of the file being compiled. Used in exceptions, and required for relative include\s and extend\s. Defaults to 'Pug'.

basedir: string

The root directory of all absolute inclusion.

doctype: string

If the doctype is not specified as part of the template, you can specify it here. It is sometimes useful to get self-closing tags and remove mirroring of boolean attributes. See doctype documentation for more information.

pretty: boolean | string

[Deprecated.] Adds whitespace to the resulting HTML to make it easier for a human to read using '  ' as indentation. If a string is specified, that will be used as indentation instead (e.g. '\t'). We strongly recommend against using this option. Too often, it creates subtle bugs in your templates because of the way it alters the interpretation and rendering of whitespace, and so this feature is going to be removed. Defaults to false.

filters: object

Hash table of custom filters. Defaults to undefined.

self: boolean

Use a self namespace to hold the locals. It will speed up the compilation, but instead of writing variable you will have to write self.variable to access a property of the locals object. Defaults to false.

debug: boolean

If set to true, the tokens and function body are logged to stdout.

compileDebug: boolean

If set to true, the function source will be included in the compiled template for better error messages (sometimes useful in development). It is enabled by default, unless used with Express in production mode.

globals: Array<string>

Add a list of global names to make accessible in templates.

cache: boolean

If set to true, compiled functions are cached. filename must be set as the cache key. Only applies to render functions. Defaults to false.

inlineRuntimeFunctions: boolean

Inline runtime functions instead of require-ing them from a shared version. For compileClient functions, the default is true (so that one does not have to include the runtime). For all other compilation or rendering types, the default is false.

name: string

The name of the template function. Only applies to compileClient functions. Defaults to 'template'.

方法(Methods) ¶

¥Methods

pug.compile(source, ?options)(pug.compile(source, ?options)) ¶

将 Pug 模板编译为函数，该函数可以使用不同的局部变量多次渲染。

¥Compile a Pug template to a function, which can be rendered multiple times with different locals.

source: string

The source Pug template to compile

options: ?options

An options object

returns: function

A function to generate the HTML from an object containing locals

var pug = require('pug');

// Compile a function
var fn = pug.compile('string of pug', options);

// Render the function
var html = fn(locals);
// => '<string>of pug</string>'

pug.compileFile(path, ?options)(pug.compileFile(path, ?options)) ¶

将 Pug 模板从文件编译为函数，该函数可以使用不同的局部变量多次渲染。

¥Compile a Pug template from a file to a function, which can be rendered multiple times with different locals.

path: string

The path to a Pug file

options: ?options

An options object

returns: function

A function to generate the HTML from an object containing locals

var pug = require('pug');

// Compile a function
var fn = pug.compileFile('path to pug file', options);

// Render the function
var html = fn(locals);
// => '<string>of pug</string>'

pug.compileClient(source, ?options)(pug.compileClient(source, ?options)) ¶

将 Pug 模板编译为 JavaScript 字符串，可以在客户端使用。

¥Compile a Pug template to a string of JavaScript, which can be used client side.

source: string

The Pug template to compile

options: ?options

An options object

returns: string

A string of JavaScript representing a function

var pug = require('pug');

// Compile a function
var fn = pug.compileClient('string of pug', options);

// Render the function
var html = fn(locals);
// => 'function template(locals) { return "<string>of pug</string>"; }'

pug.compileClientWithDependenciesTracked(source, ?options)(pug.compileClientWithDependenciesTracked(source, ?options)) ¶

与 compileClient 相同，但此方法返回以下形式的对象：

¥Same as compileClient, except that this method returns an object of the form:

{
  'body': 'function (locals) {...}',
  'dependencies': ['filename.pug']
}

仅当你需要 dependencies 来实现诸如监视 Pug 文件更改之类的操作时，才应使用此方法。

¥You should only use this method if you need dependencies to implement something like watching for changes to the Pug files.

pug.compileFileClient(path, ?options)(pug.compileFileClient(path, ?options)) ¶

将 Pug 模板文件编译为可在客户端使用的 JavaScript 字符串。

¥Compile a Pug template file to a string of JavaScript that can be used client side.

path: string

The path to a Pug file

options: ?options

An options object

options.name: string

If you pass a .name property on the options object, it will be used as the name of your client side template function.

returns: string

A JavaScript function body.

首先，我们的模板文件。

¥First, our template file.

h1 This is a Pug template
h2 By #{author}

然后，我们将 Pug 文件编译成函数字符串。

¥Then, we compile the Pug file into a function string.

var fs = require('fs');
var pug = require('pug');

// Compile the template to a function string
var jsFunctionString = pug.compileFileClient('/path/to/pugFile.pug', {name: "fancyTemplateFun"});

// Maybe you want to compile all of your templates to a templates.js file and serve it to the client
fs.writeFileSync("templates.js", jsFunctionString);

这是输出函数字符串的样子（写入 templates.js）。

¥Here’s what the output function string looks like (written to templates.js).

function fancyTemplateFun(locals) {
  var buf = [];
  var pug_mixins = {};
  var pug_interp;

  var locals_for_with = (locals || {});

  (function (author) {
    buf.push("<h1>This is a Pug template</h1><h2>By "
      + (pug.escape((pug_interp = author) == null ? '' : pug_interp))
      + "</h2>");
  }.call(this, "author" in locals_for_with ?
    locals_for_with.author : typeof author !== "undefined" ?
      author : undefined)
  );

  return buf.join("");
}

<!DOCTYPE html>
<html>
  <head>
    <script src="/templates.js"></script>
  </head>

  <body>
    <h1>This is one fancy template.</h1>

    <script type="text/javascript">
      var html = window.fancyTemplateFun({author: "enlore"});
      var div = document.createElement("div");
      div.innerHTML = html;
      document.body.appendChild(div);
    </script>
  </body>
</html>

pug.render(source, ?options, ?callback)(pug.render(source, ?options, ?callback)) ¶

source: string

The source Pug template to render

options: ?options

An options object, also used as the locals object

callback: ?function

Node.js-style callback receiving the rendered results. This callback is called synchronously.

returns: string

The resulting HTML string

var pug = require('pug');

var html = pug.render('string of pug', options);
// => '<string>of pug</string>'

pug.renderFile(path, ?options, ?callback)(pug.renderFile(path, ?options, ?callback)) ¶

path: string

The path to the Pug file to render

options: ?options

An options object, also used as the locals object

callback: ?function

Node.js-style callback receiving the rendered results. This callback is called synchronously.

returns: string

The resulting HTML string

var pug = require('pug');

var html = pug.renderFile('path/to/file.pug', options);
// ...

属性(Properties) ¶

¥Properties

pug.filters(pug.filters) ¶

自定义过滤器 的哈希表。

¥A hash table of custom filters.

该对象具有与 filters 选项 相同的语义，但全局适用于所有 Pug 编译。当 pug.filters 和 options.filters 中都存在过滤器时，filters 选项优先。

¥This object has the same semantics as the filters option, but applies globally to all Pug compilation. When a filter is present in both pug.filters and options.filters, the filters option takes precedence.