模板文档

优质

小牛编辑

128浏览

2023-12-01

这里包括 Nunjuck 所有可用的功能。

Nunjucks 是 jinja2 的 javascript 的实现，所以如果此文档有什么缺失，你可以直接查看 jinja2 的文档，不过两者之间还存在一些差异。

文件扩展名

虽然你可以用任意扩展名来命名你的Nunjucks模版或文件，但Nunjucks社区还是推荐使用.njk。

如果你在给Nunjucks开发工具或是编辑器上的语法插件时，请记得使用.njk扩展名。

变量

变量会从模板上下文获取，如果你想显示一个变量可以：

{{ username }}

会从上下文查找 username 然后显示，可以像 javascript 一样获取变量的属性 (可使用点操作符或者中括号操作符)：

{{ foo.bar }}
{{ foo["bar"] }}

如果变量的值为 undefined 或 null 将不显示，引用到 undefined 或 null 对象也是如此 (如 foo 为 undefined，{{ foo }}, {{ foo.bar }}, {{ foo.bar.baz }} 也不显示)。

过滤器

过滤器是一些可以执行变量的函数，通过管道操作符 (|) 调用，并可接受参数。

{{ foo | title }}
{{ foo | join(",") }}
{{ foo | replace("foo", "bar") | capitalize }}

第三个例子展示了链式过滤器，最终会显示 "Bar"，第一个过滤器将 "foo" 替换成 "bar"，第二个过滤器将首字母大写。

Nunjucks 提供了一些内置的过滤器，你也可以自定义过滤器。

模板继承

模板继承可以达到模板复用的效果，当写一个模板的时候可以定义 "blocks"，子模板可以覆盖他，同时支持多层继承。

如果有一个叫做 parent.html 的模板，如下所示：

{% block header %}
This is the default content
{% endblock %}

<section class="left">
  {% block left %}{% endblock %}
</section>

<section class="right">
  {% block right %}
  This is more content
  {% endblock %}
</section>

然后再写一个模板继承他

{% extends "parent.html" %}

{% block left %}
This is the left side!
{% endblock %}

{% block right %}
This is the right side!
{% endblock %}

以下为渲染结果

This is the default content

<section class="left">
  This is the left side!
</section>

<section class="right">
  This is the right side!
</section>

你可以将继承的模板设为一个变量，这样就可以动态指定继承的模板。这个变量既可以是个指向模板文件的字符串，也可以是个模板编译后所生成的对象(需要添加上下文环境)。因此你可以通过设置上下文变量，从而在渲染时动态地改变所要继承的模板。

{% extends parentTemplate %}

继承功能使用了 extends 和 block 标签，jinja2 文档中有更细节的描述。

super

你可以通过调用super从而将父级区块中的内容渲染到子区块中。如果在前面的例子中你的子模板是这样的：

{% block right %}
{{ super() }}
Right side!
{% endblock %}

这个区块的渲染结果将是：

This is more content
Right side!

被包含的模版自身可以扩展(extends)另一个模版（因此你可以让一系列相关联的模版继承同一种结构）。一个被包含的模版并不会改变包含它的模版的区块结构，它有一个分离的继承树和块级命名空间。换言之，在渲染时，include并不不是将被包含模版代码拉取到包含它的模版中的预处理器。相对的，它对被包含的模版触发了一次的分离渲染，然后再将渲染的结果引入。

import

import 可加载不同的模板，可使你操作模板输出的数据，模板将会输出宏 (macro) 和在顶级作用域进行的赋值 (使用 set)。

被 import 进来的模板没有当前模板的上下文，所以无法使用当前模板的变量，

创建一个叫 forms.html 如下所示

{% macro field(name, value='', type='text') %}
<div class="field">
  <input type="{{ type }}" name="{{ name }}"
         value="{{ value | escape }}" />
</div>
{% endmacro %}

{% macro label(text) %}
<div>
  <label>{{ text }}</label>
</div>
{% endmacro %}

我们可以 import 这个模板并将模板的输出绑定到变量 forms 上，然后就可以使用这个变量了：

{% import "forms.html" as forms %}

{{ forms.label('Username') }}
{{ forms.field('user') }}
{{ forms.label('Password') }}
{{ forms.field('pass', type='password') }}

也可以使用 from import 从模板中 import 指定的值到当前的命名空间：

{% from "forms.html" import input, label as description %}

{{ description('Username') }}
{{ input('user') }}
{{ description('Password') }}
{{ input('pass', type='password') }}

import 可以接受任意表达式，只要它最终返回一个字符串或是模板所编译成的对象: {% import name + ".html" as obj %}.

raw

