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个参数是:

未完待续…