Django内置模板标签

时间 2019-11-26

原文原文链接

Django内置标签总览

能够查询下表来总览Django的内置标签：html

标签	说明
autoescape	自动转义开关
block	块引用
comment	注释
csrf_token	CSRF令牌
cycle	循环对象的值
debug	调试模式
extends	继承模版
filter	过滤功能
firstof	输出第一个不为False的参数
for	循环对象
for … empty	带empty说明的循环
if	条件判断
ifequal	若是等于
ifnotequal	若是不等于
ifchanged	若是有变化，则..
include	导入子模版的内容
load	加载标签和过滤器
lorem	生成无用的废话
now	当前时间
regroup	根据对象重组集合
resetcycle	重置循环
spaceless	去除空白
templatetag	转义模版标签符号
url	获取url字符串
verbatim	禁用模版引擎
widthratio	宽度比例
with	上下文变量管理器

1. autoescape

控制自动转义是否可用。参数是on或off。该标签会以一个endautoescape做为结束标签.数据库

例如：django

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

2. block

block标签能够被子模板覆盖。缓存

3. comment

在{% comment %}和{% endcomment %}之间的内容会被忽略，做为注释。app

好比，当要注释掉一些代码时，能够用此来记录代码被注释掉的缘由。less

例如：dom

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

comment标签不能嵌套使用。oop

4. csrf_token

这个标签用于跨站请求伪造保护。经常使用于为form表单提供csrf令牌。测试

5. cycle

每当这个标签被访问,返回它的下一个元素。第一次访问返回第一个元素,第二次访问返回第二个参数,以此类推. 一旦全部的变量都被访问过了，就会回到最开始的地方，重复下去。这个标签在循环中特别有用:this

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

第一次迭代产生的HTML引用了row1类，第二次则是row2类，第三次又是row1 类，如此类推。

cycle的本质是根据某个规律，提供某种特性，好比想循环给表格的行添加底色等等。

也可使用变量，例如，若是你有两个模版变量：rowvalue1和rowvalue2, 可让他们的值像这样替换:

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

被包含在cycle中的变量将会被转义。能够禁止自动转义:

