Django内建模版标签和过滤器

第四章列出了许多的常用内建模板标签和过滤器。然而，Django自带了更多的内建模板标签及过滤器。这章附录列出了截止到编写本书时，Django所包含的各个内建模板标签和过滤器，但是，新的标签是会被定期地加入的。

对于提供的标签和过滤器，最好的参考就是直接进入你的管理界面。Django的管理界面包含了一份针对当前站点的所有标签和过滤器的完整参考。想看到它的话，进入你的管理界面，单击右上角的Documentation（文档）链接。

内建文档中的“标签和过滤器”小节阐述了所有内建标签（事实上，本附录中的标签和过滤器参考都直接来自那里）和所有可用的定制标签库。

考虑到那些没有管理站点可用的人们，这里提供了常用的标签和过滤器的参考。由于Django是可高度定制的，管理界面中的那些可用的标签和过滤器的参考可认为是最可信的。

内建标签参考
block

定义一个能被子模板覆盖的区块。参见第四章“模板继承”一节查看更多信息。

comment

模板引擎会忽略掉 {% comment %} 和 {% endcomment %} 之间的所有内容。

cycle

轮流使用标签给出的字符串列表中的值。

在一个循环内，轮流使用给定的字符串列表元素：

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

在循环外，在你第一次调用时，给这些字符串值定义一个不重复的名字，以后每次只需使用这个名字就行了：

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

你可以使用任意数量的用逗号分隔的值。注意不要在值与值之间有空格，只是一个逗号。

debug

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

extends

标记当前模板扩展一个父模板。

这个标签有两种用法：

{% extends "base.html" %} （带引号） 直接使用要扩展的父模板的名字 "base.html" 。

{% extends variable %} 用变量 variable 的值来指定父模板。如果变量是一个字符串，Django会把字符串的值当作父模板的文件名。如果变量是一个 Template 对象，Django会把这个对象当作父模板。

参看第四章更多应用实例。

filter

通过可变过滤器过滤变量的内容。

过滤器也可以相互传输，它们也可以有参数，就像变量的语法一样。

看这个用法实例：

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

firstof

输出传入的第一个不是 False 的变量，如果被传递变量都为 False ，则什么也不输出。

看这个用法实例：

{% firstof var1 var2 var3 %}  

这等同于如下内容：

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

for

轮询数组中的每一元素。例如显示一个指定的运动员的序列 athlete_list ：

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

你也可以逆向遍历一个列表 {% for obj in list reversed %} 。

for 循环设置了许多循环中可用的变量（见表F-1）。

if

{% if %} 标签测试一个变量，若变量为真（即其存在、非空，且不是一个为假的布尔值），区块中的内容就会被输出：

{% if athlete_list %}      Number of athletes: {{ athlete_list|length }}  {% else %}      No athletes.  {% endif %}  

若 athlete_list 非空，变量 {{ athlete_list|length }} 就会显示运动员的数量。

