Django 5.1.dev 文档

Home | Table of contents | Index | Modules

« previous | up | next »

内置模板标记和筛选器¶

本文档描述了Django的内置模板标记和过滤器。建议您使用 automatic documentation ，如果可用，因为这还将包括安装的任何自定义标记或筛选器的文档。

内置标记引用¶

`autoescape`¶

控制当前的自动转义行为。这个标签 on 或 off 作为参数，它决定自动转义是否在块内有效。该块用一个 endautoescape 结束标签。

示例用法：

{% autoescape on %}
    {{ body }}
{% endautoescape %}

当自动转义生效时，从变量派生的所有内容在将结果放入输出之前(但在应用任何过滤器之后)应用了HTML转义。这等效于手动应用 escape 对每个变量进行筛选。

唯一的例外是已经标记为“安全”的变量，不能转义。填充变量的代码可以将变量标记为“安全”，方法是将 safe 或 escape 筛选器，或者因为它是上一个筛选器的结果，该筛选器将该字符串标记为“安全”。

在禁用的自动转义范围内，链接筛选器，包括 escape 可能会导致意外(但记录在案)结果，如下所示：

{% autoescape off %}
    {{ my_list|join:", "|escape }}
{% endautoescape %}

上面的代码将输出 my_list 没有逃脱。这是因为筛选器链序列首先执行 join 在……上面 my_list (不对每一项应用转义，因为 autoescape 是 off )，将结果标记为安全。随后，这个安全的结果将被反馈到 escape 筛选器，它不应用第二轮转义。

为了正确转义序列中的每个元素，请使用 escapeseq 过滤器：

{% autoescape off %}
    {{ my_list|escapeseq|join:", " }}
{% endautoescape %}

`block`¶

定义可由子模板重写的块。见 Template inheritance 更多信息。

`comment`¶

忽略两者之间的一切 {{% comment %}} 和 {{% endcomment %}} . 可在第一个标记中插入可选注释。例如，在注释代码以记录代码被禁用的原因时，这很有用。

示例用法：

<p>Rendered text with {{ pub_date|date:"c" }}</p>
{% comment "Optional note" %}
    <p>Commented out text with {{ create_date|date:"c" }}</p>
{% endcomment %}

comment 不能嵌套标记。

`csrf_token`¶

此标签用于CSRF保护，如文档中所述 Cross Site Request Forgeries .

`cycle`¶

每次遇到此标记时都生成其参数之一。第一个论点是在第一次相遇时产生的，第二次相遇时产生的，等等。一旦所有参数都用完了，标记就循环到第一个参数并再次生成它。

此标记在循环中特别有用：

{% for o in some_list %}
    <tr class="{% cycle 'row1' 'row2' %}">
        ...
    </tr>
{% endfor %}

第一次迭代生成引用类的HTML row1 第二个 row2 ，第三到 row1 同样，对于循环的每个迭代都是如此。

您也可以使用变量。例如，如果您有两个模板变量， rowvalue1 和 rowvalue2 ，您可以在它们的值之间交替，如下所示：

{% for o in some_list %}
    <tr class="{% cycle rowvalue1 rowvalue2 %}">
        ...
    </tr>
{% endfor %}

循环中包含的变量将被转义。您可以使用以下命令禁用自动转义：

{% for o in some_list %}
    <tr class="{% autoescape off %}{% cycle rowvalue1 rowvalue2 %}{% endautoescape %}">
        ...
    </tr>
{% endfor %}

您可以混合使用变量和字符串：

{% for o in some_list %}
    <tr class="{% cycle 'row1' rowvalue2 'row3' %}">
        ...
    </tr>
{% endfor %}

在某些情况下，您可能希望引用循环的当前值，而不是前进到下一个值。要执行此操作，请将 {% cycle %} 使用“as”标记一个名字，如下所示：

{% cycle 'row1' 'row2' as rowcolors %}

从那时起，您可以通过引用循环名称作为上下文变量，在模板中的任意位置插入循环的当前值。如果要独立于原始值将循环移动到下一个值 cycle 标记，您可以使用另一个 cycle 标记并指定变量的名称。因此，下面的模板：

<tr>
    <td class="{% cycle 'row1' 'row2' as rowcolors %}">...</td>
    <td class="{{ rowcolors }}">...</td>
</tr>
<tr>
    <td class="{% cycle rowcolors %}">...</td>
    <td class="{{ rowcolors }}">...</td>
</tr>

将输出：

<tr>
    <td class="row1">...</td>
    <td class="row1">...</td>
</tr>
<tr>
    <td class="row2">...</td>
    <td class="row2">...</td>
</tr>

