Django 2.1.3 文档-模板-内置标签和过滤器(tag&filter)

-- 译自官方文档 --

内置标签和过滤器(tag&filter)

本节讲述Django的内置模板 标签和过滤器.如果可以建议你使用automatic documentation,因为它包含了如何自定义标签和过滤器.

Built-in tag 一览

autoescape
功能: 控制某一范围内的html代码是否需要转义.
参数: on(转义) 和 off(不转义),这两个参数决定了在其控制范围内的html代码是否需要转义. 控制范围由 endautoescape 结束.
            当参数设置为on,范围内的html代码在输出到页面前都会被转义(先走filter再转义). 它实现的功能和你在变量上面使用过滤                器 escape 是一样的.
例外的情况是 变量已经使用了safe/escape过滤器进行转义或者对代码做了处理或者(此句翻译可能有问题，原文: The only exceptions are variables that are already marked as “safe” from escaping, either by the code that populated the variable, or because it has had the safe or escape filters applied.)
例子:

block
功能: 定义了一部分区域,此区域可以被子模版重写. 详情见 模板继承

comment
功能: 忽略 {% comment %} and {% endcomment %}之间的内容,起到一个注释的作用. 可以在标签后面使用双引号留下注释说明, comment 标签不能嵌套使用,否则报500错误
例子:

csrf_token
此标签用于CSRF(跨站请求伪造)的保护,常在form表单中使用,关于CSRF请见 Cross Site Request Forgeries.

cycle
功能: 对cycle的 参数列表 进行轮询
参数: 可以是string字符串或模板变量
这个标签在循环中有用:

      假设 somelist 中有1,2,3,4,5,那么循环到1,cycle=‘row1’; 循环到2,cycle=‘row2’; 循环到3,cycle=‘row1’;长此以往,直到列表循环结束.你也可以给cycle传递模板变量变量, 假如你有两个变量rowvalue1 和 rowvalue2, 你可以让它们两个交替被获取:

cycle中的模板变量会自动被转义,你可以使用上面的autoescape标签去掉转义:

参数可以是string或模板变量混用(string中的内容不会被自动转义):

有时候你想在cycle参数跳到下一个之前,使用该参数. 可以这么做, 使用as给cycle标签参数一个可以引用的别名,比如rowcolors.

       这样一来,在参数跳变之前,你可以使用{{rowcolors}}这个变量了;在当前循环中,如果你想自己跳变到下一个参数可以这样做 {% cycle rowcolors %},如此一来,rowcolors的值就会变为row2,从而达到提前跳变的目的.
例子:

输出:

        在cycle标签中你可以提供n个参数(空格分开),string参数可以用单引号或双引号引起,如果不是string就会被当作模板变量来处理.默认情况下,当你使用了as提供别名,包含{% cycle %}的地方就会触发第一个参数被使用的情况.如果你想在嵌套循环或include一个模板中使用这个cycle,就会出现第一次使用却拿到第二个参数的情况,为解决这种定义就被使用的情况,达到一种先定义后使用的目的。在别名后面添加一个silent关键字.例如:

        当声明了silent关键字的时候,后续的{% cycle %}标签都会自带silent属性，这意味着{%cycle 别名%}的结果为空.尽管第二次调用cycle标签,下面的例子输出还是为空:

你可以使用resetcycle标签让一个cycle标签在下一次循环中重新从第一个参数开始轮询.

debug
功能: 输出一堆debug信息, 包含当前页内容和导入的所有模块信息.(容易浏览器崩溃)

extends
功能:声明一个模板继承自父类模板
两种使用方法:
1 {% extends “base.html” %} 引号引起要继承的父类模板名字"base.html"(确保路径加载正确).
2 {% extends variable %} 使用 variable变量的值. 如果变量的值是字符串,同上一个方法; 如果变量是一个 Template 对象, Django 将会使用这个对象作为父模板. 更多详情见Template inheritance.

通常,父类模板的名字都是一个template文件夹下子文件(也就是一个相对路径).通常以./或…/开头. 例如,有如下的目录结构:

在template.html文件中, 如下路径引用是正确的:

