内置模板标签和过滤器

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

内置标签参考

autoescape

控制当前的自动转义行为。此标签将 on 或 off 作为参数，并确定自动转义是否在块内生效。该块以 endautoescape 结束标记结束。

当自动转义生效时，所有变量内容都会在将结果放入输出之前（但在应用任何过滤器之后）应用 HTML 转义。这相当于手动将 :tfilter:`escape` 过滤器应用于每个变量。

唯一的例外是已经被标记为“安全”的变量，无论是通过填充变量的代码，还是因为它有 :tfilter:`safe` 或 :tfilter：应用了`escape` 过滤器。

示例用法：

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

block

定义一个可以被子模板覆盖的块。有关更多信息，请参阅模板继承。

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 保护，如跨站点请求伪造的文档中所述。

cycle

每次遇到此标记时生成其参数之一。第一个参数在第一次相遇时产生，第二个参数在第二次相遇时产生，依此类推。一旦所有参数都用完，标签就会循环到第一个参数并再次生成它。

这个标签在循环中特别有用：

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

第一次迭代生成引用类 row1 的 HTML，第二次引用 row2，第三次再次生成引用 row1 的 HTML，如此循环的每次迭代。

您也可以使用变量。例如，如果您有两个模板变量，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 %}

在某些情况下，您可能希望引用循环的当前值而不前进到下一个值。为此，请使用“as”为 {% cycle %} 标签命名，如下所示：

{% 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 关键字时，静音会自动应用于该特定循环标签的所有后续使用。以下模板将输出 nothing，即使第二次调用 {% cycle %} 未指定 silent：

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

您可以使用 :ttag:`resetcycle` 标记使 {% cycle %} 标记在下次遇到时从其第一个值重新启动。

debug

输出一整套调试信息，包括当前上下文和导入的模块。

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

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

请注意，该块包括 filter 和 endfilter 标签之间的文本 all。

示例用法：

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

笔记

:tfilter:`escape` 和 :tfilter:`safe` 过滤器是不可接受的参数。相反，使用 :ttag:`autoescape` 标签来管理模板代码块的自动转义。

firstof

输出第一个不为“假”的参数变量（即存在，不为空，不是假布尔值，也不是零数值）。如果所有传递的变量都为“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 的 (x,y) 坐标列表，您可以使用以下命令输出点列表：

{% 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 等），请避免添加名称类似于字典方法的键。在模板变量的文档中阅读有关点运算符查找顺序的更多信息。

for 循环在循环中设置了许多可用的变量：

变量	说明
`forloop.counter`	循环的当前迭代（1-indexed）
`forloop.counter0`	循环的当前迭代（0 索引）
`forloop.revcounter`	从循环结束开始的迭代次数（1-indexed）
`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变量显示。

如您所见，if 标签可能包含一个或多个 {% elif %} 子句，以及一个 {% else %} 子句，如果前面的所有条件都失败，则会显示该子句。这些条款是可选的。

布尔运算符

:ttag:`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

在 :ttag:`if` 标签中使用实际括号是无效的语法。如果您需要它们来表示优先级，您应该使用嵌套的 :ttag:`if` 标签。

:ttag:`if` 标签也可以使用运算符 ==、!=、<、>、[ X100X]、>=、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 %}

过滤器

您还可以在 :ttag:`if` 表达式中使用过滤器。例如：

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

复杂的表达

以上所有内容都可以组合成复杂的表达式。对于此类表达式，了解在计算表达式时如何对运算符进行分组非常重要——即优先规则。运算符的优先级从低到高依次为：

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

（这完全遵循 Python）。因此，例如，以下复杂的 :ttag:`if` 标记：

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

……将被解释为：

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

如果您需要不同的优先级，则需要使用嵌套的 :ttag:`if` 标签。有时，为了那些不知道优先规则的人，无论如何，为了清楚起见，这样做会更好。

比较运算符不能像 Python 或数学符号那样“链接”。例如，而不是使用：

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

你应该使用：

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

ifequal 和 ifnotequal

自 3.1 版起已弃用。

{% ifequal a b %} ... {% endifequal %} 是一种过时的写法 {% if a == b %} ... {% endif %}。同样，{% ifnotequal a b %} ... {% endifnotequal %} 被 {% if a != b %} ... {% endif %} 取代。

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" %}

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

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

{% include template_name %}

该变量也可以是具有接受上下文的 render() 方法的任何对象。这允许您在上下文中引用已编译的 Template。

此外，变量可能是模板名称的可迭代对象，在这种情况下，将使用第一个可以加载的，根据 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 %}

