API 參考

此頁面詳細說明如何使用 JavaScript API 呈現 Pug。

提示

Pug 可在您的網頁瀏覽器的控制台中使用！若要測試此頁面所記錄的 Pug API，請嘗試輸入

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

選項

所有 API 方法都接受下列選項

filename: string
正在編譯檔案的名稱。用於例外狀況，且對於相對應的 include\s 和 extend\s 是必要的。預設為 'Pug'。
basedir: string
所有絕對包含的根目錄。
doctype: string
如果 doctype 未指定為範本的一部分，您可以在這裡指定。有時很有用，可以取得自閉合標籤並移除布林屬性的鏡像。請參閱 doctype 文件 以取得更多資訊。
pretty: boolean | string
[已棄用。] 將空白新增到產生的 HTML，以使用 '  ' 作為縮排，讓人類更容易閱讀。如果指定字串，則會改用該字串作為縮排（例如 '\t'）。我們強烈建議不要使用此選項。它會因為改變空白的詮釋和呈現方式，而太常在您的範本中產生細微的錯誤，因此此功能將會移除。預設為 false。
filters: object
自訂篩選器 的雜湊表。預設為 undefined。
self: boolean
使用 self 名稱空間來保留區域變數。它會加速編譯，但您必須寫入 self.variable 才能存取區域變數物件的屬性，而不是寫入 variable。預設為 false。
debug: boolean
如果設為 true，令牌和函數主體會記錄到 stdout。
compileDebug: boolean
如果設為 true，函數來源會包含在已編譯範本中，以提供更好的錯誤訊息（有時在開發中很有用）。預設為啟用，除非在生產模式下與 Express 一起使用。
globals: Array<string>
新增一個全域名稱清單，以便在範本中存取。
cache: boolean
如果設為 true，已編譯函數會快取。必須將 filename 設為快取金鑰。僅適用於 render 函數。預設為 false。
inlineRuntimeFunctions: boolean
內嵌執行時期函數，而不是從共用版本中 require 它們。對於 compileClient 函數，預設為 true（因此不必包含執行時期）。對於所有其他編譯或呈現類型，預設為 false。
name: string
範本函數的名稱。僅適用於 compileClient 函數。預設為 'template'。

方法

pug.compile(source, ?options)

將 Pug 範本編譯成函數，可以使用不同的區域變數多次呈現。

source: string
要編譯的 Pug 範本來源
options: ?options
選項物件
returns: function
一個函數，用於從包含區域變數的物件產生 HTML
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 範本從檔案編譯成函數，可以使用不同的區域變數多次呈現。

path: string
Pug 檔案的路徑
options: ?options
選項物件
returns: function
一個函數，用於從包含區域變數的物件產生 HTML
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 範本編譯成 JavaScript 字串，可在用戶端使用。

source: string
要編譯的 Pug 範本
options: ?options
選項物件
傳回: string
表示函式的 JavaScript 字串
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)

與 compileClient 相同，但此方法傳回的物件格式為

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

只有在需要 dependencies 來實作類似監控 Pug 檔案變更的功能時，才應使用此方法。

pug.compileFileClient(path, ?options)

將 Pug 範本檔案編譯成 JavaScript 字串，可在用戶端使用。

path: string
Pug 檔案的路徑
options: ?options
選項物件
options.name: string
如果在 options 物件中傳入 .name 屬性，它將用作用戶端範本函式的名稱。
傳回: string
JavaScript 函式主體。

首先，我們的範本檔案。

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

接著，將 Pug 檔案編譯成函式字串。

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）。

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)

source: string
要渲染的 Pug 原始碼範本
options: ?options
options 物件，也用作 locals 物件
callback: ?function
接收已渲染結果的 Node.js 風格回呼。此回呼會同步呼叫。
傳回: 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
options 物件，也用作 locals 物件
callback: ?function
接收已渲染結果的 Node.js 風格回呼。此回呼會同步呼叫。
傳回: string
產生的 HTML 字串
var pug = require('pug');

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

屬性

pug.filters

一個自訂過濾器的雜湊表。

這個物件的語意與filters 選項相同，但會套用於所有 Pug 編譯。當一個過濾器同時存在於 pug.filters 和 options.filters 中時，filters 選項會優先。

已棄用

這個屬性已棄用，建議使用filters 選項。