如果你想输出一些 Nunjucks 特殊的标签 (如 {{)，可以使用 {{)，可以使用 {% raw %} 将所有的内容输出为纯文本。

filter

filter区块允许我们使用区块中的内容来调用过滤器。不同于使用|语法，它会将区块渲染出的内容传递给过滤器。

{% filter title %}
may the force be with you
{% endfilter %}

{% filter replace("force", "forth") %}
may the force be with you
{% endfilter %}

切记：你不能在这些区块中进行任何异步操作。

call

call区块允许你使用标签之间的内容来调用一个宏。这在你需要给宏传入大量内容时是十分有用的。在宏中，你可以通过caller()来获取这些内容。

{% macro add(x, y) %}
{{ caller() }}: {{ x + y }}
{% endmacro%}

{% call add(1, 2) -%}
The result is
{%- endcall %}

上面的例子将会输出"The result is: 3"。

关键字参数

jinja2 使用 Python 的关键字参数，支持函数，过滤器和宏。Nunjucks 会通过一个调用转换 (calling convention) 来支持。

关键字参数如下：

{{ foo(1, 2, bar=3, baz=4) }}

bar 和 baz 为关键字参数，Nunjucks 将他们转换成一个对象作为最后一个参数传入，等价于 javascript 的如下调用：

foo(1, 2, { bar: 3, baz: 4})

因为这使一个标准的调用转换，所以适用于所有的符合预期的函数和过滤器。查看 API 章节获得更多信息。

定义宏的时候也可以使用关键字参数，定义参数值时可设置默认值。Nunjucks 会自动将关键字参数与宏里定义的值做匹配。

{% macro foo(x, y, z=5, w=6) %}
{{ x }}, {{ y }}, {{ z }}, {{ w}}
{% endmacro %}

{{ foo(1, 2) }}        -> 1, 2, 5, 6
{{ foo(1, 2, w=10) }}  -> 1, 2, 5, 10

在宏中还可以混合使用位置参数 (positional arguments) 和关键字参数。如示例，你可以将位置参数用作关键字参数：

{{ foo(20, y=21) }}     -> 20, 21, 5, 6

你还可以用位置参数来替换关键字参数：

{{ foo(5, 6, 7, 8) }}   -> 5, 6, 7, 8

如下示例，你可以跳过 ("skip") 位置参数：

{{ foo(8, z=7) }}      -> 8, , 7, 6

注释

你可以使用 {# and #} 来写注释，渲染时将会去除所有的注释。

{# Loop through all the users #}
{% for user in users %}...{% endfor %}

空白字符控制

模板在正常情况会将变量 (variable) 和标签区块 (tag blocks) 周围的空白字符完全输出。有时，你不想输出一些额外的空白字符，但代码又需要一些空白字符来显得整洁。

你可以在开始和结束区块 (start or end block tag) 添加 (-) 来去除前面和后面的空白字符。

{% for i in [1,2,3,4,5] -%}
  {{ i }}
{%- endfor %}

上面准确的输出为 "12345"，-%} 会去除标签右侧的空白字符，{%- 会去除标签之前的空白字符。

表达式

你可以使用和 javascript 一样的字面量。

Strings: "How are you?", 'How are you?'
Numbers: 40, 30.123
Arrays: [1, 2, "array"]
Dicts: { one: 1, two: 2 }
Boolean: true, false

运算 (Math)

Nunjucks 支持运算 (但尽量少用，把逻辑放在代码中)，可使用以下操作符：

Addition: +
Subtraction: -
Division: /
Division and integer truncation: //
Division remainder: %
Multiplication: *
Power: **

可以如下使用：

{{ 2 + 3 }}       (outputs 5)
{{ 10/5 }}        (outputs 2)
{{ numItems*2 }}

比较 (Comparisons)

==
===
!=
!==
>
>=
<
<=

Examples:

{%-` 会去除标签之前的空白字符。

## 表达式

你可以使用和 javascript 一样的字面量。

* Strings: `"How are you?"`, `'How are you?'`
* Numbers: `40`, `30.123`
* Arrays: `[1, 2, "array"]`
* Dicts: `{ one: 1, two: 2 }`
* Boolean: `true`, `false`

### 运算 (Math)

Nunjucks 支持运算 (但尽量少用，把逻辑放在代码中)，可使用以下操作符：

* Addition: `+`
* Subtraction: `-`
* Division: `/`
* Division and integer truncation: `//`
* Division remainder: `%`
* Multiplication: `*`
* Power: `**`

可以如下使用：

```jinja
{{ 2 + 3 }}       (outputs 5)
{{ 10/5 }}        (outputs 2)
{{ numItems*2 }}

比较 (Comparisons)

==
===
!=
!==
>
>=
<
<=

Examples:

{% if numUsers < 5 %}...{% endif %}
{% if i == 0 %}...{% endif %}

Logic

and
or
not
可使用大括号来分组

Examples:

{% if users and showUsers %}...{% endif %}
{% if i == 0 and not hideFirst %}...{% endif %}
{% if (x < 5 or y < 5) and foo %}...{% endif %}

If 表达式

和 javascript 的三元运算符 (ternary operator) 一样，可使用 if 的内联表达式：

{{ "true" if foo else "false" }}

当 foo 为 true 的时候最终输出 "true" 否则为 "false"，对于获取默认值的时候非常有用：

{{ baz(foo if foo else "default") }}

函数调用 (Function Calls)

如果你传入一个函数，则可以直接调用

{{ foo(1, 2, 3) }}

正则表达式

你可以像在JavaScript中一样创建一个正则表达式:

{{ /^foo.*/ }}
{{ /bar$/g }}

正则表达式所支持的标志如下。查阅Regex on MDN以获取更多信息。

g: 应用到全局
i: 不区分大小写
m: 多行模式
y: 粘性支持（sticky）

自动转义 (Autoescaping)

如果在环境变量中设置了 autoescaping，所有的输出都会自动转义，但可以使用 safe 过滤器，Nunjucks 就不会转义了。

{{ foo }}           // &lt;span%gt;
{{ foo | safe }}    // <span>

如果未开启 autoescaping，所有的输出都会如实输出，但可以使用 escape 过滤器来转义。

{{ foo }}           // <span>
{{ foo | escape }}  // &lt;span&gt;

全局函数 (Global Functions)

以下为一些内置的全局函数

range([start], stop, [step])

如果你需要遍历固定范围的数字可以使用 range，start (默认为 0) 为起始数字，stop 为结束数字，step 为间隔 (默认为 1)。

{% for i in range(0, 5) -%}
  {{ i }},
{%- endfor %}

上面输出 0,1,2,3,4.

cycler(item1, item2, ...itemN)

cycler 可以循环调用你指定的一系列的值。

{% set cls = cycler("odd", "even") %}
{% for row in rows %}
  <div class="{{ cls.next() }}">{{ row.name }}</div>
{% endfor %}

上面的例子中奇数行的 class 为 "odd"，偶数行的 class 为 "even"。你可以使用current属性来获取当前项（在上面的例子中对应cls.current）。

joiner([separator])

当合并多项的时候，希望在他们之间又分隔符 (像逗号)，但又不希望第一项也输出。joiner 将输出分割符 (默认为 ",") 除了第一次调用。

{% set comma = joiner() %}
{% for tag in tags -%}
  {{ comma() }} {{ tag }}
{%- endfor %}

如果 tags 为 ["food", "beer", "dessert"], 上面将输出 food, beer, dessert。

内置的过滤器

Nunjucks已经实现了jinja中的大部分过滤器，同时也新增了一些属于自己的过滤器。我们需要为这些过滤器编写文档。下面是一部分过滤器的文档，其他的你可以点击链接查看jinja上的文档。

default(value, default, [boolean])

(简写为 d)

如果value全等于undefined则返回default，否则返回value。如果boolean为true，则会在value为JavaScript中的假值时（比如：false, ""等）返回default。

在2.0版本中，这个过滤器的默认表现与以前有所不同。在之前的版本中，它会把boolean的默认值设置为true，所以传入任何假值都会返回default。在2.0中，默认只有值为undefined时会返回default。如果你仍旧希望保持原来版本的表现的话，你可以给boolean传入true，或是直接使用value or default。

sort(arr, reverse, caseSens, attr)

用JavaScript中的arr.sort函数排序arr。如果reverse为true，则会返回相反的排序结果。默认状态下排序不会区分大小写，但你可以将caseSens设置为true来让排序区分大小写。我们可以用attr来指定要比较的属性。

striptags (value, [preserve_linebreaks])

类似于jinja中的striptags. 如果preserve_linebreaks为false（同时也是默认值），则会移去SGML/XML标签并用一个空格符替换临近的、连续的空白符号。如果preserve_linebreaks为true，则会尝试保留临近的空白符号。如果你希望使用管道操作符进行类似于{{ text | striptags | nl2br }}这样的操作时，你就会需要用到后一种。否则你还是应该使用默认的用法。

dump (object)

在一个对象上调用JSON.stringify，并将结果输出到模板上。这在调试时很有用：{{ foo | dump }}。

其他过滤器

abs
batch
capitalize
center
dictsort
escape (简写为e)
float
first
groupby
indent
int
join
last
length
list
lower
random
rejectattr (只接受单个参数)
replace (第一个参数也可以接受 JavaScript中的正则表达式)
reverse
round
safe
selectattr (只接受单个参数)
slice
string
sum
title
trim
truncate
upper
urlencode
urlize
wordcount

你也可以直接看代码。

模板文档

文件扩展名

变量

过滤器

模板继承

super

标签

if

for

asyncEach

asyncAll

macro

set

extends

block

include

import

raw

filter

call

关键字参数

注释

空白字符控制

表达式

运算 (Math)

比较 (Comparisons)

比较 (Comparisons)

Logic

If 表达式

函数调用 (Function Calls)

正则表达式

自动转义 (Autoescaping)

全局函数 (Global Functions)

range([start], stop, [step])

cycler(item1, item2, ...itemN)

joiner([separator])

内置的过滤器

default(value, default, [boolean])

sort(arr, reverse, caseSens, attr)

striptags (value, [preserve_linebreaks])

dump (object)

其他过滤器