笔记

:ttag:`include` 标签应该被视为“呈现这个子模板并包含 HTML”的实现，而不是“解析这个子模板并包含它的内容，就好像它是父模板的一部分” . 这意味着包含的模板之间没有共享状态——每个包含都是一个完全独立的渲染过程。

块在 被包含之前被评估 。这意味着包含来自另一个块的模板将包含已经 已经被评估和渲染 的块 - 而不是可以被例如扩展模板覆盖的块。

3.1 版更改：添加了对模板名称可迭代的支持。

load

加载自定义模板标签集。

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

{% load somelibrary package.otherlibrary %}

您还可以使用 from 参数有选择地从库中加载单个过滤器或标签。在这个例子中，名为 foo 和 bar 的模板标签/过滤器将从 somelibrary 加载：

{% load foo bar from somelibrary %}

有关详细信息，请参阅自定义标记和过滤器库。

lorem

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

用法：

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

{% lorem %} 标签可以与零、一、二或三个参数一起使用。论据是：

论据	说明
`count`	包含要生成的段落或单词数的数字（或变量）（默认为 1）。
`method`	`w` 表示文字，`p` 表示 HTML 段落或 `b` 表示纯文本段落块（默认为 `b`）。
`random`	单词 `random`，如果给出，在生成文本时不使用通用段落（“Lorem ipsum dolor sat amet...”）。

例子：

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

now

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

例子：

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

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

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

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

笔记

传递的格式也可以是预定义的格式之一 :setting:`DATE_FORMAT`, :setting:`DATETIME_FORMAT`, :setting:`SHORT_DATE_FORMAT` 或：设置：`SHORT_DATETIME_FORMAT`。预定义的格式可能会根据当前的语言环境以及格式本地化是否启用而有所不同，例如：

It is {% now "SHORT_DATETIME_FORMAT" %}

您还可以使用语法 {% now "Y" as current_year %} 将输出（作为字符串）存储在变量中。如果你想在像 :ttag:`blocktranslate` 这样的模板标签中使用 {% now %}，这很有用，例如：

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

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'},
]

…并且您想显示按国家/地区排序的分层列表，如下所示：

印度
- 孟买：19,000,000
- 加尔各答：15,000,000
美国
- 纽约：20,000,000
- 芝加哥：7,000,000
日本
- 东京：33,000,000

您可以使用 {% 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 %} 接受三个参数：要重新分组的列表、要分组的属性以及结果列表的名称。在这里，我们通过 country 属性重新组合 cities 列表并调用结果 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 列表不是按 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 %} 模板代码将产生以下输出：

印度
- 孟买：19,000,000
美国
- 纽约：20,000,000
印度
- 加尔各答：15,000,000
美国
- 芝加哥：7,000,000
日本
- 东京：33,000,000

解决这个问题的最简单的方法是确保在你的视图代码中数据是根据你想要的显示方式排序的。

另一个解决方案是使用 :tfilter:`dictsort` 过滤器对模板中的数据进行排序，如果您的数据在字典列表中：

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

在其他属性上分组

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