您可以在 cycle 标签，用空格分隔。单引号括起的值 (' ）或双引号 (" ）被视为字符串文本，而不带引号的值被视为模板变量。

默认情况下，当您使用 as 带有循环标记的关键字，使用 {% cycle %} 启动周期本身将产生周期中的第一个值。如果要在嵌套循环或包含的模板中使用该值，这可能是一个问题。如果只想声明循环而不生成第一个值，则可以添加一个 silent 关键字作为标记中的最后一个关键字。例如：

{% for obj in some_list %}
    {% cycle 'row1' 'row2' as rowcolors silent %}
    <tr class="{{ rowcolors }}">{% include "subtemplate.html" %}</tr>
{% endfor %}

这将输出一个列表 <tr> 元素与 class 两者交替 row1 和 row2 . 子模板将可以访问 rowcolors 在其上下文中，该值将与 <tr> 包围着它。如果 silent 省略关键词， row1 和 row2 将作为普通文本发出，在 <tr> 元素。

当在周期定义上使用SILENT关键字时，SILENT自动应用于该特定周期标签的所有后续使用。以下模板将输出 nothing ，即使第二次调用 {% cycle %} 没有具体说明 silent ：

{% cycle 'row1' 'row2' as rowcolors silent %}
{% cycle rowcolors %}

你可以使用 resetcycle 标签制作 {{% cycle %}} 当下次遇到标记时，从它的第一个值重新启动。

`debug`¶

输出全部调试信息，包括当前上下文和导入的模块。 {% debug %} 时不输出任何内容。 DEBUG 设置为 False 。

`extends`¶

表示此模板扩展父模板。

此标记可通过两种方式使用：

{{% extends "base.html" %}} （带引号）使用文字值 "base.html" 作为要扩展的父模板的名称。
{{% extends variable %}} 使用的值 variable . 如果变量的计算结果为字符串，Django将使用该字符串作为父模板的名称。如果变量的计算结果为 Template 对象，Django将使用该对象作为父模板。

见模板继承更多信息。

通常，模板名称相对于模板加载器的根目录。字符串参数也可以是以开头的相对路径 ./ 或 ../ 。例如，假定目录结构如下：

dir1/
    template.html
    base2.html
    my/
        base3.html
base1.html

在……里面 template.html ，则以下路径将有效：

{% extends "./base2.html" %}
{% extends "../base1.html" %}
{% extends "./my/base3.html" %}

`filter`¶

通过一个或多个筛选器筛选块的内容。可以用管道指定多个过滤器，并且过滤器可以有参数，就像在变量语法中一样。

请注意，该块包括 all 文本介于 filter 和 endfilter 标签。

示例用法：

{% filter force_escape|lower %}
    This text will be HTML-escaped, and will appear in all lowercase.
{% endfilter %}

备注

这个 escape 和 safe 筛选器不是可接受的参数。相反，使用 autoescape 标记来管理模板代码块的自动转义。

`firstof`¶

输出第一个不为“false”的参数变量（即存在、不为空、不是假布尔值且不是零数值）。如果所有传递的变量都为“false”，则不输出任何内容。

示例用法：

{% firstof var1 var2 var3 %}

这相当于：

{% if var1 %}
    {{ var1 }}
{% elif var2 %}
    {{ var2 }}
{% elif var3 %}
    {{ var3 }}
{% endif %}

如果所有传递的变量都为FALSE，还可以使用文字字符串作为备用值：

{% firstof var1 var2 var3 "fallback value" %}

此标记自动转义变量值。您可以使用以下命令禁用自动转义：

{% autoescape off %}
    {% firstof var1 var2 var3 "<strong>fallback value</strong>" %}
{% endautoescape %}

或者，如果只应转义某些变量，则可以使用：

{% firstof var1 var2|safe var3 "<strong>fallback value</strong>"|safe %}

您可以使用语法 {{% firstof var1 var2 var3 as value %}} 将输出存储在变量中。

`for`¶

循环数组中的每一项，使该项在上下文变量中可用。中提供的运动员列表。 athlete_list ：

<ul>
{% for athlete in athlete_list %}
    <li>{{ athlete.name }}</li>
{% endfor %}
</ul>

您可以使用 {{% for obj in list reversed %}} .

如果需要遍历列表列表，可以将每个子列表中的值解压缩到单独的变量中。例如，如果您的上下文包含一个名为 points ，您可以使用以下命令输出点列表：

{% for x, y in points %}
    There is a point at {{ x }},{{ y }}
{% endfor %}

如果您需要访问词典中的项，这也很有用。例如，如果您的上下文包含词典 data ，下面将显示字典的键和值：

{% for key, value in data.items %}
    {{ key }}: {{ value }}
{% endfor %}

请记住，对于点运算符，字典键查找优先于方法查找。因此，如果 data 字典包含一个名为 'items' ， data.items 将返回 data['items'] 而不是 data.items() . 如果要在模板中使用这些方法，请避免添加类似字典方法的键。 (items ， values ， keys 等）。阅读中有关点运算符查找顺序的详细信息 documentation of template variables .

for循环设置循环中可用的变量数：

变量	描述
`forloop.counter`	循环的当前迭代（1个索引）
`forloop.counter0`	循环的当前迭代（0-索引）
`forloop.revcounter`	循环结束时的迭代次数（1个索引）
`forloop.revcounter0`	循环结束时的迭代次数（0-索引）
`forloop.first`	如果这是第一次通过循环，则为真
`forloop.last`	如果这是最后一次通过循环，则为真
`forloop.parentloop`	对于嵌套循环，这是围绕当前循环的循环

`for` ... `empty`¶

这个 for 标记可以采用可选的 {% empty %} 如果给定数组为空或找不到，则显示其文本的子句：

<ul>
{% for athlete in athlete_list %}
    <li>{{ athlete.name }}</li>
{% empty %}
    <li>Sorry, no athletes in this list.</li>
{% endfor %}
</ul>

以上内容等同于--但更短、更简洁，而且可能比--更快：

<ul>
  {% if athlete_list %}
    {% for athlete in athlete_list %}
      <li>{{ athlete.name }}</li>
    {% endfor %}
  {% else %}
    <li>Sorry, no athletes in this list.</li>
  {% endif %}
</ul>

`if`¶

这个 {% if %} 标记对变量求值，如果该变量为“真”(即存在、不为空且不是假的布尔值)，则输出块的内容：

{% if athlete_list %}
    Number of athletes: {{ athlete_list|length }}
{% elif athlete_in_locker_room_list %}
    Athletes should be out of the locker room soon!
{% else %}
    No athletes.
{% endif %}

在上面，如果 athlete_list 不为空，运动员人数将由 {{{{ athlete_list|length }}}}

如你所见， if 标签可能需要一个或多个 {{% elif %}} 条款，以及 {{% else %}} 如果所有以前的条件都失败，将显示的子句。这些条款是可选的。

布尔运算符¶

if 标签可以使用 and ， or 或 not 要测试多个变量或求反给定的变量，请执行以下操作：

{% if athlete_list and coach_list %}
    Both athletes and coaches are available.
{% endif %}

{% if not athlete_list %}
    There are no athletes.
{% endif %}

{% if athlete_list or coach_list %}
    There are some athletes or some coaches.
{% endif %}

{% if not athlete_list or coach_list %}
    There are no athletes or there are some coaches.
{% endif %}

{% if athlete_list and not coach_list %}
    There are some athletes and absolutely no coaches.
{% endif %}

两者都使用 and 和 or 同一标记内的子句是允许的， and 具有高于…的优先权 or 例如：

{% if athlete_list and coach_list or cheerleader_list %}

将被解释为：

if (athlete_list and coach_list) or cheerleader_list

实际括号的使用 if 标记的语法无效。如果需要它们指示优先级，则应使用嵌套 if 标签。

if 标记也可以使用运算符 == ， != ， < ， > ， <= ， >= ， in ， not in ， is 和 is not 其工作原理如下：

`==` 操作人员¶

平等。示例：

{% if somevar == "x" %}
  This appears if variable somevar equals the string "x"
{% endif %}

`!=` 操作人员¶

不平等。示例：

{% if somevar != "x" %}
  This appears if variable somevar does not equal the string "x",
  or if somevar is not found in the context
{% endif %}

`<` 操作人员¶

不到。示例：

{% if somevar < 100 %}
  This appears if variable somevar is less than 100.
{% endif %}

`>` 操作人员¶

大于。示例：

{% if somevar > 0 %}
  This appears if variable somevar is greater than 0.
{% endif %}

`<=` 操作人员¶

小于或等于。示例：

{% if somevar <= 100 %}
  This appears if variable somevar is less than 100 or equal to 100.
{% endif %}

`>=` 操作人员¶

大于或等于。示例：

{% if somevar >= 1 %}
  This appears if variable somevar is greater than 1 or equal to 1.
{% endif %}

`in` 操作人员¶

包含在其中。许多Python容器都支持此运算符，以测试给定值是否在容器中。以下是一些示例，说明如何 x in y 将被解释为：

{% if "bc" in "abcdef" %}
  This appears since "bc" is a substring of "abcdef"
{% endif %}

{% if "hello" in greetings %}
  If greetings is a list or set, one element of which is the string
  "hello", this will appear.
{% endif %}

{% if user in users %}
  If users is a QuerySet, this will appear if user is an
  instance that belongs to the QuerySet.
{% endif %}

`not in` 操作人员¶

不包含在中。这是对 in 操作员。

`is` 操作人员¶

对象标识。测试两个值是否为同一对象。示例：

{% if somevar is True %}
  This appears if and only if somevar is True.
{% endif %}

{% if somevar is None %}
  This appears if somevar is None, or if somevar is not found in the context.
{% endif %}

`is not` 操作人员¶

否定的对象标识。测试两个值是否不是同一对象。这是对 is 接线员。示例：

{% if somevar is not True %}
  This appears if somevar is not True, or if somevar is not found in the
  context.
{% endif %}

{% if somevar is not None %}
  This appears if and only if somevar is not None.
{% endif %}

过滤器¶

您还可以在 if 表情。例如：

{% if messages|length >= 100 %}
   You have lots of messages today!
{% endif %}

复杂表达式¶

所有这些都可以组合成复杂的表达式。对于此类表达式，在计算表达式（即优先级规则）时，了解如何对运算符进行分组是很重要的。运算符的优先级从低到高如下：

or
and
not
in
==, !=, <, >, <=, >=

(这完全遵循Python)。所以，举个例子，下面这个复合体 if 标签：

{% if a == b or c == d and e %}

…将解释为：

(a == b) or ((c == d) and e)

如果需要不同的优先级，则需要使用嵌套 if 标签。有时，为了那些不知道优先规则的人，这样做更清楚。

不能像在Python或数学表示法中那样将比较运算符链接到一起。例如，不使用：

{% if a > b > c %}  (WRONG)

您应该使用：

{% if a > b and b > c %}

`ifchanged`¶

检查值是否已从循环的最后一次迭代更改。

这个 {{% ifchanged %}} 块标记在循环中使用。它有两种可能的用途。

对照其先前状态检查其自身呈现的内容，并且仅在内容已更改时才显示该内容。例如，这将显示天数列表，仅在月份发生变化时才显示：

<h1>Archive for {{ year }}</h1>

{% for date in days %}
    {% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %}
    <a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a>
{% endfor %}

如果给定一个或多个变量，请检查是否有任何变量已更改。例如，下面显示每次更改日期时的日期，而如果小时或日期更改，则显示小时：

{% for date in days %}
    {% ifchanged date.date %} {{ date.date }} {% endifchanged %}
    {% ifchanged date.hour date.date %}
        {{ date.hour }}
    {% endifchanged %}
{% endfor %}

这个 ifchanged 标记还可以采用可选的 {% else %} 值未更改时将显示的子句：

{% for match in matches %}
    <div style="background-color:
        {% ifchanged match.ballot_id %}
            {% cycle "red" "blue" %}
        {% else %}
            gray
        {% endifchanged %}
    ">{{ match }}</div>
{% endfor %}

`include`¶

加载模板并用当前上下文呈现。这是一种在模板中“包括”其他模板的方法。

模板名称可以是变量或硬编码（带引号）字符串，可以是单引号或双引号。

此示例包括模板的内容 "foo/bar.html" ：

{% include "foo/bar.html" %}

通常，模板名称是相对于模板加载器的根目录的。字符串参数也可以是以开头的相对路径 ./ 或 ../ 如中所述 extends 标签。

此示例包括其名称包含在变量中的模板的内容 template_name ：

{% include template_name %}

变量也可以是具有 render() 接受上下文的方法。这允许您引用已编译的 Template 在你的背景下。

此外，变量可以是一个iterable的模板名，在这种情况下，将使用第一个可以加载的，根据 select_template() .

包含的模板在包含它的模板的上下文中呈现。此示例生成输出 "Hello, John!" ：

上下文：变量 person 设置为 "John" 变量 greeting 设置为 "Hello" .
模板：
```
{% include "name_snippet.html" %}
```

这个 name_snippet.html 模板：

{{ greeting }}, {{ person|default:"friend" }}!

您可以使用关键字参数将其他上下文传递给模板：

{% include "name_snippet.html" with person="Jane" greeting="Hello" %}

如果只想使用提供的变量(甚至根本不使用变量)呈现上下文，请使用 only 选择。没有其他变量可用于包含的模板：

{% include "name_snippet.html" with greeting="Hi" only %}

备注

这个 include 标记应被视为“呈现此子模板并包含HTML”的实现，而不是“解析此子模板并将其内容包含为父模板的一部分”。这意味着包含的模板之间没有共享状态——每个包含都是一个完全独立的呈现过程。

对块进行评估之前包括在内。这意味着包含来自另一个的块的模板将包含具有 已经过评估和呈现 -不能被扩展模板等覆盖的块。

`load`¶

加载自定义模板标记集。

例如，以下模板将加载在中注册的所有标记和过滤器 somelibrary 和 otherlibrary 位于包装中 package ：

{% load somelibrary package.otherlibrary %}

方法从库中有选择地加载单个筛选器或标记。 from 争论。在本例中，名为的模板标记/过滤器 foo 和 bar 将从以下位置加载 somelibrary ：

{% load foo bar from somelibrary %}

见 Custom tag and filter libraries 更多信息。

`lorem`¶

显示随机的“lorem ipsum”拉丁文本。这对于在模板中提供示例数据很有用。

用途：

{% lorem [count] [method] [random] %}

这个 {{% lorem %}} 标记可以与零、一、二或三个参数一起使用。参数如下：

论证	描述
`count`	包含要生成的段落或单词数的数字（或变量）（默认值为1）。
`method`	要么 `w` 为了语言， `p` 对于HTML段落或 `b` 对于纯文本段落块（默认为 `b` ）
`random`	单词 `random` 如果给定，则在生成文本时不使用常用段落（“lorem ipsum dolor sit amet…”）。

实例：

{{% lorem %}} 将输出常见的“lorem ipsum”段落。
{{% lorem 3 p %}} 将输出常用的“lorem ipsum”段落和两个随机段落，每个段落用HTML包装 <p> 标签。
{{% lorem 2 w random %}} 将输出两个随机拉丁词。

`now`¶

根据给定字符串使用格式显示当前日期和/或时间。此类字符串可以包含格式说明符字符，如 date 过滤部分。

示例：

It is {% now "jS F Y H:i" %}

请注意，如果要使用“原始”值，可以对格式字符串进行反斜杠转义。在本例中，“o”和“f”都是反斜杠转义的，因为否则每个都是分别显示年份和时间的格式字符串：

It is the {% now "jS \o\f F" %}

这将显示为“9月4日”。

备注

传递的格式也可以是预定义的格式之一 DATE_FORMAT ， DATETIME_FORMAT ， SHORT_DATE_FORMAT 或 SHORT_DATETIME_FORMAT 。预定义的格式可能会因当前区域设置和格式本地化已启用，例如：

It is {% now "SHORT_DATETIME_FORMAT" %}

您还可以使用以下语法 {% now "Y" as current_year %} 将输出(作为字符串)存储在变量中。如果您要使用以下功能，则此功能非常有用 {% now %} 在模板标记内，如 blocktranslate 例如：

{% now "Y" as current_year %}
{% blocktranslate %}Copyright {{ current_year }}{% endblocktranslate %}

`query_string`¶

New in Django Development version.

从给定的 QueryDict 实例(如果提供)或 request.GET 如果不是，则 django.template.context_processors.request 已启用上下文处理器。如果 QueryDict 为空，则输出将为空字符串。否则，将返回带有前导的查询字符串 "?" 。

如果不使用 django.template.context_processors.request 上下文处理器，则必须将 request 放入模板上下文或一个 QueryDict 实例添加到此标记中。

下面的示例逐字输出当前查询字符串。因此，如果查询字符串是 ?color=green&size=M ，则输出将为 ?color=green&size=M ：

{% query_string %}

您还可以传入一个定制的 QueryDict 它将被用来代替 request.GET ：

{% query_string my_query_dict %}

每个关键字参数都将添加到查询字符串中，替换该键的任何现有值。使用查询字符串 ?color=blue ，则会导致以下结果 ?color=red&size=S ：

{% query_string color="red" size="S" %}

可以通过传递 None 作为一种价值。使用查询字符串 ?color=blue&size=M ，则会导致以下结果 ?size=M ：

{% query_string color=None %}

如果给定的参数是列表，则该值将保留为列表。例如，如果 my_list 设置为 ["red", "blue"] ，则会导致以下结果 ?color=red&color=blue ：

{% query_string color=my_list %}

使用此标记的一个常见示例是，在显示一页结果时保留当前查询字符串，同时添加指向下一页和前一页结果的链接。例如，如果分页器当前位于第3页，并且当前查询字符串为 ?color=blue&size=M&page=3 ，下面的代码将输出 ?color=blue&size=M&page=4 ：

{% query_string page=page.next_page_number %}

您还可以将该值存储在变量中，例如，如果您需要使用如下语法指向同一页的多个链接：

{% query_string page=page.next_page_number as next_page %}

`regroup`¶

通过公共属性重新组合相似对象的列表。

这个复杂的标签最好用一个例子来说明：说 cities 是由字典表示的城市列表，其中包含 "name" ， "population" 和 "country" 钥匙：

cities = [
    {"name": "Mumbai", "population": "19,000,000", "country": "India"},
    {"name": "Calcutta", "population": "15,000,000", "country": "India"},
    {"name": "New York", "population": "20,000,000", "country": "USA"},
    {"name": "Chicago", "population": "7,000,000", "country": "USA"},
    {"name": "Tokyo", "population": "33,000,000", "country": "Japan"},
]

…您希望显示按国家排序的分层列表，如下所示：

印度
- 孟买：19000000
- 加尔各答：15000000
USA
- 纽约：20000000
- 芝加哥：70万
日本
- 东京：33000000

您可以使用 {% regroup %} 标记可按国家/地区对城市列表进行分组。以下模板代码片断将实现这一点：

{% regroup cities by country as country_list %}

<ul>
{% for country in country_list %}
    <li>{{ country.grouper }}
    <ul>
        {% for city in country.list %}
          <li>{{ city.name }}: {{ city.population }}</li>
        {% endfor %}
    </ul>
    </li>
{% endfor %}
</ul>

让我们来看看这个例子。 {{% regroup %}} 采用三个参数：要重新组合的列表、要分组的属性以及结果列表的名称。这里，我们正在重新组织 cities 按清单列出 country 属性并调用结果 country_list .

{{% regroup %}} 生成一个列表（在本例中， country_list 的） 组对象 . 组对象是的实例 namedtuple() 有两个字段：

grouper --按（例如字符串“India”或“Japan”）分组的项。
list --此组中所有项目的列表（例如，Country='India'的所有城市的列表）。

因为 {% regroup %} 产 namedtuple() 对象，您还可以将上一个示例编写为：

{% regroup cities by country as country_list %}

<ul>
{% for country, local_cities in country_list %}
    <li>{{ country }}
    <ul>
        {% for city in local_cities %}
          <li>{{ city.name }}: {{ city.population }}</li>
        {% endfor %}
    </ul>
    </li>
{% endfor %}
</ul>

注意 {{% regroup %}} 不订购其输入！我们的示例依赖于以下事实： cities 列表的排序依据 country 首先。如果 cities 列表做 not 命令其成员 country 对于一个国家，重组会天真地显示出不止一个群体。例如，说 cities 列表已设置为（请注意，这些国家未分组在一起）：

cities = [
    {"name": "Mumbai", "population": "19,000,000", "country": "India"},
    {"name": "New York", "population": "20,000,000", "country": "USA"},
    {"name": "Calcutta", "population": "15,000,000", "country": "India"},
    {"name": "Chicago", "population": "7,000,000", "country": "USA"},
    {"name": "Tokyo", "population": "33,000,000", "country": "Japan"},
]

使用此输入 cities 举例 {{% regroup %}} 上面的模板代码将导致以下输出：

印度
- 孟买：19000000
USA
- 纽约：20000000
印度
- 加尔各答：15000000
USA
- 芝加哥：70万
日本
- 东京：33000000

这个gotcha的最简单的解决方案是确保在视图代码中，数据是按照您想要显示的方式排序的。

另一种解决方案是使用 dictsort 过滤器，如果您的数据在字典列表中：

{% regroup cities|dictsort:"country" by country as country_list %}

按其他属性分组¶

任何有效的模板查找都是REGROUP标签的合法分组属性，包括方法、属性、字典键和列表项。例如，如果“Country”字段是具有属性“Description”的类的外键，则可以使用：

{% regroup cities by country.description as country_list %}

或者，如果 country 是包含以下内容的字段 choices ，它将有一个 get_FOO_display() 方法作为属性提供，允许您对显示字符串进行分组，而不是 choices 密钥：

{% regroup cities by get_country_display as country_list %}

{{{{ country.grouper }}}} 现在将显示 choices 设置而不是键。

`resetcycle`¶

重置上一个 cycle 以便在下次遇到时从第一个项目重新启动。没有参数， {{% resetcycle %}} 将重置最后一个 {{% cycle %}} 在模板中定义。

用法示例：

{% for coach in coach_list %}
    <h1>{{ coach.name }}</h1>
    {% for athlete in coach.athlete_set.all %}
        <p class="{% cycle 'odd' 'even' %}">{{ athlete.name }}</p>
    {% endfor %}
    {% resetcycle %}
{% endfor %}

此示例将返回此HTML：

<h1>Gareth</h1>
<p class="odd">Harry</p>
<p class="even">John</p>
<p class="odd">Nick</p>

<h1>John</h1>
<p class="odd">Andrea</p>
<p class="even">Melissa</p>

注意第一个块是如何以 class="odd" 新的开始 class="odd" . 没有 {{% resetcycle %}} 标记，第二个块将以 class="even" .

您还可以重置命名的循环标记：

{% for item in list %}
    <p class="{% cycle 'odd' 'even' as stripe %} {% cycle 'major' 'minor' 'minor' 'minor' 'minor' as tick %}">
        {{ item.data }}
    </p>
    {% ifchanged item.category %}
        <h1>{{ item.category }}</h1>
        {% if not forloop.first %}{% resetcycle tick %}{% endif %}
    {% endifchanged %}
{% endfor %}

在这个例子中，我们每五行都有交替的奇数行/偶数行和一个“主要”行。当类别更改时，仅重置五行循环。

`spaceless`¶

删除HTML标记之间的空白。这包括制表符和换行符。

用法示例：

{% spaceless %}
    <p>
        <a href="foo/">Foo</a>
    </p>
{% endspaceless %}

此示例将返回此HTML：

<p><a href="foo/">Foo</a></p>

只有空格 tags 被删除--而不是标记和文本之间的空格。在本例中，周围的空间 Hello 不会被剥夺：

{% spaceless %}
    <strong>
        Hello
    </strong>
{% endspaceless %}

`templatetag`¶

输出用于组成模板标记的语法字符之一。

模板系统没有“转义”个别字符的概念。但是，您可以使用 {% templatetag %} 标记以显示模板标记字符组合之一。

参数告诉输出哪个模板位：

论证	输出
`openblock`	`{%`
`closeblock`	`%}`
`openvariable`	`{{`
`closevariable`	`}}`
`openbrace`	`{`
`closebrace`	`}`
`opencomment`	`{#`
`closecomment`	`#}`

示例用法：

The {% templatetag openblock %} characters open a block.

另请参阅 verbatim 标记，以获得包含这些字符的另一种方式。

`url`¶

返回与给定视图和可选参数匹配的绝对路径引用（没有域名的URL）。结果路径中的任何特殊字符都将使用 iri_to_uri() .

这是一种在不违反DRY原则的情况下输出链接的方法，它必须在模板中硬编码URL：

{% url 'some-url-name' v1 v2 %}

第一个参数是 URL pattern name 。它可以是带引号的文字或任何其他上下文变量。其他参数是可选的，应该是空格分隔值，这些值将用作URL中的参数。上面的例子显示了位置参数的传递。或者，您可以使用关键字语法：

{% url 'some-url-name' arg1=v1 arg2=v2 %}

不要在单个调用中混合使用位置语法和关键字语法。urlconf所需的所有参数都应存在。

例如，假设您有一个视图， app_views.client ，其urlconf获取客户端ID（此处， client() 是视图文件中的方法 app_views.py ）urlconf行可能如下所示：

path("client/<int:id>/", app_views.client, name="app-views-client")

如果此应用程序的urlconf包含在项目的urlconf中，路径如下：

path("clients/", include("project_name.app_name.urls"))

...然后，您可以在模板中创建指向此视图的链接，如下所示：

{% url 'app-views-client' client.id %}

模板标记将输出字符串 /clients/client/123/ .

请注意，如果要反转的URL不存在，您将得到一个 NoReverseMatch 引发异常，这将导致网站显示错误页。

如果您希望检索URL而不显示它，您可以使用稍微不同的调用：

{% url 'some-url-name' arg arg2 as the_url %}

<a href="{{ the_url }}">I'm linking to {{ the_url }}</a>

由创建的变量的范围 as var 语法是 {{% block %}} 其中 {{% url %}} 标签出现。

这 {% url ... as var %} 语法将 not 如果缺少该视图，则会导致错误。在实践中，您将使用它链接到可选的视图：

{% url 'some-url-name' as the_url %}
{% if the_url %}
  <a href="{{ the_url }}">Link to optional stuff</a>
{% endif %}

如果要检索命名空间URL，请指定完全限定名称：

{% url 'myapp:view-name' %}

这是正常的 namespaced URL resolution strategy 包括使用上下文提供的有关当前应用程序的任何提示。

警告

别忘了在URL模式周围加引号 name 否则，该值将被解释为上下文变量！

`verbatim`¶

阻止模板引擎呈现此块标记的内容。

一种常见的用途是允许与Django的语法冲突的JavaScript模板层。例如：

{% verbatim %}
    {{if dying}}Still alive.{{/if}}
{% endverbatim %}

您还可以指定特定的结束标记，允许使用 {% endverbatim %} 作为未渲染内容的一部分：

{% verbatim myblock %}
    Avoid template rendering via the {% verbatim %}{% endverbatim %} block.
{% endverbatim myblock %}

`widthratio`¶

对于创建条形图等，此标记计算给定值与最大值的比率，然后将该比率应用于常量。

例如：

<img src="bar.png" alt="Bar"
     height="10" width="{% widthratio this_value max_value max_width %}">

如果 this_value 是175， max_value 是200， max_width 为100，上面示例中的图像将为88像素宽（因为175/200=0.875；.875*100=87.5，四舍五入为88）。

在某些情况下，您可能希望捕获 widthratio 在一个变量中。它可能有用，例如在 blocktranslate 如下所示：

{% widthratio this_value max_value max_width as width %}
{% blocktranslate %}The width is: {{ width }}{% endblocktranslate %}

`with`¶

以更简单的名称缓存复杂变量。这在多次访问“昂贵”方法（例如，访问数据库的方法）时很有用。

例如：

{% with total=business.employees.count %}
    {{ total }} employee{{ total|pluralize }}
{% endwith %}

填充变量（在上面的示例中， total ）仅在 {{% with %}} 和 {{% endwith %}} 标签。

您可以分配多个上下文变量：

{% with alpha=1 beta=2 %}
    ...
{% endwith %}

备注

仍支持以前更详细的格式： {{% with business.employees.count as total %}}

内置筛选器引用¶

`add`¶

将参数添加到值中。

例如：

{{ value|add:"2" }}

如果 value 是 4 ，则输出为 6 .

此筛选器将首先尝试将两个值强制为整数。如果失败，它将尝试将这些值相加。这将对某些数据类型（字符串、列表等）有效，而对其他数据类型无效。如果失败，结果将是一个空字符串。

例如，如果我们有：

{{ first|add:second }}

和 first 是 [1, 2, 3] 和 second 是 [4, 5, 6] ，则输出为 [1, 2, 3, 4, 5, 6] .

警告

可以强制为整数的字符串将总结，不连接，如上面的第一个示例中所示。

`addslashes`¶

在引号前添加斜线。例如，对于在csv中转义字符串很有用。

例如：

{{ value|addslashes }}

如果 value 是 "I'm using Django" ，输出为 "I\'m using Django" .

`capfirst`¶

将值的第一个字符大写。如果第一个字符不是字母，则此筛选器无效。

例如：

{{ value|capfirst }}

如果 value 是 "django" ，输出为 "Django" .

`center`¶

将给定宽度的字段中的值居中。

例如：

"{{ value|center:"15" }}"

如果 value 是 "Django" ，输出为 " Django " .

`cut`¶

从给定字符串中删除arg的所有值。

例如：

{{ value|cut:" " }}

如果 value 是 "String with spaces" ，输出为 "Stringwithspaces" .

`date`¶

根据给定格式设置日期格式。

使用与PHP类似的格式 date() 函数有一些不同之处。

备注

这些格式字符不在模板之外的Django中使用。它们被设计成与PHP兼容，以方便设计师进行转换。

可用格式字符串：

设置字符格式	描述	实例输出
Day
`d`	每月的某一天，2位数字，前导零。	`'01'` to `'31'`
`j`	月份中没有前导零的日期。	`'1'` to `'31'`
`D`	一周中的某一天，文本，3个字母。	`'Fri'`
`l`	一周中的某一天，文本，漫长。	`'Friday'`
`S`	月日的英文序数后缀，2个字符。	`'st'`, `'nd'`, `'rd'` or `'th'`
`w`	星期几，不带前导零的数字。	`'0'` （星期日） `'6'` （星期六）
`z`	一年中的某一天。	`1` to `366`
Week
`W`	ISO-8601每年的第几周，从星期一开始。	`1`, `53`
Month
`m`	月，2位数字，前导零。	`'01'` to `'12'`
`n`	月份没有前导零。	`'1'` to `'12'`
`M`	月，文本，3个字母。	`'Jan'`
`b`	月，文本，3个字母，小写。	`'jan'`
`E`	月份，特定于区域设置的可选表示，通常用于长日期表示。	`'listopada'` （波兰地区，而不是 `'Listopad'` ）
`F`	月，文本，长。	`'January'`
`N`	美联社样式中的月份缩写。专有扩展。	`'Jan.'`, `'Feb.'`, `'March'`, `'May'`
`t`	给定月份中的天数。	`28` to `31`
Year
`y`	年份，带前导零的2位数字。	`'00'` to `'99'`
`Y`	年份，带前导零的4位数字。	`'0001'`, ..., `'1999'`, ..., `'9999'`
`L`	布尔值表示是否为闰年。	`True` or `False`
`o`	ISO-8601周编号年份，对应于使用闰周的ISO-8601周编号（W）。有关更常见的年份格式，请参见Y。	`'1999'`
Time
`g`	小时，12小时格式，不带前导零。	`'1'` to `'12'`
`G`	小时，24小时格式，不带前导零。	`'0'` to `'23'`
`h`	小时，12小时格式。	`'01'` to `'12'`
`H`	小时，24小时制。	`'00'` to `'23'`
`i`	分钟。	`'00'` to `'59'`
`s`	秒，2位数，前导零。	`'00'` to `'59'`
`u`	微秒。	`000000` to `999999`
`a`	`'a.m.'` 或 `'p.m.'` （请注意，这与PHP的输出稍有不同，因为这包括与相关新闻样式匹配的句点。）	`'a.m.'`
`A`	`'AM'` 或 `'PM'` .	`'AM'`
`f`	时间，12小时分，如果是零，还有分钟。专有扩展。	`'1'`, `'1:30'`
`P`	时间，以12小时、分钟和“a.m.”和“p.m.”为单位，如果为零，则剩余分钟，如果合适，特殊情况下字符串为“午夜”和“中午”。专有扩展。	`'1 a.m.'`, `'1:30 p.m.'`, `'midnight'`, `'noon'`, `'12:30 p.m.'`
Timezone
`e`	时区名称。可以是任何格式，也可以返回空字符串，具体取决于日期时间。	`''` ， `'GMT'` ， `'-500'` ， `'US/Eastern'` 等。
`I`	夏令时，无论它是否有效。	`'1'` or `'0'`
`O`	以小时为单位的格林威治时间差。	`'+0200'`
`T`	这台机器的时区。	`'EST'`, `'MDT'`
`Z`	时区偏移（秒）。UTC以西时区的偏移量始终为负，而UTC以东时区的偏移量始终为正。	`-43200` to `43200`
Date/Time
`c`	ISO 8601格式。(注意：与其他格式化程序(如“Z”、“O”或“r”)不同，如果value是朴素的日期时间，则“c”格式化程序不会添加时区偏移(请参见 `datetime.tzinfo` )。	`2008-01-02T10:30:00.000123+02:00` 或 `2008-01-02T10:30:00.000123` 如果日期时间是幼稚的
`r`	RFC 5322 格式化日期。	`'Thu, 21 Dec 2000 16:01:07 +0200'`
`U`	自Unix时代以来的秒数（1970年1月1日00:00:00 UTC）。

例如：

{{ value|date:"D d M Y" }}

如果 value 是一个 datetime 对象（例如，结果 datetime.datetime.now() ，输出将是字符串 'Wed 09 Jan 2008' .

传递的格式可以是预定义的格式之一 DATE_FORMAT ， DATETIME_FORMAT ， SHORT_DATE_FORMAT 或 SHORT_DATETIME_FORMAT 或使用上表中所示格式说明符的自定义格式。请注意，根据当前区域设置，预定义格式可能会有所不同。

假设 LANGUAGE_CODE 例如， "es" ，则为：

{{ value|date:"SHORT_DATE_FORMAT" }}

输出将是字符串 "09/01/2008" (the "SHORT_DATE_FORMAT" 的格式说明符 es Django附带的区域设置为 "d/m/Y" ）

在不使用格式字符串的情况下， DATE_FORMAT 使用了格式说明符。假设设置与上一个示例相同：

{{ value|date }}

输出 9 de Enero de 2008 (the DATE_FORMAT 的格式说明符 es 区域设置是 r'j \d\e F \d\e Y' ). “d”和“e”都是反斜杠转义的，因为否则每个都是一个格式字符串，分别显示日期和时区名称。

你可以结合 date 与 time 筛选器以呈现 datetime 价值。例如：

{{ value|date:"D d M Y" }} {{ value|time:"H:i" }}

`default`¶

如果值的计算结果为 False ，使用给定的默认值。否则，使用该值。

例如：

{{ value|default:"nothing" }}

如果 value 是 "" （空字符串），输出将 nothing .

`default_if_none`¶

如果（且仅当）值为 None ，使用给定的默认值。否则，使用该值。

请注意，如果给定空字符串，则默认值将 not 被使用。使用 default 如果要回退为空字符串，则筛选。

例如：

{{ value|default_if_none:"nothing" }}

如果 value 是 None ，输出为 nothing .

`dictsort`¶

获取字典列表并返回按参数中给定的键排序的列表。

例如：

{{ value|dictsort:"name" }}

如果 value 是：

[
    {"name": "zed", "age": 19},
    {"name": "amy", "age": 22},
    {"name": "joe", "age": 31},
]

那么输出将是：

[
    {"name": "amy", "age": 22},
    {"name": "joe", "age": 31},
    {"name": "zed", "age": 19},
]

您还可以做更复杂的事情，如：

{% for book in books|dictsort:"author.age" %}
    * {{ book.title }} ({{ book.author.name }})
{% endfor %}

如果 books 是：

[
    {"title": "1984", "author": {"name": "George", "age": 45}},
    {"title": "Timequake", "author": {"name": "Kurt", "age": 75}},
    {"title": "Alice", "author": {"name": "Lewis", "age": 33}},
]

那么输出将是：

* Alice (Lewis)
* 1984 (George)
* Timequake (Kurt)

dictsort 还可以对列表列表(或任何其他实现 __getitem__() )按指定索引处的元素。例如：

{{ value|dictsort:0 }}

如果 value 是：

[
    ("a", "42"),
    ("c", "string"),
    ("b", "foo"),
]

那么输出将是：

[
    ("a", "42"),
    ("b", "foo"),
    ("c", "string"),
]

必须将索引作为整数而不是字符串传递。以下命令会产生空输出：

{{ values|dictsort:"0" }}

词典不支持按指定索引处的元素排序。

`dictsortreversed`¶

获取字典列表并返回该列表，该列表按参数中给定的键的相反顺序排序。这与上面的过滤器的工作原理完全相同，但返回的值将是相反的顺序。

`divisibleby`¶

返回 True 如果值可被参数整除。

例如：

{{ value|divisibleby:"3" }}

如果 value 是 21 ，输出为 True .

`escape`¶

转义字符串的HTML。具体来说，它可以进行以下替换：

< is converted to <
> is converted to >
' (single quote) is converted to '
" (double quote) is converted to "
& is converted to &

应用 escape 对于通常对结果应用自动转义的变量，只会执行一轮转义。因此，即使在自动转义环境中也可以安全地使用此函数。如果要应用多个转义过程，请使用 force_escape 过滤器。

例如，您可以应用 escape 在以下情况下到字段 autoescape 处于关闭状态：

{% autoescape off %}
    {{ title|escape }}
{% endautoescape %}

链接 escape 使用其他滤镜

正如在 autoescape 部分，当过滤器包括 escape 链接在一起，如果前面的筛选器将潜在的不安全字符串标记为安全，则可能会导致意外结果 autoescape 存在 off 。

在这种情况下，链接 escape 不会对已标记为安全的字符串进行重新转义。

例如，在使用对序列进行操作的过滤器时，这一点尤其重要 join 。如果需要对序列中的每个元素进行转义，请使用专用 escapeseq 过滤。

`escapejs`¶

在单引号或双引号中转义字符以用作完整的JavaScript字符串文字，如下所示。此筛选器不会使该字符串在 "JavaScript template literals" (JavaScript反引号语法)。不支持上面未列出的任何其他用途。通常建议使用HTML语言传递数据 data- 属性，或 json_script 筛选器，而不是在嵌入的JavaScript中。

例如：

<script>
let myValue = '{{ value|escapejs }}'

`escapeseq`¶

New in Django 5.0.

将应用于 escape 过滤到序列的每个元素。与其他对序列进行操作的筛选器配合使用，例如 join 。例如：

{% autoescape off %}
    {{ my_list|escapeseq|join:", " }}
{% endautoescape %}

`filesizeformat`¶

将值格式化为“可读”文件大小（即 '13 KB' ， '4.1 MB' ， '102 bytes' 等）。

例如：

{{ value|filesizeformat }}

如果 value 是123456789，输出为 117.7 MB .

文件大小和国际单位

严格来说， filesizeformat 不符合国际单位制，当字节大小以1024次幂计算时，建议使用kib、mib、gib等。相反，django使用传统的单位名称（kb、mb、gb等），与更常用的名称相对应。

`first`¶

返回列表中的第一项。

例如：

{{ value|first }}

如果 value 是名单 ['a', 'b', 'c'] ，输出为 'a' .

`floatformat`¶

在没有参数的情况下使用时，将浮点数舍入到小数点后一位，但仅当要显示小数部分时。例如：

`value`	模板	产量
`34.23234`	`{{ value\|floatformat }}`	`34.2`
`34.00000`	`{{ value\|floatformat }}`	`34`
`34.26000`	`{{ value\|floatformat }}`	`34.3`

如果与数字整数参数一起使用， floatformat 将一个数字舍入到小数点后那么多。例如：

`value`	模板	产量
`34.23234`	`{{ value\|floatformat:3 }}`	`34.232`
`34.00000`	`{{ value\|floatformat:3 }}`	`34.000`
`34.26000`	`{{ value\|floatformat:3 }}`	`34.260`

特别有用的是将0（零）作为参数传递，该参数将浮点四舍五入为最接近的整数。

`value`	模板	产量
`34.23234`	`{{ value\|floatformat:"0" }}`	`34`
`34.00000`	`{{ value\|floatformat:"0" }}`	`34`
`39.56000`	`{{ value\|floatformat:"0" }}`	`40`

如果参数传递给 floatformat 如果为负，它将把一个数字舍入到小数点后的那个位数——但只有在有小数部分要显示的情况下。例如：

`value`	模板	产量
`34.23234`	`{{ value\|floatformat:"-3" }}`	`34.232`
`34.00000`	`{{ value\|floatformat:"-3" }}`	`34`
`34.26000`	`{{ value\|floatformat:"-3" }}`	`34.260`

如果将参数传递给 floatformat 有没有 g 后缀，它将强制按 THOUSAND_SEPARATOR 用于活动区域设置。例如，当活动区域设置为 en (英文)：

`value`	模板	产量
`34232.34`	`{{ value\|floatformat:"2g" }}`	`34,232.34`
`34232.06`	`{{ value\|floatformat:"g" }}`	`34,232.1`
`34232.00`	`{{ value\|floatformat:"-3g" }}`	`34,232`

输出始终本地化(独立于 {% localize off %} 标记)，除非将参数传递给 floatformat 有没有 u 后缀，它将强制禁用本地化。例如，当活动区域设置为 pl (波兰语)：

`value`	模板	产量
`34.23234`	`{{ value\|floatformat:"3" }}`	`34,232`
`34.23234`	`{{ value\|floatformat:"3u" }}`	`34.232`

使用 floatformat 没有参数等于使用 floatformat 与…参数 -1 .

`force_escape`¶

将HTML转义应用于字符串（请参见 escape 详细信息筛选）。已应用此筛选器立即并返回一个新的转义字符串。在需要多次转义或希望对转义结果应用其他筛选器的罕见情况下，这非常有用。通常，您要使用 escape 过滤器。

例如，如果要捕获 <p> 对象创建的HTML元素 linebreaks 过滤器：

{% autoescape off %}
    {{ body|linebreaks|force_escape }}
{% endautoescape %}

`get_digit`¶

给定一个整数，返回请求的数字，其中1是最右边的数字，2是第二个最右边的数字，等等。返回无效输入的原始值（如果输入或参数不是整数，或者参数小于1）。否则，输出总是一个整数。

例如：

{{ value|get_digit:"2" }}

如果 value 是 123456789 ，输出为 8 .

`iriencode`¶

将IRI（国际化资源标识符）转换为适合包含在URL中的字符串。如果您试图在URL中使用包含非ASCII字符的字符串，那么这是必需的。

在已经通过 urlencode 过滤器。

例如：

{{ value|iriencode }}

如果 value 是 "?test=1&me=2" ，输出为 "?test=1&me=2" .

`join`¶

用字符串联接列表，如python的 str.join(list)

例如：

{{ value|join:" // " }}

如果 value 是名单 ['a', 'b', 'c'] ，输出将是字符串 "a // b // c" .

`json_script`¶

安全地将python对象输出为json，包装在 <script> 标记，可用于JavaScript。

Argument: 的可选的HTML“id” <script> 标签。

例如：

{{ value|json_script:"hello-data" }}

如果 value 是字典吗 {{'hello': 'world'}} ，输出为：

<script id="hello-data" type="application/json">{"hello": "world"}</script>

结果数据可以在javascript中访问，如下所示：

const value = JSON.parse(document.getElementById('hello-data').textContent);

通过转义字符“<”、“>”和“&”来减轻XSS攻击。例如，如果 value 是 {{'hello': 'world</script>&'}} ，输出为：

<script id="hello-data" type="application/json">{"hello": "world\\u003C/script\\u003E\\u0026amp;"}</script>

这与禁止页内脚本执行的严格内容安全策略兼容。它还保持了被动数据和可执行代码之间的清晰分离。

`last`¶

返回列表中的最后一项。

例如：

{{ value|last }}

如果 value 是名单 ['a', 'b', 'c', 'd'] ，输出将是字符串 "d" .

`length`¶

返回值的长度。这对字符串和列表都有效。

例如：

{{ value|length }}

如果 value 是 ['a', 'b', 'c', 'd'] 或 "abcd" ，输出为 4 .

过滤器返回 0 对于未定义的变量。

`linebreaks`¶

用适当的HTML替换纯文本中的换行符；单个换行符变为HTML换行符 (<br> ）新的一行加上一个空行就变成了一个段落分隔符。 (</p> ）

例如：

{{ value|linebreaks }}

如果 value 是 Joel\nis a slug ，输出为 <p>Joel<br>is a slug</p> .

`linebreaksbr`¶

将一段纯文本中的所有换行符转换为HTML换行符 (<br> ）

例如：

{{ value|linebreaksbr }}

如果 value 是 Joel\nis a slug ，输出为 Joel<br>is a slug .

`linenumbers`¶

显示带行号的文本。

例如：

{{ value|linenumbers }}

如果 value 是：

one
two
three

输出将为：

one
two
three

`ljust`¶

左对齐给定宽度字段中的值。

论点： 字段大小

例如：

"{{ value|ljust:"10" }}"

如果 value 是 Django ，输出为 "Django " .

`lower`¶

将字符串转换为全部小写。

例如：

{{ value|lower }}

如果 value 是 Totally LOVING this Album! ，输出为 totally loving this album! .

`make_list`¶

返回转换为列表的值。对于字符串，它是一个字符列表。对于整数，在创建列表之前将参数强制转换为字符串。

例如：

{{ value|make_list }}

如果 value 是字符串 "Joel" ，输出将是列表 ['J', 'o', 'e', 'l'] .如果 value 是 123 ，输出将是列表 ['1', '2', '3'] .

`phone2numeric`¶

将电话号码（可能包含字母）转换为等效的数字。

输入不一定是有效的电话号码。这将很高兴地转换任何字符串。

例如：

{{ value|phone2numeric }}

如果 value 是 800-COLLECT ，输出为 800-2655328 .

`pluralize`¶

如果值不是，则返回复数后缀 1 ， '1' 或长度为1的对象。默认情况下，此后缀为 's' .

示例：

You have {{ num_messages }} message{{ num_messages|pluralize }}.

如果 num_messages is 1, the output will be You have 1 message. 如果 num_messages 是 2 输出将是 You have 2 messages.

对于需要后缀而不是 's' ，您可以提供一个可选后缀作为过滤器的参数。

示例：

You have {{ num_walruses }} walrus{{ num_walruses|pluralize:"es" }}.

对于不以简单后缀复数的单词，可以同时指定单数和复数后缀，用逗号分隔。

示例：

You have {{ num_cherries }} cherr{{ num_cherries|pluralize:"y,ies" }}.

备注

使用 blocktranslate 使翻译后的字符串复数。

`pprint`¶

包装纸 pprint.pprint() --是为了调试。

`random`¶

返回给定列表中的随机项。

例如：

{{ value|random }}

如果 value 是名单 ['a', 'b', 'c', 'd'] ，输出可以是 "b" .

`rjust`¶

右对齐给定宽度的字段中的值。

论点： 字段大小

例如：

"{{ value|rjust:"10" }}"

如果 value 是 Django ，输出为 " Django" .

`safe`¶

将字符串标记为在输出前不需要进一步的HTML转义。当自动转义关闭时，此筛选器没有效果。

备注

如果链接筛选器，则在以下位置应用筛选器 safe 会让里面的东西再次变得不安全。例如，下面的代码按原样打印未转义的变量：

{{ var|safe|escape }}

`safeseq`¶

将应用于 safe 过滤到序列的每个元素。与其他对序列进行操作的筛选器配合使用，例如 join 。例如：

{{ some_list|safeseq|join:", " }}

你不能用 safe 在这种情况下直接过滤，因为它首先将变量转换为字符串，而不是处理序列中的单个元素。

`slice`¶

返回列表切片。

使用与Python的列表切片相同的语法。有关介绍，请参阅https://diveinto.org/python3/native-datatypes.html#slicinglists。

示例：

{{ some_list|slice:":2" }}

如果 some_list 是 ['a', 'b', 'c'] ，输出为 ['a', 'b'] .

`slugify`¶

转换为ASCII。将空格转换为连字符。删除不是字母数字、下划线或连字符的字符。转换为小写。同时去掉前导空格和尾随空格。

例如：

{{ value|slugify }}

如果 value 是 "Joel is a slug" ，输出为 "joel-is-a-slug" .

`stringformat`¶

根据参数（字符串格式说明符）设置变量的格式。此说明符使用 printf-style String Formatting 语法，除去前导“%”。

例如：

{{ value|stringformat:"E" }}

如果 value 是 10 ，输出为 1.000000E+01 .

`striptags`¶

尽一切可能剥去一切 [X] HTML标签。

例如：

{{ value|striptags }}

如果 value 是 "<b>Joel</b> <button>is</button> a <span>slug</span>" ，输出为 "Joel is a slug" .

无安全保证

请注意 striptags 不保证其输出是HTML安全的，特别是对于无效的HTML输入。所以 NEVER 应用 safe 筛选器以 striptags 输出。如果您正在寻找更健壮的工具，可以考虑使用第三方的HTML清理工具。

`time`¶

根据给定格式格式化时间。

给定的格式可以是预定义的格式 TIME_FORMAT 或自定义格式，与 date 过滤器。请注意，预定义的格式取决于区域设置。

例如：

{{ value|time:"H:i" }}

如果 value 等于 datetime.datetime.now() ，输出将是字符串 "01:23" .

请注意，如果要使用“原始”值，可以对格式字符串进行反斜杠转义。在本例中，“h”和“m”都是反斜杠转义的，因为否则每个都是分别显示小时和月的格式字符串：

{{ value|time:"H\h i\m" }}

显示为“01h 23m”。

另一个例子：

假设 LANGUAGE_CODE 例如， "de" ，则为：

{{ value|time:"TIME_FORMAT" }}

输出将是字符串 "01:23" (The "TIME_FORMAT" 的格式说明符 de Django附带的区域设置为 "H:i" ）

这个 time 过滤器将只接受格式字符串中与时间相关的参数，而不是日期。如果需要格式化 date 价值，使用 date 而是过滤（或与 time 如果你需要呈现一个完整的 datetime 价值）。

上面的规则有一个例外：当通过 datetime 附加时区信息的值（A time-zone-aware datetime 实例） time 筛选器将接受与时区相关的 format specifiers 'e' ， 'O' ， 'T' 和 'Z' .

在不使用格式字符串的情况下， TIME_FORMAT 使用格式说明符：

{{ value|time }}

等同于：

{{ value|time:"TIME_FORMAT" }}

`timesince`¶

将日期格式设置为自该日期起的时间（例如，“4天，6小时”）。

接受一个可选参数，该参数是一个包含用作比较点的日期的变量(没有此参数，比较点为 now )。例如，如果 blog_date 是表示2006年6月1日午夜的Date实例，并且 comment_date 是2006年6月1日08：00的日期实例，则以下代码将返回“8小时”：

{{ blog_date|timesince:comment_date }}

比较offset naive和offset aware日期时间将返回空字符串。

分钟是使用的最小单位，对于将来相对于比较点的任何日期，都将返回“0分钟”。

`timeuntil`¶

类似 timesince 但它度量从现在到给定日期或日期时间的时间。例如，如果今天是2006年6月1日， conference_date 是2006年6月29日的日期实例，那么 {{{{ conference_date|timeuntil }}}} 将返回“4周”。

接受一个可选参数，该参数是包含用作比较点的日期的变量(而不是 now )。如果 from_date 包含2006年6月22日，则以下代码将返回“1周”：

{{ conference_date|timeuntil:from_date }}

比较offset naive和offset aware日期时间将返回空字符串。

分钟是使用的最小单位，对于过去相对于比较点的任何日期，都将返回“0分钟”。

`title`¶

通过使单词以大写字符开头，其余字符以小写字母开头，将字符串转换为标题库。这个标签不费吹灰之力地将“琐碎的单词”保持为小写。

例如：

{{ value|title }}

如果 value 是 "my FIRST post" ，输出为 "My First Post" .

`truncatechars`¶

如果字符串长度超过指定的字符数，则截断该字符串。截断的字符串将以可翻译省略号字符（“…”）结尾。

论点： 要截断到的字符数

例如：

{{ value|truncatechars:7 }}

如果 value 是 "Joel is a slug" ，输出为 "Joel i…" .

`truncatechars_html`¶

类似 truncatechars ，但它知道HTML标记。在字符串中打开但在截断点之前未关闭的所有标记在截断后立即关闭。

例如：

{{ value|truncatechars_html:7 }}

如果 value 是 "<p>Joel is a slug</p>" ，输出为 "<p>Joel i…</p>" .

将保留HTML内容中的换行符。

输入字符串的大小

处理可能存在格式错误的大型HTML字符串可能会占用大量资源，并影响服务性能。 truncatechars_html 将输入限制为前500万个字符。

Changed in Django 3.2.22:

在较早的版本中，处理的字符串超过500万个字符。

`truncatewords`¶

在一定数量的单词后截断字符串。

论点： 后面要截断的字数

例如：

{{ value|truncatewords:2 }}

如果 value 是 "Joel is a slug" ，输出为 "Joel is …" .

将删除字符串中的换行符。

`truncatewords_html`¶

类似 truncatewords ，但它知道HTML标记。在字符串中打开但在截断点之前未关闭的所有标记在截断之后立即关闭。

这比 truncatewords ，因此只能在传递HTML文本时使用。

例如：

{{ value|truncatewords_html:2 }}

如果 value 是 "<p>Joel is a slug</p>" ，输出为 "<p>Joel is …</p>" .

将保留HTML内容中的换行符。

输入字符串的大小

处理可能存在格式错误的大型HTML字符串可能会占用大量资源，并影响服务性能。 truncatewords_html 将输入限制为前500万个字符。

Changed in Django 3.2.22:

在较早的版本中，处理的字符串超过500万个字符。

`unordered_list`¶

递归地获取一个自嵌套列表并返回一个HTML无序列表--不需要打开和关闭 <ul> 标签。

假定该列表的格式正确。例如，如果 var 含 ['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']] ，那么 {{ var|unordered_list }} 会回来：

<li>States
<ul>
        <li>Kansas
        <ul>
                <li>Lawrence</li>
                <li>Topeka</li>
        </ul>
        </li>
        <li>Illinois</li>
</ul>
</li>

`upper`¶

将字符串转换为全部大写。

例如：

{{ value|upper }}

如果 value 是 "Joel is a slug" ，输出为 "JOEL IS A SLUG" .

`urlencode`¶

转义一个值以在URL中使用。

例如：

{{ value|urlencode }}

如果 value 是 "https://www.example.org/foo?a=b&c=d" ，输出为 "https%3A//www.example.org/foo%3Fa%3Db%26c%3Dd" .

可以提供包含不应转义的字符的可选参数。

如果未提供，则假定‘/’字符是安全的。在以下情况下可以提供空字符串 all 应对字符进行转义。例如：

{{ value|urlencode:"" }}

如果 value 是 "https://www.example.org/" ，输出为 "https%3A%2F%2Fwww.example.org%2F" .

`urlize`¶

将文本中的URL和电子邮件地址转换为可单击的链接。

此模板标记用于前缀为的链接 http:// ， https:// 或 www. . 例如， https://goo.gl/aia1t 将被转换，但 goo.gl/aia1t 不会。

它还支持以原始顶级域之一结尾的仅域链接 (.com ， .edu ， .gov ， .int ， .mil ， .net 和 .org ）例如， djangoproject.com 转换。

链接可以有尾随标点（句点、逗号、右括号）和前导标点（左括号），以及 urlize 仍然会做正确的事情。

链接生成者 urlize 有一个 rel="nofollow" 属性添加到它们。

例如：

{{ value|urlize }}

如果 value 是 "Check out www.djangoproject.com" ，输出为 "Check out <a href="http://www.djangoproject.com" rel="nofollow">www.djangoproject.com</a>" .

除了网络链接外， urlize 同时将电子邮件地址转换为 mailto: 链接。如果 value 是 "Send questions to foo@example.com" ，输出为 "Send questions to <a href="mailto:foo@example.com">foo@example.com</a>" .

这个 urlize 过滤器还接受可选参数 autoescape .如果 autoescape 是 True ，链接文本和URL将使用Django内置的 escape 过滤器。的默认值 autoescape 是 True .

备注

如果 urlize 应用于已包含HTML标记的文本，或应用于包含单引号的电子邮件地址 (' ）事情不会像预期的那样成功。仅对纯文本应用此筛选器。

`urlizetrunc`¶

将URL和电子邮件地址转换为可单击的链接，就像 urlize, 但截断的URL长度超过了给定的字符限制。

论点： 链接文本应截断到的字符数，包括在需要截断时添加的省略号。

例如：

{{ value|urlizetrunc:15 }}

如果 value 是 "Check out www.djangoproject.com" ，输出为 'Check out <a href="http://www.djangoproject.com" rel="nofollow">www.djangoproj…</a>' .

和一样 urlize, 此筛选器只能应用于纯文本。

`wordcount`¶

返回字数。

例如：

{{ value|wordcount }}

如果 value 是 "Joel is a slug" ，输出为 4 .

`wordwrap`¶

以指定的行长度换行。

论点： 文本换行的字符数

例如：

{{ value|wordwrap:5 }}

如果 value 是 Joel is a slug ，则输出将为：

Joel
is a
slug

`yesno`¶

映射值 True ， False 和（可选） None ，返回字符串“yes”、“no”、“maybe”或作为逗号分隔列表传递的自定义映射，并根据值返回这些字符串之一：

例如：

{{ value|yesno:"yeah,no,maybe" }}

价值	论证	输出
`True`		`yes`
`True`	`"yeah,no,maybe"`	`yeah`
`False`	`"yeah,no,maybe"`	`no`
`None`	`"yeah,no,maybe"`	`maybe`
`None`	`"yeah,no"`	`no` （皈依者） `None` 到 `False` 如果没有映射 `None` 给出）

国际化标记和过滤器¶

Django提供了模板标签和过滤器来控制 internationalization 在模板中。它们允许对翻译、格式化和时区转换进行粒度控制。

`i18n`¶

此库允许在模板中指定可翻译文本。要启用它，请设置 USE_I18N 到 True ，然后加载 {{% load i18n %}} .

见国际化：在模板代码中 .

`l10n`¶

该库提供了对模板中值的本地化的控制。您只需使用以下命令加载库 {% load l10n %} 。

见控制模板中的本地化 .

`tz`¶

此库提供对模板中时区转换的控制。喜欢 l10n ，您只需要使用 {{% load tz %}} 但是你通常也会 USE_TZ 到 True 所以默认情况下转换为本地时间。

见模板中的时区感知输出 .

其他标记和筛选器库¶

Django附带了一些其他模板标记库，您必须在 INSTALLED_APPS 在模板中设置和启用 {{% load %}} 标签。

`django.contrib.humanize`¶

一组Django模板过滤器，用于向数据添加“人工触摸”。见 django.contrib.humanize .

`static`¶

链接到保存在中的静态文件 STATIC_ROOT Django出货时配备了一台 static 模板标签。如果 django.contrib.staticfiles 应用程序安装后，该标记将使用 url() 指定的存储方法的 staticfiles 在……里面 STORAGES 。例如：

{% load static %}
<img src="{% static 'images/hi.jpg' %}" alt="Hi!">

它还能够使用标准上下文变量，例如，假设 user_stylesheet 变量被传递给模板：

{% load static %}
<link rel="stylesheet" href="{% static user_stylesheet %}" media="screen">

如果您希望检索静态URL而不显示它，您可以使用稍微不同的调用：

{% load static %}
{% static "images/hi.jpg" as myphoto %}
<img src="{{ myphoto }}">

使用jinja2模板？

见 Jinja2 有关使用的信息 static 用金贾2标记。

`get_static_prefix`¶

您应该更喜欢 static 模板标记，但如果您需要更多地控制确切的位置和方式 STATIC_URL 注入到模板中，则可以使用 get_static_prefix 模板标签：

{% load static %}
<img src="{% get_static_prefix %}images/hi.jpg" alt="Hi!">

如果多次需要该值，还可以使用第二个表单来避免额外的处理：

{% load static %}
{% get_static_prefix as STATIC_PREFIX %}

<img src="{{ STATIC_PREFIX }}images/hi.jpg" alt="Hi!">
<img src="{{ STATIC_PREFIX }}images/hi2.jpg" alt="Hello!">

`get_media_prefix`¶

类似于 get_static_prefix ， get_media_prefix 使用媒体前缀填充模板变量 MEDIA_URL ，例如：

{% load static %}
<body data-media-url="{% get_media_prefix %}">

通过将值存储在一个数据属性中，我们可以确保如果我们想在JavaScript上下文中使用它，可以对其进行适当的转义。

« previous | up | next »

Django 5.1.dev 文档

内置模板标记和筛选器¶

内置标记引用¶

autoescape¶

block¶

comment¶

csrf_token¶

cycle¶

debug¶

extends¶

filter¶

firstof¶

for¶

for ... empty¶

if¶

布尔运算符¶

== 操作人员¶

!= 操作人员¶

< 操作人员¶

> 操作人员¶

<= 操作人员¶

>= 操作人员¶

in 操作人员¶

not in 操作人员¶

is 操作人员¶

is not 操作人员¶

过滤器¶

复杂表达式¶

ifchanged¶

include¶

load¶

lorem¶

now¶

query_string¶

regroup¶

按其他属性分组¶

resetcycle¶

spaceless¶

templatetag¶

url¶

verbatim¶

widthratio¶

with¶

内置筛选器引用¶

add¶

addslashes¶

capfirst¶

center¶

cut¶

date¶

default¶

default_if_none¶

dictsort¶

dictsortreversed¶

divisibleby¶

escape¶

escapejs¶

escapeseq¶

filesizeformat¶

first¶

floatformat¶

force_escape¶

get_digit¶

iriencode¶

join¶

json_script¶

last¶

length¶

linebreaks¶

linebreaksbr¶

linenumbers¶

ljust¶

lower¶

make_list¶

phone2numeric¶

pluralize¶

pprint¶

random¶

rjust¶

safe¶

`autoescape`¶

`block`¶

`comment`¶

`csrf_token`¶

`cycle`¶

`debug`¶

`extends`¶

`filter`¶

`firstof`¶

`for`¶

`for` ... `empty`¶

`if`¶

`==` 操作人员¶

`!=` 操作人员¶

`<` 操作人员¶

`>` 操作人员¶

`<=` 操作人员¶

`>=` 操作人员¶

`in` 操作人员¶

`not in` 操作人员¶

`is` 操作人员¶

`is not` 操作人员¶

`ifchanged`¶

`include`¶

`load`¶

`lorem`¶

`now`¶

`query_string`¶

`regroup`¶

`resetcycle`¶

`spaceless`¶

`templatetag`¶

`url`¶

`verbatim`¶

`widthratio`¶

`with`¶

`add`¶

`addslashes`¶

`capfirst`¶

`center`¶

`cut`¶

`date`¶

`default`¶

`default_if_none`¶

`dictsort`¶

`dictsortreversed`¶

`divisibleby`¶

`escape`¶

`escapejs`¶

`escapeseq`¶

`filesizeformat`¶

`first`¶

`floatformat`¶

`force_escape`¶

`get_digit`¶

`iriencode`¶

`join`¶

`json_script`¶

`last`¶

`length`¶

`linebreaks`¶

`linebreaksbr`¶

`linenumbers`¶

`ljust`¶

`lower`¶

`make_list`¶

`phone2numeric`¶

`pluralize`¶

`pprint`¶

`random`¶

`rjust`¶

`safe`¶

`safeseq`¶

`slice`¶

`slugify`¶

`stringformat`¶

`striptags`¶

`time`¶

`timesince`¶

`timeuntil`¶