filter(标签filter而不是过滤器filter)
功能: 将一块内容使用多个过滤器进行处理.多个过滤器可以用 | 连接,过滤器还可以提供参数,就像变量的语法那样 .
注意: 一块内容是指包含在 filter标签 和 endfilter 标签之间的所有内容.

实例说明:

firstof
功能:输出第一个非 False(0,’’,False,null)的参数的值.
使用方法: {% firstof var1 var2 var3 %}
等价于:

为了避免所有都是False,你可以在最后传一个string (这些变量上都可以使用过滤器filter):
{% firstof var1 var2 var3 "fallback value" %}
你可以用 “as 别名” 来存储输出结果,如:
{% firstof var1 var2 var3 as value %}.

for
功能: 循环数组中的每一项,每项都会以文本形式输出.例如,为了显示运动员列表 athlete_list中的每个运动员:

你可以使用 reversed语法 ,让列表反转过{% for obj in list reversed %}.

      如果你想循环一个包含了列表的列表,你可以为内层每个列表中的每个对象分配一个名字. 例如,你的points列表内容是一些点(x,y), 你可以用如下方式输出每个点的x,y:

如果你要处理一个 字典对象,这种方法很好用.例如,你要输出字典的键值对:

注意事项:(python语法相关)请注意点操作, 字典中键的查找优先于方法的查找.因此如果 data 字典中有一个键的名字叫做 ‘items’, data.items 将会返回 data[‘items’]的值 而不是 data.items()方法的返回值. 为了避免你使用字典类内的关键字,请不要使用这些名称来定义键 (items, values, keys, etc.). 获取更多点操作的查找顺序，请见 documentation of template variables.

Django 为for 循环定义了一些内置变量供你使用:

for … empty
功能:如果for循环的列表是空 或者 列表变量不存在,会执行{% empty %}里面的内容:

上面的更简洁也可能更快,下面的是等价写法:

if
功能: 判断一个变量,如果是true(不为空,不是false)就会执行 if 块里面的内容:

      如果上面的运动员列表athlete_list 不为空,运动员的个数 {{ athlete_list|length }} 就会显示出来.
如上所示,if标签块内可以使用 {% elif %}或 {% else %},其作用不言而喻.

Boolean operators
if标签可以使用 and, or, not 去测试变量的值,进而进行不同的操作:

同一个if 标签内可以同时使用and和or操作符，and优先级更高，例如.:
{% if athlete_list and coach_list or cheerleader_list %}
上面内容将会被Django解释成:
if (athlete_list and coach_list) or cheerleader_list
if标签内使用圆括号是非法的，你可以用嵌套if来代替.

      if标签还可以用其它操作符,如 ==, !=, <, >, <=, >=, in, not in, is, is not 它们是这么用的:
== 等于:

!= 不等于、 < 小于、 > 大于、 <= 小于等于、 >= 大于等于，这几个操作符的用法例子同==
in 包含在内
      此操作符号支持许多Python容器类对象,用于判断容器中是否存在某一变量.下面的例子
都是in的可用形式(字符串,list,set…):

not in 不包含在内.
in的对立操作.

is 对象匹配.
判断两个变量/对象是否是同一个变量/对象:

is no非对象匹配.
判断两个变量/对象是否不是同一个变量/对象.is的对立操作:

Filters
你在if表达式后面也可以使用filter,例如:

Complex expressions
      上面这些操作符能组成更复杂的表达式,于此,了解运算符优先级规则在求值表达式时如何分组是很重要的.
下面的运算符的优先级从最低到最高:

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