正如你所见， if 标签有可选的 {% 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 (OK, so      writing English translations of Boolean logic sounds      stupid; it‘s not our fault).  {% endif %}    {% if athlete_list and not coach_list %}      There are some athletes and absolutely no coaches.  {% endif %}  

不允许 and 和 or 同时出现在一个 if 语句中，因为这样会有逻辑上的问题。例如这样是有语病的：

{% if athlete_list and coach_list or cheerleader_list %}  

如果你需要同时使用 and 和 or 来实现较高级的逻辑，可以用嵌套的 if 标签来实现。例如：

{% if athlete_list %}      {% if coach_list or cheerleader_list %}          We have athletes, and either coaches or cheerleaders!      {% endif %}  {% endif %}  

重复使用同一逻辑符是可以的。例如这样是正确的：

{% if athlete_list or coach_list or parent_list or teacher_list %}  

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

前面那个例子中日期每次发生变化时就会显示出来，但只有小时和日期都发生变化时才会显示小时。

ifequal

如果两个参数相等，就输出该区块的内容。

举个例子：

{% ifequal user.id comment.user_id %}      ...  {% endifequal %}  

正如 {% if %} 标签一样， {% else %} 语句是可选的。

参数也可以是硬编码的字符串，所以下面这种写法是正确的：

{% ifequal user.username "adrian" %}      ...  {% endifequal %}  

可以用来比较的参数只限于模板变量或者字符串（实际上整数和小数也是可以的——译注），你不能检查诸如 True or False 等Python对象是否相等。如果你需要测试某值的真假，可以用 if 标签。

ifnotequal

和 ifequal 类似，不过它是用来测试两个参数是 不 相等的。

include

加载一个模板，并用当前上下文对它进行渲染，这是在一个模板中包含其他模板的一种方法。

模板名可以是一个变量或者是一个硬编码（引号引起来的）的字符串，引号可以是单引号或者双引号。

这个例子包含了 "foo/bar.html" 模板的内容：

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

这个例子包含了名字由变量 template_name 指定的模板的内容：

{% include template_name %}  

load

读入一个自定义的模板库。第十章里有关于自定义模板的相关信息资料

now

根据给定的格式字符串显示当前日期。

这个标签来源于PHP中的 date() 函数（ http://php.net/date ），并使用与其相同的格式语法，但是Django对其做了扩展。

表F-2显示了可用的格式字符串。

看这个例子：

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

记住，如果你想用一个字符串的原始值的话，你可以用反斜线进行转义。在这个例子中，f被用反斜线转义了，如果不转义的话f就是显示时间的格式字符串。o不用转义，因为它本来就不是一个格式字母。

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

这样就会显示成“It is the 4th of September”。

regroup

把一列相似的对象根据某一个共有的属性重新分组。

要解释清这个复杂的标签，最好来举个例子。比如， people 是包含 Person 对象的一个列表， 这个对象拥有 first_name 、 last_name 和 gender 属性，你想这样显示这个列表：

* Male:      * George Bush      * Bill Clinton  * Female:      * Margaret Thatcher      * Condoleezza Rice  * Unknown:      * Pat Smith  

下面这段模板代码就可以完成这个看起来很复杂的任务：

{% regroup people by gender as grouped %}  <ul>  {% for group in grouped %}      <li>{{ group.grouper }}      <ul>          {% for item in group.list %}          <li>{{ item }}</li>          {% endfor %}      </ul>      </li>  {% endfor %}  </ul>  

如你所见， {% regroup %} 构造了一个列表变量，列表中的每个对象都有 grouper 和 list 属性。grouper 包含分组所依据的属性， list 包含一系列拥有共同的 grouper 属性的对象。这样 grouper 就会是 Male 、 Female 和 Unknown ， list 就是属于这几种性别的人们。

记住，如果被分组的列表不是按照某一列排好序的话，你就不能用 {% regroup %} 在这一列上进行重新分组！就是说如果人的列表不是按照性别排好序的话，在用它之前就要先对它排序，即：

{% regroup people|dictsort:"gender" by gender as grouped %}  

spaceless

去除HTML标签之间的空白符号，包括制表符和换行符。

例如：

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

返回结果如下：

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

仅仅 标签 之间的空白符被删掉，标签和文本之间的空白符是不会被处理的。在下面这个例子中，Hello 两边的空白符是不会被截掉的：

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

ssi

把一个指定的文件的内容输出到页面上。

像include标签一样， {% ssi %} 会包含另外一个文件的内容，这个文件必须以绝对路径指明：

{% ssi /home/html/ljworld.com/includes/right_generic.html %}  

如果指定了可选的parsed参数的话，包含进来的文件的内容会被当作模板代码，并用当前的上下文来渲染：

{% ssi /home/html/ljworld.com/includes/right_generic.html parsed %}  

注意，如果你要使用 {% ssi %} 的话，为了安全起见，你必须在Django配置文件中定义ALLOWED_INCLUDE_ROOTS。

大多数情况下 {% include %} 比 {% ssi %} 更好用， {% ssi %} 的存在通常是为了向后兼容。

templatetag

输出组成模板标签的语法字符。

模板系统没有转义的概念，所以要显示一个组成模板标签的字符的话，你必须使用 {% templatetag %} 标签。

参数用来标明要显示的字符（参见表F-3）。

url

根据所给视图函数和可选参数，返回一个绝对的URL（就是不带域名的URL）。由于没有在模板中对URL进行硬编码，所以这种输出链接的方法没有违反DRY原则。

{% url path.to.some_view arg1,arg2,name1=value1 %}  

第一个变量是按package.package.module.function形式给出的指向一个view函数的路径。那些可选的、用逗号分隔的附加参数被用做URL中的位置和关键词变量。所有URLconf需要的参数都应该是存在的。

例如，假设你有一个view，app_name.client，它的URLconf包含一个client ID参数。URLconf对应行可能看起来像这样：

(‘^client/(\d+)/$‘, ‘app_name.client‘)  

如果这个应用的URLconf像下面一样被包含在项目的URLconf里：

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

那么，在模板中，你可以像这样创建一个指向那个view的link连接：

{% url app_name.client client.id %}  

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

widthratio，寬度的比率

為了畫出長條圖，這個標籤計算一個給定值相對於最大值的比率，然後將這個比率給定一個常數

一些实例：

<img src="bar.gif" height="10" width="{% widthratio this_value max_value 100 %}" />  

If this_value is 175 and max_value is 200, the image in the preceding example will be 88 pixels wide (because 175/200 = .875; .875 * 100 = 87.5, which is rounded up to 88).

Built-in Filter Reference
add

例如：

{{ value|add:"5" }}  

参数与被处理数据相加的结果.

addslashes

例如：

{{ string|addslashes }}  

给敏感字符添加斜线(转义). 举例,要将一个字符串传递给 JavaScript 时.

capfirst

例如：

{{ string|capfirst }}  

将字符串的首字母大写

center

例如：

{{ string|center:"50" }}  

在一个给定的长度让字符串居中

cut

例如：

{{ string|cut:"spam" }}  

把给定字符串中包含的所有参数值删除掉。

date

Example:

{{ value|date:"F j, Y" }}  

把一个date类型按照给定的格式输出（与”now”标签用法一样）。

default

例如：

{{ value|default:"(N/A)" }}  

如果变量不存在，使用默认值

default_if_none

例如：

{{ value|default_if_none:"(N/A)" }}  

如果变量值为None，使用默认值

dictsort

例如：

{{ list|dictsort:"foo" }}  

接受一个字典列表,返回按给定参数的属性排序后的列表.

dictsortreversed

例子:

{{ list|dictsortreversed:"foo" }}  

接受一个字典列表,返回按给定参数的属性逆序排序后的列表

divisibleby

Example:

{% if value|divisibleby:"2" %}      Even!  {% else %}      Odd!  {% else %}  

如果值能够被给定的参数整除的话，返回“True”。

escape

例如：

{{ string|escape }}  

按照以下的规则，转义一个HTML字符串：

"&" to "&"

< to "&lt;"

> to "&gt;"

‘"‘ (double quote) to ‘&quot;‘

"‘" (single quote) to ‘'‘

filesizeformat

Example:

{{ value|filesizeformat }}  

将值格式化为 ‘可读性好的’ 文件大小(比如 ‘13 KB’, ‘4.1 MB’, ‘102bytes’ 等等).

first

Example:

{{ list|first }}  

返回列表中的第一个元素.

fix_ampersands

Example:

{{ string|fix_ampersands }}  

将 & 符号替换为 &amp; 实体

floatformat

Examples:

{{ value|floatformat }}  {{ value|floatformat:"2" }}  

将一个浮点数四舍五入到小数点后1位 — 如果根本没有小数,小数部分不会显示.

36.123 gets converted to 36.1 .

36.15 gets converted to 36.2 .

36 gets converted to 36 .

如果使用同一个数字的整数参数，“floatformat”轮数，许多小数位：

36.1234 with floatformat:3 gets converted to 36.123 .

36 with floatformat:4 gets converted to 36.0000 .

If the argument passed to floatformat is negative, it will round a number to that many decimal places but only if theres a decimal part to be displayed:

36.1234 with floatformat:-3 gets converted to 36.123 .

36 with floatformat:-4 gets converted to 36 .

Using floatformat with no argument is equivalent to using floatformat with an argument of -1 .

get_digit

Example:

{{ value|get_digit:"1" }}  

提供一个完整的数, 返回该数中被请求的数字,其中 1 是最右边的数, 2 是从右边数第二个数字等等. 若输入值非法(若输入或参数不是整数, 或者参数小于1)则返回其原始值. 否则输出就总是整数.

join

例子：

{{ list|join:", " }}  

用一个字符串将一个列表连接起来,类似 Python 的 str.join(list).

length

例子：

{{ list|length }}  

返回对象的长度

length_is

Example:

{% if list|length_is:"3" %}      ...  {% endif %}  

若值的长度与参数相等,返回 True, 否则返回 False.

linebreaks

Example:

{{ string|linebreaks }}  

把换行符转换成<p>和<br />标签。

linebreaksbr

Example:

{{ string|linebreaksbr }}  

把每个新行转换为”<br />”标签

linenumbers

Example:

{{ string|linenumbers }}  

带行号显示文本

ljust

Example:

{{ string|ljust:"50" }}  

在给定宽度的域内将文本左对齐.

lower

Example:

{{ string|lower }}  

把一个给定的字符串转换成小写。

make_list

Example:

{% for i in number|make_list %}      ...  {% endfor %}  

将值转化为一个列表.对一个整数,它是一个数字的列表.对一个字符串,这是一个字符的列表

phone2numeric

Example:

{{ string|phone2numeric }}  

将一个电话号码(可能包含字母)转化等价的数字值.比如: ‘800-COLLECT’ 将被转化为 ‘800-2655328’.

输入不一定非是一个合法号码. 它可以转化任意字符串.

pluralize

Example:

The list has {{ list|length }} item{{ list|pluralize }}.  

如果值不是 1 的话返回 ‘s’ 用于 ‘1 vote’ vs. ‘2 votes’ 这种场合

Example:

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

For words that require a suffix other than ‘s‘ , you can provide an alternate suffix as a parameter to the filter.

Example:

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

For words that dont pluralize by simple suffix, you can specify both a singular and plural suffix, separated by a comma.

Example:

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

pprint

Example:

{{ object|pprint }}  

pprint.pprint 和一个封装器— 仅用于调试.

random

Example:

{{ list|random }}  

返回随机的从列表中返回一个元素

removetags

Example:

{{ string|removetags:"br p div" }}  

从输出中删除单空格分隔的 [X]HTML标签 列表

rjust

Example:

{{ string|rjust:"50" }}  

在给定宽度的域内将文本右对齐.

slice

Example:

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

返回一个列表的片段

使用与 Python 的 list 相同的语法, 参阅http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice 以了解更详细的信息.

slugify

Example:

{{ string|slugify }}  

转化为小写, 移去非单词字符(字母数字和下划线),将空白转化为连字符,去除前后空白.

stringformat

Example:

{{ number|stringformat:"02i" }}  

根据给定参数(一个格式字符串)格式化一个变量, 这个格式字符串使用 Python 字符串格式化语法, 例外之处是 “%” 运算符被省略.

参阅 http://docs.python.org/lib/typesseq-strings.html 以了解 Python 格式字符串

striptags

Example:

{{ string|striptags }}  

过滤掉[X]HTML标签.

time

Example:

{{ value|time:"P" }}  

按指定的样式（样式定义同now标签）来格式化一个时间对象

timesince

Examples:

{{ datetime|timesince }}  {{ datetime|timesince:"other_datetime" }}  

格式化一个日期,这个日期是从给定日期到现在的天数和小时数(比如: “4 days, 6 hours”).

接受一个可选的参数，该参数是一个包含比较日期的变量（该参数默认值是 now). 举例来说， 如果 blog_date 是一个日期实例表示 2006-06-01 午夜， 而 comment_date 是一个日期实例表示 2006-06-01 早上8点，那么 {{ comment_date|timesince:blog_date }} 将返回 “8 hours”.