{% 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 标签中，经过空格分割，可使用任意数量的值。被包含在单引号(')或者双引号(")中的值被认为是可迭代字符串，相反，没有被引号包围的值被看成模版变量。

6. debug

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

7. extends

表示当前模板继承自一个父模板。

这个标签能够有两种用法:

{% extends "base.html" %}：继承名为"base.html"的父模板
{％ extends variable ％}:使用variable变量表示的模版

Django1.10中添加了使用相对路径的能力。一般模板名称是相对于模板加载器的根目录。字符串参数也能够是以./或../开头的相对路径。例如，假设有如下目录结构：

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

在template.html中，如下路径将有效：

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

8. filter

经过一个或多个过滤器对内容过滤。须要结束标签endfilter。

例如：

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

9. firstof

输出第一个不为False参数。若是传入的全部变量都为False，就什么也不输出。

例如：

{% firstof var1 var2 var3 %}

它等价于：

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

固然也能够用一个默认字符串做为输出以防止传入的全部变量都是False：

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

10. for

循环对象中的每个元素

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

若是你想访问一个字典中的键值，这个方法一样有用：

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

请记住，对于点运算符，字典键查找优先于方法查找。

下面是Django为for标签内置的一些属性，能够看成变量同样使用{{ }}在模版中使用。

forloop.counter：循环的当前索引值，从1开始计数；经常使用于生成一个表格或者列表的序号！
forloop.counter0：循环的当前索引值，从0开始计数；
forloop.revcounter：循环结束的次数（从1开始）
forloop.revcounter0 循环结束的次数（从0开始）
forloop.first：判断当前是否循环的第一次，是的话，该变量的值为True。咱们常常要为第一行加点特殊的对待，就用得上这个判断了，结合if。
forloop.last：若是这是最后一次循环，则为真
forloop.parentloop：对于嵌套循环，返回父循环所在的循环次数。某些场景下，这是个大杀器，能解决你不少头疼的问题。

11. 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>

12. if

{% if %}会对一个变量求值，若是它的值是“True”（存在、不为空、且不是boolean类型的False值），这个内容块就会输出：

{% 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 }}过滤器展现出athletes的数量。

if标签以后能够带有一个或者多个{% elif %}从句，也能够带有一个{% else %}从句以便在以前的全部条件不成立的状况下完成执行。这些从句都是可选的。

布尔运算符:

if标签可使用not，and或or来测试布尔值：

{% 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标签中使用实际括号是错误的语法，这点不一样于Python。若是须要为它们指示优先级，应使用嵌套的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 %} {% 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 not in users %}  If users is a QuerySet, this will appear if user is not an  instance that belongs to the QuerySet. {% endif %} {% 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 %} {% 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 %} (错误的用法)

应该使用：

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

13. ifequal和ifnotequal

{％ ifequal a b ％} ... {％ endifequal ％}是一种过期的写法，等同于{％ if a == b ％} ... {％ endif ％}。一样， {％ ifnotequal a b ％} ... {％ endifnotequal ％}等同于{％ if a ！= b ％} ... {％ endif ％}。这两个标签将在之后的版本中弃用。

14. ifchanged

检查一个值是否在上一次的迭代中被改变了。

{% ifchanged %}标签一般用在循环里。它有两个用处：

检查已经渲染过的内容的当前状态。而且只会显示发生改变的内容。例如，如下的代码是输出days的列表项，不过它只会输出被修改过月份的项:

<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=" color: rgb(153, 153, 153); font-weight: bold; font-style: italic;">{% ifchanged match.ballot_id %} {% cycle "red" "blue" %} {% else ％} gray {% endifchanged ％} ">{{ match }}</div> {% endfor %}

15. include

加载指定的模板并以标签内的参数渲染。这是一种引入别的模板的方法，必定要将include和extend区分开！include相似Python的import。

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

也可使用变量名template_name：

{% include template_name %}

下面这个示例生成输出“Hello, John!”：

context：变量greeting="Hello"，变量person="John"。

模板：

{% 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中"的变种方法,而不该该看做是"解析子模版并在被父模版包含的状况下展示其被父模版定义的内容"。这意味着在不一样的被包含的子模版之间并不共享父模版的状态,每个子包含都是彻底独立的渲染过程。

16. load

加载自定义模板标签。

下面的模板将会从somelibrary和package包中的otherlibrary中载入全部已经注册的标签和过滤器:

{% load somelibrary package.otherlibrary %}

还可使用from参数从库中选择性加载单个过滤器或标记。

{% load foo bar from somelibrary %}

17. lorem

这个标签是用来在模版中提供文字样本以供测试用的。使用场景是什么？

好比你要写个demo，里面要有一大段的文字和篇章，你不可能真的去写一篇文章吧？若是懒得去网上COPY，又不肯意使用一堆毫无心义杂乱的乱码，那么使用这个方法，能够帮你自动填充一些能够阅读的内容。

PS：Django考虑得真细.....

用法：

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

可使用零个，一个，两个或三个参数。这些参数是：

count ：一个数字（或变量），其中包含要生成的段落或字数（默认值为1）。
method：HTML中使用p标签、仍是w标签、仍是b标签，决定文本格式。默认是“b”。
random：若是给出的话，random这个词在生成文本时不会使用公共段落。例子：

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

18. now

显示当前的日期或时间。能够指定显示的格式。例如：

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

下面的例子中，“o”和“f”都被反斜杠转义：

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

这将显示为“It is the 4th of September”。

还可使用语法{％ now “Y” as current_year ％}将输出存储在变量中。

{% now "Y" as current_year %} {% blocktrans %}Copyright {{ current_year }}{% endblocktrans %}

19. regroup

用对象间共有的属性重组列表。

对于下面的数据：

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

若是你想显示按国家/地区排序的分层列表，以下所示：

India
    Mumbai: 19,000,000
    Calcutta: 15,000,000
USA
    New York: 20,000,000
    Chicago: 7,000,000
Japan
    Tokyo: 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中。

country_list的每一个元素是具备两个字段的namedtuple()的实例：

grouper - 分组的项目（例如，字符串“India”或“Japan”）。
list - 此群组中全部项目的列表（例如，全部城市的列表，其中country ='India'）。

20. resetcycle

Django1.11中的新功能。

重置先前的循环，以便在下一次循环时从其第一个项目从新启动。若是没有参数，{％ 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 %}

在这个例子中，咱们有交替的奇数/偶数行和每五行出现一次的‘major’行。当类别更改时，只有五行周期被重置。

21. 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 %}

22. templatetag

输出用于构成模板标签的语法字符。

因为模板系统没有“转义”的概念，没法在HTML中使用‘\’转义出相似{%的字符。为了显示模板标签自己，必须使用{％ templatetag ％}标签，并添加相应的参数：

openblock：{％
closeblock： ％}
openvariable： {{
closevariable： }}
openbrace ：{
closebrace： }
opencomment： {＃
closecomment： ＃}

例如：

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

23. url

返回与给定视图和可选参数匹配的绝对路径引用（不带域名的URL）。在解析后返回的结果路径字符串中，每一个特殊字符将使用iri_to_uri()编码。这能够避免在模板中硬编码超级连接路径。

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

第一个参数是url()的名字。它能够是一个被引号引发来的字符串或者其余的上下文变量。其余参数是可选的而且以空格隔开，这些值会在URL中以参数的形式传递。上面的例子展现了如何传递位置参数，固然也可使用关键字参数。

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

不要把位置参数和关键字参数混在一块儿使用。URLconf所需的全部参数都应该提供。

例如，假设有一个视图app_views.client，其URLconf接受客户端ID，并以下所示：

('^client/([0-9]+)/$', app_views.client, name='app-views-client')

若是你的应用中的URLconf已经被包含到项目URLconf中，好比下面这样

('^clients/', include('project_name.app_name.urls'))

而后，在模板中，你能够建立一个此视图的连接，以下所示：

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

模板标签会输出字符串:/clients/client/123/

若是但愿在不显示网址的状况下检索网址，可使用略有不一样的调用：

{% url 'some-url-name' arg arg2 as the_url %} <a href="{{ the_url }}">I'm linking to {{ the_url }}</a>

若是视图不存在，{％ url ... as var ％}语法不会致使错误。

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

若是使用urlconf的名称空间网址，经过冒号指定彻底名称，以下所示：

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

再次强调，是冒号，不是圆点不是斜杠！

24. verbatim

禁止模版引擎在该标签中进行渲染工做。

常见的用法是容许与Django语法冲突的JavaScript模板图层工做。像这样：

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

25. 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）。

26. with

使用一个简单地名字缓存一个复杂的变量，当你须要使用一个代价较大的方法（好比访问数据库）不少次的时候这是很是有用的。

像这样：

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

total只在with标签内部有效。

能够分配多个变量：

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