模板继承(Template Inheritance)

¥Template Inheritance

Pug 支持模板继承。模板继承通过 block 和 extends 关键字进行。

¥Pug supports template inheritance. Template inheritance works via the block and extends keywords.

在模板中，block 只是 Pug 的 “block”，子模板可以替换它。这个过程是递归的。

¥In a template, a block is simply a “block” of Pug that a child template may replace. This process is recursive.

如果合适的话，Pug 块可以提供默认内容。不过，提供默认内容完全是可选的。下面的示例定义了 block scripts、block content 和 block foot。

¥Pug blocks can provide default content, if appropriate. Providing default content is purely optional, though. The example below defines block scripts, block content, and block foot.

//- layout.pug
html
  head
    title My Site - #{title}
    block scripts
      script(src='/jquery.js')
  body
    block content
    block foot
      #footer
        p some footer content

要扩展此布局，请创建一个新文件并使用 extends 指令和父模板的路径。（如果未给出文件扩展名，则 .pug 会自动附加到文件名中。）然后，定义一个或多个块以覆盖父块内容。

¥To extend this layout, create a new file and use the extends directive with a path to the parent template. (If no file extension is given, .pug is automatically appended to the file name.) Then, define one or more blocks to override the parent block content.

下面，请注意 foot 块没有重新定义，因此它将使用父级的默认值并输出 “一些页脚内容”。

¥Below, notice that the foot block is not redefined, so it will use the parent’s default and output “some footer content”.

//- page-a.pug
extends layout.pug

block scripts
  script(src='/jquery.js')
  script(src='/pets.js')

block content
  h1= title
  - var pets = ['cat', 'dog']
  each petName in pets
    include pet.pug

//- pet.pug
p= petName

还可以覆盖某个块以提供其他块，如以下示例所示。如图所示，content 现在公开了 sidebar 和 primary 块以供覆盖。（或者，子模板可以完全覆盖 content。）

¥It’s also possible to override a block to provide additional blocks, as shown in the following example. As it shows, content now exposes a sidebar and primary block for overriding. (Alternatively, the child template could override content altogether.)

//- sub-layout.pug
extends layout.pug

block content
  .sidebar
    block sidebar
      p nothing
  .primary
    block primary
      p nothing

//- page-b.pug
extends sub-layout.pug

block content
  .sidebar
    block sidebar
      p nothing
  .primary
    block primary
      p nothing

块 append / prepend(Block append / prepend) ¶

¥Block append / prepend

Pug 允许你 replace（默认）、prepend 或 append 块。

¥Pug allows you to replace (default), prepend, or append blocks.

假设你希望在每个页面上使用 head 块中的默认脚本。你可以这样做：

¥Suppose you have default scripts in a head block that you wish to use on every page. You might do this:

//- layout.pug
html
  head
    block head
      script(src='/vendor/jquery.js')
      script(src='/vendor/caustic.js')
  body
    block content

现在，考虑 JavaScript 游戏的一个页面。你需要一些与游戏相关的脚本以及这些默认值。你可以简单地对块进行 append：

¥Now, consider a page of your JavaScript game. You want some game related scripts as well as these defaults. You can simply append the block:

//- page.pug
extends layout.pug

block append head
  script(src='/vendor/three.js')
  script(src='/game.js')

当使用 block append 或 block prepend 时，“block”一词是可选的：

¥When using block append or block prepend, the word “block” is optional:

//- page.pug
extends layout

append head
  script(src='/vendor/three.js')
  script(src='/game.js')

常见错误(Common mistakes) ¶

¥Common mistakes

Pug 的模板继承是一个强大的功能，它允许你将复杂的页面模板结构拆分为更小、更简单的文件。但是，如果将很多很多模板链接在一起，则可能会使事情变得更加复杂。

¥Pug’s template inheritance is a powerful feature that allows you to split complex page template structures into smaller, simpler files. However, if you chain many, many templates together, you can make things a lot more complicated for yourself.

请注意，只有命名块和 mixin 定义可以出现在子模板的顶层（未缩进）。这个很重要！父模板定义页面的整体结构，子模板只能 append、prepend，或替换特定的标记和逻辑块。如果子模板尝试在块之外添加内容，Pug 将无法知道将其放在最终页面的何处。

¥Note that only named blocks and mixin definitions can appear at the top (unindented) level of a child template. This is important! Parent templates define a page’s overall structure, and child templates can only append, prepend, or replace specific blocks of markup and logic. If a child template tried to add content outside of a block, Pug would have no way of knowing where to put it in the final page.

这包括 无缓冲代码，它也可以包含标记。如果你需要定义在子模板中使用的变量，你可以通过几种不同的方式来执行此操作：

¥This includes unbuffered code, which can also contain markup. If you need to define variables for use in a child template, you can do so a few different ways:

• 将变量添加到 Pug options 对象，或在父模板中的无缓冲代码中定义它们。子模板将继承这些变量。

  ¥Add the variables to the Pug options object, or define them in unbuffered code in a parent template. The child template will inherit these variables.

• 在子模板的块中定义变量。扩展模板必须至少有一个块，否则它将是空的 - 只需在那里定义变量即可。

  ¥Define the variables in a block in the child template. Extending templates must have at least one block, or it would be empty — just define your variables there.

出于同样的原因，Pug 的 缓冲注释 不能出现在扩展模板的顶层：它们生成的 HTML 注释在生成的 HTML 中无处可去。（然而，无缓冲的 Pug 注释仍然可以去任何地方。）

¥For the same reason, Pug’s buffered comments cannot appear at the top level of an extending template: they produce HTML comments which would have nowhere to go in the resulting HTML. (Unbuffered Pug comments, however, can still go anywhere.)