timeuntil

Examples:

{{ datetime|timeuntil }}  {{ datetime|timeuntil:"other_datetime" }}  

类似 timesince, 只是它比较当前时间直到给定日期时间。举例来说，如果今天是 2006-06-01 而 conference_date 是 2006-06-29, 那么 {{ conference_date|timeuntil }} 将返回 “28 days”.

接受一个可选的参数，该参数是一个包含比较日期的变量（该参数默认值是 now). 举例来说， 如果 from_date 是一个日期实例表示 2006-06-22， 那么 {{ conference_date|timeuntil:from_date }} 会返回 “7 days”.

title

Example:

{{ string|titlecase }}  

按标题格式转化一个字符串

truncatewords

Example:

{{ string|truncatewords:"15" }}  

将一个字符串截短为指定数目的单词.

truncatewords_html

Example:

{{ string|truncatewords_html:"15" }}  

Similar to truncatewords , except that it is aware of HTML tags. Any tags that are opened in the string and not closed before the truncation point are closed immediately after the truncation.

This is less efficient than truncatewords , so it should be used only when it is being passed HTML text.

unordered_list

Example:

<ul>      {{ list|unordered_list }}  </ul>  

递归的接受一个自嵌套的列表并返回一个HTML无序列表(此列表可不是pythob语义中的列表) — 只是没有开始和结束的<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

例子：

{{ string|upper }}  

将一个字符串全部字母改为大写。

urlencode

例子：

<a href="{{ link|urlencode }}">linkage</a>  

转义该值以用于 URL.

urlize

例子：

{{ string|urlize }}  

将URLs由纯文本变为可点击的链接。

urlizetrunc

例子：

{{ string|urlizetrunc:"30" }}  

将URLs变为可点击的链接，按给定字母限截短URLs。

wordcount

例如：

{{ string|wordcount }}  

返回单词数。

wordwrap

例如：

{{ string|wordwrap:"75" }}  

在指定长度将文字换行。

yesno

例如：

{{ boolean|yesno:"Yes,No,Perhaps" }}  

提供一个字符串参数对应着 true, false 和 (可选的) None, 根据被处理的值返回相应的字符串:

Django内建模版标签和过滤器