(优先级规则遵循Python).例如,如下的 if 标签表达式:
{% if a == b or c == d and e %}
等同于Python中的:
if((a == b) or ((c == d) and e)
      如果你想使用不同的优先级顺序, 为了大家都明白你的优先级顺序,你该使用其嵌套的 if 标签.比较运算符不能像Python那样写一串儿,你不能这么写:
{% if a > b > c %} (WRONG)
应该这样写:
{% if a > b and b > c %}

ifequal 和 ifnotequal
{% ifequal a b %}..{% endifequal %} 等价于 {% if a == b %}...{% endif %}.
{% ifnotequal a b %}..{% endifnotequal %} 等价于{% if a != b %}...{% endif %}.
这两个标签未来会废弃,用 == 和 != 就好了.

ifchanged (翻译完也没懂它的作用，请自己找例子理解)
功能: 在for循环中某些检查值是否发生改变
{% ifchanged %} 用在循环里面,两种用途.

1. 检查当前渲染内容和之前的状态是否相同，如果不同则重新展示.此例中显示了一些日期,只有月份变化才会显示月份:
   
2. 给一些变量,检查它们是否有变化.下面的实例,每当日期变化就显示,小时变化也会显示:
   

ifchanged标签也可以使用 {% else %} 表示某个变量未发生变化:

include
功能: 在当前内容页中加载一个模板,模板名称可以是一个而变量或者一个字符串.
这个例子包含了一个叫做 "foo/bar.html"的模板:
{% include "foo/bar.html" %}
模板的名字都是一个template文件夹下子文件(也就是一个相对路径),通常以./或…/开头. .
此例以一个变量 template_name作为模板的名字:
{% include template_name %}
变量的形式还可以是一个对象,对象有个render()方法接收内容. 这样允许你在上下文中引用已编译的模板(暂时不明白).

一个被包含的模板,由包含它的模板进行内容的渲染,同时变量可以跨模板使用.这个例子输出 “Hello, John!”:

• Context: person 设置为 “John” greeting 设置为 “Hello”.

• Template:
  {% include "name_snippet.html" %}

• name_snippet.html :
  {{ greeting }}, {{ person|default:"friend" }}
  通过with关键字,可以把显示地传递参数:
  
         上面提到过变量可以跨模板使用,子模板可以引用父模板中的变量，如果你指定了only 选项,那么只有被only跟随的那些变量可以跨模板使用，其它的不行.:
  {% include "name_snippet.html" with greeting="Hi" only %}
  

load
功能: 加载一些模板tag或filter [也可能是变量].
例如: 如下的模板将会加载所有来自(somelibrary文件和包package内otherlibrary文件)中的标签和过滤器:
{% load somelibrary package.otherlibrary %}
你可以选择性地从某文件中加载指定名称的标签或过滤器. 此例中 bar和 foo(标签或过滤器)从somelibrary文件中被引入:
{% load foo bar from somelibrary %}
更多关于自定义标签和过滤器的内容请见Custom tag and filter libraries.

lorem
功能: 随机生成拉丁文的"乱数假文".在模板内随机生成测试数据测试页面.
使用方法:

{% lorem %} 标签可以提供3个参数,你可以指定前n(1-3)个参数. 这3个参数是:

now
功能:使用格式化的字符串显示当前日期或时间.这个格式化的字符串可以使用date过滤器中指定的参数 .
例如:
It is {% now "jS F Y H:i" %}
如果你想参数不被转义,你可以使用反斜线.下面的例子原本会输出 It is the 26th 2018 12:30 十月,转义之后输出It is the 26th of 十月 :


你可以使用as+别名来存储当前结果的字符串形式 {% now "Y" as current_year %} .如果你想在blocktrans模板标签中使用now标签，这会很有用 blocktrans :

regroup
功能:按照某一属性对一个列表进行重新分组.
这个复杂的标签最好用一个例子来说明。cities 是一个城市的列表,包含了很多字典对象，
每个字典对象由name,population,country这三个key和对应的value组成:

如果你想显示一个以国家分级的列表,如下面的样式:

下面的代码将会帮你实现这种结果:

看看这个例子，regroup标签接收三个参数,一个列表,对列表中哪个属性进行分组，分组之后的对象.
这里我们对cities列表中的country进行重新分组,结果对象名为result_list.

regroup标签返回的新列表是一种 group objects的实例. Group objects 实现了 namedtuple()函数 并提供两个属性:

• grouper – 被分组的属性(e.g., 字符串 “India” or “Japan”).
• list – 当前分组中的所有项 .

因为regroup标签产生的是 namedtuple() 对象, 前面的例子还可以这么写:

注意,regroup不会对列表进行排序. 我们的例子之所以能成功,需要列表事先按照country这个属性
排列好,否则同一个分组会输出多次,例如你给的列表变成了这样顺序:

输出结果会变成这样:

    最好的解决方法是按照输出结果知错就改.另一种方法是使用过滤器dictsort(如果你的列表是字典构成的):

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

Grouping on other properties
    对于regroup标签来说，它的分组属性可以是任何的 valid template lookup, 包括方法,属性，字典的键
和列表的项. 例如,如果country字段是一个模型类的外键并且country字段所表示的类还有一个
descrption属性,可以这么用:

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

    如果country是一个模型类的字段,该字段含有choices选项,它会有一个 get_FOO_display() 方法可用, 允许你在此方法返回的字符串属性上进行分组:

{% regroup cities by get_country_display as country_list %}

{{ country.grouper }} 会显示choices中的属性而不是键,如下 .

resetcycle
功能:重置cycle标签,下次循环从第一个参数开始.不对{% resetcycle %} 标签提供参数将会重置最近的 {% cycle %} 值.
使用方法:

输出的HTML如下:

注意:第一块结束时,class=“odd” 第二块开始也是class=“odd”. 如果不提供resetcycle,第二块开始会是 class=“even”.
你也可以给reset标签重命名:

在这个例子中,每五行有一个major行,只有当category变化的时候,major行重置.
spaceless
功能:移除 html标签和标签之间的空白(tab,空行).
使用方法:

结果返回的HTML是这样的:

只有标签之间的空白被移除了，标签内的文本是不会移除的. 在此例中 Hello两边的空白不会被移除:

templatetag
功能:输出用于组成模板标签的语法字符之一.
由于模板系统里面没有"转义"的概念,django为你提供了{% templatetag %} 标签.
如下参数决定输出什么字符:

url
功能:返回某个视图(可能含有参数)的绝对路径(不包含域名).路径内的特殊字符会使用 iri_to_uri()编码.
在你的模板中使用 URL硬编码并不违反DRY 原则:
{% url 'some-url-name' v1 v2 %}
第一个参数是 URL pattern name.它可以用引号包裹也可以是一个上下文中的变量，后面是URL参数,使用
空格分开.上面的传参例子也可以通过下面的例子显示地指定:
{% url 'some-url-name' arg1=v1 arg2=v2 %}
这两种方式不要混用,所有参数都应该有值.
    例如,你有个视图函数app_views.client,它的URL接收一个client ID (client()是app_views.py中的一个函数). URL配置如下:
path('client/<int:id>/', app_views.client, name='app-views-client')
如果app的url被包含到了工程里面:
path('clients/', include('project_name.app_name.urls'))
在一个模板里,你可以这样访问一个视图:
{% url 'app-views-client' client.id %}
其请求的url将会是 /clients/client/123/.
如果你的url反向解析无法找到视图函数,你会得到一个 NoReverseMatch错误, 页面上将会显示错误.

如果你想看看请求的url是什么而不请求视图内容,你可以这么写:

可以用as+别名 存储你请求的url,哪怕视图函数不存在也不会报错.例子中链接到一个可选的视图:

如果你想检索一个命名空间里的url,这么做:
{% url 'myapp:view-name' %}
这会采用普通的 namespaced URL resolution 策略, including using any hints provided by the context as to the current application(不太明白).

verbatim
功能:不让模板引擎渲染此标签中的内容.
经常用它来处理js和Django模板引擎冲突的问题,例如:

你可以设计一个自定义的闭合标签:

widthratio
功能:为了创建条形图或其它,这个标签计算你给的变量和最大值之间的百分比(也可以做乘除法).
例如:

如果 this_value =175, max_value =200, and max_width =100, 上面的结果会是88 (因为 175/200 = .875; .875 * 100 = 87.5 向上取整为88).

在一些情况下,你可以把这个结果存在变量里. 例如你在 blocktrans 中想这么用:

with
功能:给复杂的变量一个别名.例子:

别名只在块内有效,你可以为多个变量指定别名:
{% with alpha=1 beta=2 %} ... {% endwith %}

tag 部分 - 完

未完待续…