API 參考文檔

此頁面將詳細(xì)說明如何 JavaScript API 來對 Pug 代碼進行渲染。

提示

現(xiàn)在 Pug 可以在您的瀏覽器控制臺上使用！想測試各種 Pug 的 API，您可以嘗試在控制臺輸入：

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

選項

所有的 API 方法都可以使用以下的選項：

filename: string

要編譯的代碼的文件名。用于異常信息以及（使用相對路徑的）包含（include）和擴展（extends）操作。默認(rèn)值是 'Pug'。

basedir: string

模板里所有絕對定位的根目錄。

doctype: string

如果 doctype 沒有出現(xiàn)模板里（比如模板只渲染一個 HTML 片段），那么您可以在這里指定它。在一些需要控制自閉合標(biāo)簽和布爾值屬性的代碼樣式的時候非常有用。您可以閱讀 doctype 的說明來了解更多細(xì)節(jié)。

pretty: boolean | string

（不贊成使用）在輸出的 HTML 里添加 '  ' 這樣的空格縮進來獲得更好的代碼可讀性。如果這里指定了一個字符串（比如 '\t'），那么將會使用它作為控制縮進的字符。我們強烈建議您不要使用這個選項，它改變解釋器和空格渲染工作的方式會極其頻繁地導(dǎo)致一些錯誤。我們將會在未來移除這個功能。默認(rèn)為 false。

filters: object

存放自定義過濾器的哈希表。默認(rèn)為 undefined。

self: boolean

是否使用一個叫做 self 的命名空間來存放局部變量。這可以加速編譯的過程，但是，相對于原來書寫比如 variable 來訪問局部變量，您將需要改為 self.variable 來訪問它們。默認(rèn)為 false。

debug: boolean

當(dāng)設(shè)置為 true 時，編譯產(chǎn)生的函數(shù)代碼會被記錄到標(biāo)準(zhǔn)輸出。

compileDebug: boolean

當(dāng)設(shè)置為 true 時，源代碼會被包含在編譯出來的模板函數(shù)中，用于提供更詳實的錯誤信息（這在開發(fā)時會有用）。它默認(rèn)是啟用的，除非是在 Express 的生產(chǎn)環(huán)境模式中。

globals: Array<string>

該數(shù)組用于向模板中添加全局對象的名字，編譯器將保證它們不被局部作用域影響。

cache: boolean

當(dāng)設(shè)置為 true 時，編譯出來的函數(shù)會被緩存下來。此時必須填寫 filename 選項作為緩存的索引字段。該選項僅用于 render 函數(shù)。默認(rèn)為 false。

inlineRuntimeFunctions: boolean

相對于使用 require 來獲得公用的運行時函數(shù)，是否需要直接嵌入這些運行時函數(shù)。在 compileClient 函數(shù)里默認(rèn)是 true，因此就不需要再手動包含那些函數(shù)（從而讓其能在瀏覽器上運行）。在其他的 compile / render 系列函數(shù)中，默認(rèn)是 false。

name: string

模板函數(shù)的名稱。僅用于 compileClient 函數(shù)。默認(rèn)值是 'template'。

方法

pug.compile(source, ?options)

把一個 Pug 模板編譯成一個可多次使用、可傳入不同局部變量渲染的函數(shù)。

source: string

需要編譯的 Pug 代碼

options: ?options

存放選項的對象

returns: function

一個可以從包含局部變量的對象渲染生成出 HTML 的函數(shù)

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 模板，并編譯成一個可多次使用、可傳入不同局部變量渲染的函數(shù)。

path: string

需要編譯的 Pug 代碼文件的位置

options: ?options

存放選項的對象

returns: function

一個可以從包含局部變量的對象渲染生成出 HTML 的函數(shù)

var pug = require('pug');

// 編譯出一個函數(shù)
var fn = pug.compileFile('到 Pug 代碼文件的路徑', options);

// 渲染它
var html = fn(locals);
// => '從 Pug 生成的 HTML 代碼'

pug.compileClient(source, ?options)

把一個 Pug 模板編譯成一份 JavaScript 代碼字符串，它可以直接用在瀏覽器上而不需要 Pug 的運行時庫。

source: string

需要編譯的 Pug 代碼

options: ?options

存放選項的對象

returns: string

一份 JavaScript 代碼字符串

var pug = require('pug');

// 編譯出一個函數(shù)
var fn = pug.compileClient('string of pug', options);

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

pug.compileClientWithDependenciesTracked(source, ?options) ?

與 compileClient 相似，但這個函數(shù)返回的是這樣一個結(jié)構(gòu)：

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

您應(yīng)該在需要 dependencies 來實現(xiàn)一些諸如“監(jiān)視 Pug 文件變動”的功能的時候，才使用該函數(shù)。

pug.compileFileClient(path, ?options)

從文件中讀取一個 Pug 模板并編譯成一份 JavaScript 代碼字符串，它可以直接用在瀏覽器上而不需要 Pug 的運行時庫。

path: string

需要編譯的 Pug 代碼文件的位置

options: ?options

存放選項的對象

options.name: string

如果您傳遞了 .name 屬性給選項對象，那么編譯出來的函數(shù)名稱就會被換成這個屬性指定的名稱。

returns: string

一份 JavaScript 代碼字符串

首先，寫下我們的模板……

h1 這是一個 Pug 模板
h2 作者：#{author}

然后將 Pug 編譯為函數(shù)代碼字符串。

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

// 將模板編譯為一個函數(shù)的代碼字符串
var jsFunctionString = pug.compileFileClient('/path/to/pugFile.pug', {name: "fancyTemplateFun"});

// 或許您還想要把模板編譯到一個叫做 templates.js 的文件里，讓瀏覽器直接使用。
fs.writeFileSync("templates.js", jsFunctionString);

您獲得的輸出的結(jié)果可能類似下面的內(nèi)容（即被寫入 templates.js 中的代碼）：

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

  var 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("");
}

請確保您已經(jīng)把 Pug 的運行時庫（node_modules/pug/runtime.js）傳給了瀏覽器，從而讓瀏覽器能夠順利執(zhí)行您剛才編譯出來的函數(shù)。

<!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 風(fēng)格的回調(diào)函數(shù)，用于接收渲染結(jié)果。注意：這個回調(diào)是同步執(zhí)行的。

returns: string

渲染出來的 HTML 字符串

var pug = require('pug');

var 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 風(fēng)格的回調(diào)函數(shù)，用于接收渲染結(jié)果。注意：這個回調(diào)是同步執(zhí)行的。

returns: string

渲染出來的 HTML 字符串

var pug = require('pug');

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

屬性

pug.filters

這是一個存放自定義過濾器的哈希表。

這個對象和 filters 選項有著同樣的語義，但它是全局地應(yīng)用在所有 Pug 編譯過程的。當(dāng)一個過濾器名稱同時出現(xiàn)在了 pug.filters 和 options.filters 里，本 filters 選項將被優(yōu)先選擇。

不贊成使用

不贊成使用這個屬性，應(yīng)該使用 filters 選項取而代之。