{% 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

重置前一个循环，以便它在下一次遇到时从第一项重新开始。如果没有参数，{% 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>José Mourinho</h1>
<p class="odd">Thibaut Courtois</p>
<p class="even">John Terry</p>
<p class="odd">Eden Hazard</p>

<h1>Carlo Ancelotti</h1>
<p class="odd">Manuel Neuer</p>
<p class="even">Thomas Müller</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>

仅删除了标签之间的空格——而不是标签和文本之间的空格。在这个例子中， Hello 周围的空间不会被剥离：

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

templatetag

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

由于模板系统没有“转义”的概念，要显示模板标签中使用的位之一，必须使用{% templatetag %}标签。

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

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

示例用法：

{% templatetag openblock %} url 'entry_list' {% templatetag closeblock %}

url

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

这是一种无需在模板中硬编码 URL 即可在不违反 DRY 原则的情况下输出链接的方法：

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

第一个参数是 URL 模式名称。它可以是带引号的文字或任何其他上下文变量。附加参数是可选的，应该是空格分隔的值，将用作 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' %}

这将遵循正常的命名空间 URL 解析策略，包括使用上下文提供的有关当前应用程序的任何提示。

警告

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

verbatim

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

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

{% 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 = .875; . 875 * 100 = 87.5，四舍五入为 88）。

在某些情况下，您可能希望在变量中捕获 widthratio 的结果。例如，它可以用于 :ttag:`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]。

警告

可以强制为整数的字符串将是 summed，而不是连接，如上面的第一个示例。

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 兼容，以简化设计人员的过渡。

可用的格式字符串：

格式字符	说明	示例输出
日
`d`	月份中的第几天，带前导零的 2 位数字。	`'01'` 至 `'31'`
`j`	一个月中没有前导零的日期。	`'1'` 至 `'31'`
`D`	星期几，文本，3 个字母。	`'Fri'`
`l`	星期几，文本，长。	`'Friday'`
`S`	月份日期的英文序数后缀，2 个字符。	`'st'`、`'nd'`、`'rd'` 或 `'th'`
`w`	星期几，没有前导零的数字。	`'0'`（星期日）至 `'6'`（星期六）
`z`	一年中的一天。	`1` 至 `366`
星期
`W`	ISO-8601 年的周数，周从星期一开始。	`1`、`53`
月
`m`	月份，带前导零的 2 位数字。	`'01'` 至 `'12'`
`n`	没有前导零的月份。	`'1'` 至 `'12'`
`M`	月份，文本，3 个字母。	`'Jan'`
`b`	月份，文本，3 个字母，小写。	`'jan'`
`E`	月份，特定于语言环境的替代表示通常用于长日期表示。	`'listopada'`（波兰语语言环境，相对于 `'Listopad'`）
`F`	月，文字，长。	`'January'`
`N`	美联社风格的月份缩写。专有扩展。	`'Jan.'`、`'Feb.'`、`'March'`、`'May'`
`t`	给定月份的天数。	`28` 至 `31`
年
`y`	年份，带前导零的 2 位数字。	`'00'` 至 `'99'`
`Y`	年份，4 位数字。	`'1999'`
`L`	布尔值是否是闰年。	`True` 或 `False`
`o`	ISO-8601 周编号年份，对应使用闰周的 ISO-8601 周编号 (W)。有关更常见的年份格式，请参阅 Y。	`'1999'`
时间
`g`	小时、12 小时格式，不带前导零。	`'1'` 至 `'12'`
`G`	小时、24 小时格式，不带前导零。	`'0'` 至 `'23'`
`h`	小时、12 小时格式。	`'01'` 至 `'12'`
`H`	小时，24 小时格式。	`'00'` 至 `'23'`
`i`	分钟。	`'00'` 至 `'59'`
`s`	秒，带前导零的 2 位数字。	`'00'` 至 `'59'`
`u`	微秒。	`000000` 至 `999999`
`a`	`'a.m.'` 或 `'p.m.'`（请注意，这与 PHP 的输出略有不同，因为这包括与美联社风格相匹配的句点。）	`'a.m.'`
`A`	`'AM'` 或 `'PM'`。	`'AM'`
`f`	时间，以 12 小时制的小时和分钟表示，如果它们为零，则分钟数会停止。专有扩展。	`'1'`、`'1:30'`
`P`	时间，以 12 小时制小时、分钟和 'am'/'pm' 表示，如果分钟为零，则离开，特殊情况下的字符串 'midnight' 和 'noon'（如果合适）。专有扩展。	`'1 a.m.'`、`'1:30 p.m.'`、`'midnight'`、`'noon'`、`'12:30 p.m.'`
时区
`e`	时区名称。可以是任何格式，也可以返回空字符串，具体取决于日期时间。	、`'GMT'`、`'-500'`、`'US/Eastern'`等
`I`	夏令时，无论是否生效。	`'1'` 或 `'0'`
`O`	与格林威治时间的时差。	`'+0200'`
`T`	本机的时区。	`'EST'`、`'MDT'`
`Z`	时区偏移量（以秒为单位）。 UTC 以西时区的偏移量始终为负，UTC 以东时区的偏移量始终为正。	`-43200` 至 `43200`
约会时间
`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 纪元（UTC 时间 1970 年 1 月 1 日 00:00:00）以来的秒数。

例如：

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

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

传递的格式可以是预定义的格式之一 :setting:`DATE_FORMAT`、:setting:`DATETIME_FORMAT`、:setting:`SHORT_DATE_FORMAT` 或 [ X163X]:setting:`SHORT_DATETIME_FORMAT`，或使用上表中显示的格式说明符的自定义格式。请注意，预定义格式可能因当前语言环境而异。

假设 :setting:`USE_L10N` 是 True 并且 :setting:`LANGUAGE_CODE` 是，例如，"es"，那么对于：

{{ value|date:"SHORT_DATE_FORMAT" }}

输出将是字符串 "09/01/2008"（Django 附带的 es 语言环境的 "SHORT_DATE_FORMAT" 格式说明符是 "d/m/Y"）。

当不带格式字符串使用时，使用 DATE_FORMAT 格式说明符。假设设置与上一个示例相同：

{{ value|date }}

输出 9 de Enero de 2008（es 语言环境的 DATE_FORMAT 格式说明符是 r'j \d\e F \d\e Y'）。 “d”和“e”都是反斜杠转义的，否则每个都是一个格式字符串，分别显示日期和时区名称。

您可以将 date 与 :tfilter:`time` 过滤器结合使用，以呈现 datetime 值的完整表示。例如：

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

default

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

例如：

{{ value|default:"nothing" }}

如果 value 为 ""（空字符串），则输出为 nothing。

default_if_none

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

请注意，如果给出空字符串，则将使用默认值不。如果要回退空字符串，请使用 :tfilter:`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。具体来说，它进行了这些替换：

< 转换为 <
> 转换为 >
'（单引号）转换为'
"（双引号）转换为 "
& 转换为 &

将 escape 应用于通常会对结果应用自动转义的变量只会导致进行一轮转义。因此，即使在自动转义环境中使用此功能也是安全的。如果要应用多个转义通道，请使用 :tfilter:`force_escape` 过滤器。

例如，当 :ttag:`autoescape` 关闭时，您可以将 escape 应用于字段：

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

escapejs

转义字符以用于 JavaScript 字符串。这确实 而不是 使字符串可以安全地用于 HTML 或 JavaScript 模板文字，但在使用模板生成 JavaScript/JSON 时确实可以保护您免受语法错误的影响。

例如：

{{ value|escapejs }}

如果 value 为 "testing\r\njavascript 'string\" <b>escaping</b>"，则输出将为 "testing\\u000D\\u000Ajavascript \\u0027string\\u0022 \\u003Cb\\u003Eescaping\\u003C/b\\u003E"。

filesizeformat

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

例如：

{{ value|filesizeformat }}

如果 value 为 123456789，则输出将为 117.7 MB。

文件大小和 SI 单位

严格来说，filesizeformat 不符合推荐使用 KiB、MiB、GiB 等的国际单位制。当字节大小以 1024 的幂计算时（这里就是这种情况）。相反，Django 使用与更常用的名称相对应的传统单元名称（KB、MB、GB 等）。

first

返回列表中的第一项。

例如：

{{ value|first }}

如果 value 是列表 ['a', 'b', 'c']，则输出将为 'a'。

floatformat

在不带参数的情况下使用时，将浮点数四舍五入到一位小数——但前提是要显示小数部分。例如：

`value`	模板	输出
`34.23234`	`模板:Value`	`34.2`
`34.00000`	`模板:Value`	`34`
`34.26000`	`模板:Value`	`34.3`

如果与数字整数参数一起使用，floatformat 会将数字四舍五入到那么多小数位。例如：

`value`	模板	输出
`34.23234`	`模板:Value`	`34.232`
`34.00000`	`模板:Value`	`34.000`
`34.26000`	`模板:Value`	`34.260`

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

`value`	模板	输出
`34.23234`	`模板:Value`	`34`
`34.00000`	`模板:Value`	`34`
`39.56000`	`模板:Value`	`40`

如果传递给 floatformat 的参数是负数，它会将一个数字四舍五入到那么多小数位——但前提是有一个小数部分要显示。例如：

`value`	模板	输出
`34.23234`	`模板:Value`	`34.232`
`34.00000`	`模板:Value`	`34`
`34.26000`	`模板:Value`	`34.260`

如果传递给 floatformat 的参数具有 g 后缀，它将强制按 :setting:`THOUSAND_SEPARATOR` 对活动语言环境进行分组。例如，当活动语言环境为 en（英文）时：

`value`	模板	输出
`34232.34`	`模板:Value`	`34,232.34`
`34232.06`	`模板:Value`	`34,232.1`
`34232.00`	`模板:Value`	`34,232`

使用不带参数的 floatformat 等效于使用带 -1 的参数的 floatformat。

3.1 版更改：在旧版本中，对于舍入为零的负数，返回负零 -0。

3.2 版更改：添加了 g 后缀以强制按千位分隔符分组。

force_escape

将 HTML 转义应用于字符串（有关详细信息，请参阅 :tfilter:`escape` 过滤器）。此过滤器立即应用 ' 并返回一个新的转义字符串。这在您需要多次转义或希望将其他过滤器应用于转义结果的极少数情况下非常有用。通常，您想使用 :tfilter:`escape` 过滤器。

例如，如果您想捕获由 :tfilter:`linebreaks` 过滤器创建的 <p> HTML 元素：

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

get_digit

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

例如：

{{ value|get_digit:"2" }}

如果 value 为 123456789，则输出将为 8。

iriencode

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

在已经通过 :tfilter:`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 一起使用。

参数： <script> 标签的 HTML “id”。

例如：

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

length_is

如果值的长度是参数，则返回 True，否则返回 False。

例如：

{{ value|length_is:"4" }}

如果 value 为 ['a', 'b', 'c', 'd'] 或 "abcd"，则输出将为 True。

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为1时，输出为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" }}.

笔记

使用 :ttag:`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

将 :tfilter:`safe` 过滤器应用于序列的每个元素。与其他对序列进行操作的过滤器结合使用非常有用，例如 :tfilter:`join`。例如：

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

在这种情况下，您不能直接使用 :tfilter:`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

根据参数（字符串格式说明符）格式化变量。此说明符使用 old-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 输出。如果您正在寻找更强大的东西，您可以使用 bleach Python 库，特别是它的 clean 方法。

time

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

给定格式可以是预定义的 :setting:`TIME_FORMAT`，也可以是自定义格式，与 :tfilter:`date` 过滤器相同。请注意，预定义格式取决于语言环境。

例如：

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

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

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

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

这将显示为“01h 23m”。

另一个例子：

假设 :setting:`USE_L10N` 是 True 并且 :setting:`LANGUAGE_CODE` 是，例如，"de"，那么对于：

{{ value|time:"TIME_FORMAT" }}

输出将是字符串 "01:23"（Django 附带的 de 语言环境的 "TIME_FORMAT" 格式说明符是 "H:i"）。

time 过滤器将只接受格式字符串中与时间相关的参数，而不是日期。如果您需要格式化 date 值，请改用 :tfilter:`date` 过滤器（如果需要，也可以使用 :tfilter:`time`渲染一个完整的 datetime 值）。

上述规则有一个例外：当传递带有附加时区信息的 datetime 值（time-zone-aware datetime 实例）时，time filter 将接受与时区相关的格式说明符 'e'、'O'、'T' 和 'Z'。

当不带格式字符串使用时，使用 TIME_FORMAT 格式说明符：

{{ value|time }}

是相同的：

{{ value|time:"TIME_FORMAT" }}

timesince

将日期格式化为自该日期以来的时间（例如，“4 天 6 小时”）。

接受一个可选参数，该参数是一个包含用作比较点的日期的变量（没有参数，比较点是 now）。例如，如果 blog_date 是代表 2006 年 6 月 1 日午夜的日期实例，而 comment_date 是代表 2006 年 6 月 1 日 08:00 的日期实例，则以下将返回“8 hours” ：

{{ blog_date|timesince:comment_date }}

比较偏移天真和偏移感知日期时间将返回一个空字符串。

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

timeuntil

类似于 timesince，除了它测量从现在到给定日期或日期时间的时间。例如，如果今天是 2006 年 6 月 1 日，而 conference_date 是持有 2006 年 6 月 29 日的日期实例，那么 模板:Conference date 将返回“4 周”。

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

{{ conference_date|timeuntil:from_date }}

比较偏移天真和偏移感知日期时间将返回一个空字符串。

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

title

通过使单词以大写字符开头，其余字符小写，将字符串转换为 titlecase。这个标签不努力将“琐碎的词”保持为小写。

例如：

{{ value|title }}

如果 value 为 "my FIRST post"，则输出将为 "My First Post"。

truncatechars

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

Argument: 要截断的字符数

例如：

{{ value|truncatechars:7 }}

如果 value 为 "Joel is a slug"，则输出将为 "Joel i…"。

truncatechars_html

类似于 :tfilter:`truncatechars`，除了它知道 HTML 标签。任何在字符串中打开但在截断点之前未关闭的标记在截断后立即关闭。

例如：

{{ value|truncatechars_html:7 }}

如果 value 为 "<p>Joel is a slug</p>"，则输出将为 "<p>Joel i…</p>"。

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

truncatewords

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

Argument: 要截断的字数

例如：

{{ value|truncatewords:2 }}

如果 value 为 "Joel is a slug"，则输出将为 "Joel is …"。

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

truncatewords_html

与 :tfilter:`truncatewords` 类似，除了它知道 HTML 标签。任何在字符串中打开但在截断点之前没有关闭的标签，在截断后立即关闭。

这比 :tfilter:`truncatewords` 效率低，所以应该只在传递 HTML 文本时使用。

例如：

{{ value|truncatewords_html:2 }}

如果 value 为 "<p>Joel is a slug</p>"，则输出将为 "<p>Joel is …</p>"。

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

unordered_list

递归地获取一个自嵌套列表并返回一个 HTML 无序列表——无需打开和关闭

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%22，则输出将为 "https%3A//www.example.org/foo%3Fa%3Db%26c%3Dd"。

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

如果未提供，则假定“/”字符是安全的。当 all 字符应该被转义时，可以提供一个空字符串。例如：

{{ value|urlencode:"" }}

如果 value 为 "https://www.example.org/%22，则输出将为 "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%22 rel="nofollow">www.djangoproject.com</a>"。

除了网页链接，urlize 还可以将电子邮件地址转换为 mailto: 链接。如果 value 为 "Send questions to foo@example.com"，则输出将为 "Send questions to <a href="mailto:foo@example.com%22>foo@example.com</a>"。

urlize 过滤器还带有一个可选参数 autoescape。如果 autoescape 是 True，链接文本和 URL 将使用 Django 的内置 :tfilter:`escape` 过滤器进行转义。 autoescape 的默认值为 True。

笔记

如果将 urlize 应用于已包含 HTML 标记的文本，或应用于包含单引号 (') 的电子邮件地址，则不会按预期工作。仅将此过滤器应用于纯文本。

urlizetrunc

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

Argument: 链接文本应该被截断到的字符数，包括在需要截断时添加的省略号。

例如：

{{ value|urlizetrunc:15 }}

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

与 urlize 一样，此过滤器应仅应用于纯文本。

wordcount

返回字数。

例如：

{{ value|wordcount }}

如果 value 为 "Joel is a slug"，则输出将为 4。

wordwrap

以指定的行长换行。

Argument: 文本换行的字符数

例如：

{{ 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` 的映射，则将 `None` 转换为 `False`）

国际化标签和过滤器

Django 提供模板标签和过滤器来控制模板中国际化的各个方面。它们允许对翻译、格式和时区转换进行精细控制。

i18n

该库允许在模板中指定可翻译文本。要启用它，请将 :setting:`USE_I18N` 设置为 True，然后使用 {% load i18n %} 加载它。

参见国际化：在模板代码中。

l10n

该库提供对模板中值的本地化的控制。您只需要使用 {% load l10n %} 加载库，但您经常将 :setting:`USE_L10N` 设置为 True，以便本地化默认处于活动状态。

请参阅在模板中控制本地化。

tz

该库提供对模板中时区转换的控制。像l10n一样，你只需要使用{% load tz %}加载库，但你通常也会设置:setting:`USE_TZ`为True所以默认情况下会转换为本地时间。

请参阅模板中的时区感知输出。

其他标签和过滤器库

Django 附带了一些其他模板标签库，您必须在您的：设置：`INSTALLED_APPS` 使用 :ttag:`{% 加载 %} ` 标签。

django.contrib.humanize

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

static

要链接到保存在 :setting:`STATIC_ROOT` 中的静态文件，Django 附带了一个 :ttag:`static` 模板标签。如果安装了 django.contrib.staticfiles 应用程序，标签将使用 :setting:`STATICFILES_STORAGE` 指定的存储的 url() 方法提供文件。例如：

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

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

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

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

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

使用 Jinja2 模板？

有关在 Jinja2 中使用 static 标签的信息，请参阅 Jinja2。

get_static_prefix

您应该更喜欢 :ttag:`static` 模板标签，但是如果您需要更多地控制 :setting:`STATIC_URL` 注入模板的位置和方式，您可以使用 :ttag:`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

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

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

通过将值存储在数据属性中，如果我们想在 JavaScript 上下文中使用它，我们可以确保它被适当地转义。

内置模板标签和过滤器 — Django 文档

内置模板标签和过滤器

内置标签参考

autoescape

block

comment

csrf_token

cycle

debug

extends

filter

firstof

for

for … empty

if

布尔运算符

== 运算符

!= 运算符

< 运算符

> 运算符

<= 运算符

>= 运算符

in 运算符

not in 运算符

is 运算符

is not 运算符

过滤器

复杂的表达

ifequal 和 ifnotequal

ifchanged

include

load

lorem

now

regroup

在其他属性上分组

resetcycle

spaceless

templatetag

url

verbatim

widthratio

with

内置过滤器参考

add

addslashes

capfirst

center

cut

date

default

default_if_none

dictsort

dictsortreversed

divisibleby

escape

escapejs

filesizeformat

first

floatformat

force_escape

get_digit

iriencode

join

json_script

last

length

length_is

linebreaks

linebreaksbr

linenumbers

ljust

lower

make_list

phone2numeric

pluralize

pprint

random

rjust

safe