jinja2模板设计六：全局函数清单、扩展

全局函数清单¶

默认下，下面的函数在全局作用域中可用:

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

返回一个包含整等差级数的列表。 range(i, j) 返回 [i, i+1, i+2, ...., j-1] ；起始值（！）默认为 0 。当给定了公差，它决定了增长（或减小）。 例如 range(4) 返回 [0, 1, 2, 3] 。末端的值被丢弃了。这些是一个 4 元素 数组的有效索引值。

例如重复一个模板块多次来填充一个列表是有用的。想向你有一个 7 个用户的 列表，但你想要渲染三个空项目来用 CSS 强制指定高度:

<ul>
{% for user in users %}
    <li>{{ user.username }}</li>
{% endfor %}
{% for number in range(10 - users|count) %}
    <li class="empty"><span>...</span></li>
{% endfor %}
</ul>

lipsum(n=5, html=True, min=20, max=100)

在模板中生成 lorem ipsum 乱数假文。默认会生成 5 段 HTML ，每段在 20 到 100 词之间。如果 HTML 被禁用，会返回常规文本。这在测试布局时生成简单内容时很有 用。

dict(**items)

方便的字典字面量替代品。 {'foo' : 'bar'} 与 dict(foo=bar) 等价。

class cycler(*items)

周期计允许你在若干个值中循环，类似 loop.cycle 的工作方式。不同于 loop.cycle 的是，无论如何你都可以在循环外或在多重循环中使用它。

比如如果你想要显示一个文件夹和文件列表，且文件夹在上，它们在同一个列表中且 行颜色是交替的。

下面的例子展示了如何使用周期计:

{% set row_class = cycler('odd', 'even') %}
<ul class="browser">
{% for folder in folders %}
  <li class="folder {{ row_class.next() }}">{{ folder|e }}</li>
{% endfor %}
{% for filename in files %}
  <li class="file {{ row_class.next() }}">{{ filename|e }}</li>
{% endfor %}
</ul>

周期计有下面的属性和方法:

reset()

重置周期计到第一个项。

next()

返回当前项并跳转到下一个。

current

返回当前项。.

New in version 2.1.

class joiner(sep=', ')

一个小巧的辅助函数用于“连接”多个节。连接器接受一个字符串，每次被调用时返回 那个字符串，除了第一次调用时返回一个空字符串。你可以使用它来连接:

{% set pipe = joiner("|") %}
{% if categories %} {{ pipe() }}
    Categories: {{ categories|join(", ") }}
{% endif %}
{% if author %} {{ pipe() }}
    Author: {{ author() }}
{% endif %}
{% if can_edit %} {{ pipe() }}
    <a href="?action=edit">Edit</a>
{% endif %}

扩展

下面的几节涵盖了可能被应用启用的 Jinja2 内置的扩展。应用也可以提供进一步 的扩展，但这不会在此描述。会有独立的文档来解释那种情况下的扩展。

i18n

如果启用来 i18n 扩展，可以把模板中的部分标记为可译的。标记一个段为可译的，可 以使用 trans:

<p>{% trans %}Hello {{ user }}!{% endtrans %}</p>

要翻译一个模板表达式——比如使用模板过滤器或访问对象的属性——你需要绑定表达式到 一个名称来在翻译块中使用:

<p>{% trans user=user.username %}Hello {{ user }}!{% endtrans %}</p>

如果你需要在 trans 标签中绑定一个以上的表达式，用逗号来分割（ , ）:

{% trans book_title=book.title, author=author.name %}
This is {{ book_title }} by {{ author }}
{% endtrans %}

在翻译块中不允许使用语句，只能使用变量标签。

为表示复数，在 trans 和 endtrans 之间用 pluralize 标签同时指定单数和复 数形式:

{% trans count=list|length %}
There is {{ count }} {{ name }} object.
{% pluralize %}
There are {{ count }} {{ name }} objects.
{% endtrans %}

默认情况下块中的第一个变量用于决定使用单数还是复数。如果这不奏效，你可以指定 用于复数的名称作为 pluralize 的参数:

{% trans ..., user_count=users|length %}...
{% pluralize user_count %}...{% endtrans %}

也可以翻译表达式中的字符串。为此，有三个函数:

_ gettext: 翻译一个单数字符串 - ngettext: 翻译一个复数字符串 - _: gettext 的别名

例如你可以容易地这样打印一个已翻译的字符串:

{{ _('Hello World!') }}

你可以使用 format 过滤器来使用占位符:

{{ _('Hello %(user)s!')|format(user=user.username) }}

因为其它语言可能不会用同样的顺序使用词汇，要使用多个占位符，应始终用字符 串参数传给 format 。

Changed in version 2.5.

如果激活了新样式的 gettext 调用（ 新样式 Gettext ），使用占位符 会更加简单:

{{ gettext('Hello World!') }}
{{ gettext('Hello %(name)s!', name='World') }}
{{ ngettext('%(num)d apple', '%(num)d apples', apples|count) }}

注意 ngettext 函数的格式化字符串自动接受 num 参数作为计数作为附加的 常规参数。

表达式语句

如果加载了表达式语句扩展，一个名为 do 的扩展即可用。它工作几乎如同常规的变量 表达式（ {{ ... }} ），只是它不打印任何东西。这可以用于修改列表:

{% do navigation.append('a string') %}

循环控制

如果应用启用来 循环控制 ，则可以在循环中使用 break 和 continue 。到达 break 时，循环终止。到达 continue 时，当前处理会终止并 从下一次迭代继续。

这个循环每两项跳过一次:

{% for user in users %}
    {%- if loop.index is even %}{% continue %}{% endif %}
    ...
{% endfor %}

同样，这个循环 10 次迭代之后会终止处理:

{% for user in users %}
    {%- if loop.index >= 10 %}{% break %}{% endif %}
{%- endfor %}

With 语句

New in version 2.3.

如果应用启用了 With 语句 ，将允许在模板中使用 with 关键 字。这使得创建一个新的内作用域。这个作用域中的变量在外部是不可见的。

With 用法简介:

{% with %}
    {% set foo = 42 %}
    {{ foo }}           foo is 42 here
{% endwith %}
foo is not visible here any longer

因为在作用域的开始设置变量很常见，你可以在 with 语句里这么做。下面的两 个例子是等价的:

{% with foo = 42 %}
    {{ foo }}
{% endwith %}

{% with %}
    {% set foo = 42 %}
    {{ foo }}
{% endwith %}

自动转义扩展

New in version 2.4.

如果你的应用程序设置了 自动转义扩展 ，你就可以在模版中开启或者关闭自动转义。

例子:

{% autoescape true %}
自动转义在这块文本中是开启的。
{% endautoescape %}

{% autoescape false %}
自动转义在这块文本中是关闭的。
{% endautoescape %}

在 endautoescape 标签之后，自动转义的行为将回到与之前相同的状态。