API 参考文档 reference

此页面将详细说明如何 JavaScript API 来对 Pug 代码进行渲染。

现在 Pug 可以在您的浏览器控制台上使用！想测试各种 Pug 的 API，您可以尝试在控制台输入：

pug.render('p Hello world!')

选项 `Options`

所有的 API 方法都可以使用以下的选项：

filename: string
要编译的代码的文件名。用于异常信息以及(使用相对路径的)包含(include)和扩展(extends)操作。默认值是 'Pug'。
basedir string
模板里所有绝对定位的根目录。
doctype string
如果 doctype 没有出现模板里(比如模板只渲染一个 HTML 片段)，那么您可以在这里指定它。在一些需要控制自闭合标签和布尔值属性的代码样式的时候非常有用。您可以阅读 doctype 的说明来了解更多细节。
pretty boolean | string
(不赞成使用)在输出的 HTML 里添加 ' ' 这样的空格缩进来获得更好的代码可读性。如果这里指定了一个字符串(比如 '\t')，那么将会使用它作为控制缩进的字符。我们强烈建议您不要使用这个选项，它改变解释器和空格渲染工作的方式会极其频繁地导致一些错误。我们将会在未来移除这个功能。默认为 false。
filters object
存放自定义过滤器的哈希表。默认为 undefined。
self boolean
是否使用一个叫做 self 的命名空间来存放局部变量。这可以加速编译的过程，但是，相对于原来书写比如 variable 来访问局部变量，您将需要改为 self.variable 来访问它们。默认为 false。
debug boolean
当设置为 true 时，编译产生的函数代码会被记录到标准输出。
compileDebug boolean
当设置为 true 时，源代码会被包含在编译出来的模板函数中，用于提供更详实的错误信息(这在开发时会有用)。它默认是启用的，除非是在 Express 的生产环境模式中。
globals Array<string>
该数组用于向模板中添加全局对象的名字，编译器将保证它们不被局部作用域影响。
cache boolean
当设置为 true 时，编译出来的函数会被缓存下来。此时必须填写 filename 选项作为缓存的索引字段。该选项仅用于 render 函数。默认为 false。
inlineRuntimeFunctions boolean
相对于使用 require 来获得公用的运行时函数，是否需要直接嵌入这些运行时函数。在 compileClient 函数里默认是 true，因此就不需要再手动包含那些函数(从而让其能在浏览器上运行)。在其他的 compile / render 系列函数中，默认是 false。
name string
模板函数的名称。仅用于 compileClient 函数。默认值是 'template'。

方法 `Methods`

pug.compile`(source, options?)`

把一个 Pug 模板编译成一个可多次使用、可传入不同局部变量渲染的函数。

source string
需要编译的 Pug 代码
options ?options
存放选项的对象
returns function
一个可以从包含局部变量的对象渲染生成出 HTML 的函数

const pug = require('pug')

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

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

pug.compileFile`(path, ?options)`

从文件中读取一个 Pug 模板，并编译成一个可多次使用、可传入不同局部变量渲染的函数。

path string
需要编译的 Pug 代码文件的位置
options ?options
存放选项的对象
returns function
一个可以从包含局部变量的对象渲染生成出 HTML 的函数

const pug = require('pug')

// 编译出一个函数
const fn = pug.compileFile('到 Pug 代码文件的路径', options)

// 渲染它
const html = fn(locals)
// => '从 Pug 生成的 HTML 代码'

pug.compileClient`(source, ?options)`

把一个 Pug 模板编译成一份 JavaScript 代码字符串，它可以直接用在浏览器上而不需要 Pug 的运行时库。

source string
需要编译的 Pug 代码
options ?options
存放选项的对象
returns string
一份 JavaScript 代码字符串

const pug = require('pug')

// 编译出一个函数
const fn = pug.compileClient('string of pug', options)

// 渲染它
const html = fn(locals)
// => 'function template(locals) { return "从 Pug 生成的 HTML 代码"; }'

pug.compileClientWithDependenciesTracked`(source, ?options)`

与 [compileClient] 相似，但这个函数返回的是这样一个结构：

json

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

您应该在需要 dependencies 来实现一些诸如“监视 Pug 文件变动”的功能的时候，才使用该函数。

pug.compileFileClient`(path, ?options)`

从文件中读取一个 Pug 模板并编译成一份 JavaScript 代码字符串，它可以直接用在浏览器上而不需要 Pug 的运行时库。

path string
需要编译的 Pug 代码文件的位置
options ?options
存放选项的对象
options.name string
如果您传递了 .name 属性给选项对象，那么编译出来的函数名称就会被换成这个属性指定的名称。
returns string
一份 JavaScript 代码字符串

首先，写下我们的模板……

pug

h1 这是一个 Pug 模板
h2 作者：#{author}

然后将 Pug 编译为函数代码字符串。

const fs = require('node:fs')
const pug = require('pug')

// 将模板编译为一个函数的代码字符串
const jsFunctionString = pug.compileFileClient('/path/to/pugFile.pug', { name: 'fancyTemplateFun' })

// 或许您还想要把模板编译到一个叫做 templates.js 的文件里，让浏览器直接使用。
fs.writeFileSync('templates.js', jsFunctionString)

您获得的输出的结果可能类似下面的内容(即被写入 templates.js 中的代码)：

function fancyTemplateFun(locals) {
  const buf = []
  const pug_mixins = {}
  let pug_interp

  const locals_for_with = (locals || {});

  (function (author) {
    buf.push(`<h1>这是一个 Pug 模板</h1><h2>作者：${
     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('')
}

请确保您已经把 Pug 的运行时库(node_modules/pug/runtime.js)传给了浏览器，从而让浏览器能够顺利执行您刚才编译出来的函数。

html

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

  <body>
    <h1>这是一个神奇的模板。</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)`

source string
需要渲染的 Pug 代码
options ?options
存放选项的对象，同时也直接用作局部变量的对象
callback ?function
Node.js 风格的回调函数，用于接收渲染结果。注意：这个回调是同步执行的。
returns string
渲染出来的 HTML 字符串

const pug = require('pug')

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

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

path string
需要渲染的 Pug 代码文件的位置
options ?options
存放选项的对象，同时也直接用作局部变量的对象
callback ?function
Node.js 风格的回调函数，用于接收渲染结果。注意：这个回调是同步执行的。
returns string
渲染出来的 HTML 字符串

const pug = require('pug')

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

属性 `Properties`

pug.filters

这是一个存放自定义过滤器的哈希表。

这个对象和 filters 选项有着同样的语义，但它是全局地应用在所有 Pug 编译过程的。当一个过滤器名称同时出现在了 pug.filters 和 options.filters 里，本 filters 选项将被优先选择。

不赞成使用

不赞成使用这个属性，应该使用 filters 选项取而代之。

选项 Options

方法 Methods

pug.compile(source, options?)

pug.compileFile(path, ?options)

pug.compileClient(source, ?options)

pug.compileClientWithDependenciesTracked(source, ?options)

pug.compileFileClient(path, ?options)

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

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

属性 Properties