附录 F 内建的模板标签和过滤器

第四章列出了许多的常用内建模板标签和过滤器。然而，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，寬度的比率

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

Heres an example:

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

Adds the argument to the value.

addslashes

例如：

{{ string|addslashes }}

Adds backslashes before single and double quotes. This is useful for passing strings to JavaScript, for example.

capfirst

例如：

{{ string|capfirst }}将字符串的首字母大写

center

例如：

{{ string|center:"50" }}

Centers the string in a field of a given width.

cut

例如：

{{ string|cut:"spam" }}

Removes all values of the argument from the given string.

date

Example:

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

Formats a date according to the given format (same as the now tag).

default

例如：

{{ value|default:"(N/A)" }}如果变量不存在，使用默认值

default_if_none

例如：

{{ value|default_if_none:"(N/A)" }}如果变量值为 None，使用默认值

dictsort

例如：

{{ list|dictsort:"foo" }}

Takes a list of dictionaries and returns that list sorted by the property given in the argument.

dictsortreversed

例子:

{{ list|dictsortreversed:"foo" }}

Takes a list of dictionaries and returns that list sorted in reverse order by the property given in the argument.

divisibleby

Example:

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

{% else %}

Odd!

{% else %}

Returns True if the value is divisible by the argument.

escape

Example:

{{ string|escape }}

Escapes a strings HTML. Specifically, it makes these replacements:

• "&" to "&amp;"

• < to "&lt;"

• > to "&gt;"

• '"' (double quote) to '&quot;'

• "'" (single quote) to '''

  filesizeformat

  Example:

  {{ value|filesizeformat }}

  Formats the value like a human-readable file size (i.e., '13 KB' , '4.1 MB' , '102 bytes' , etc).

  first

  Example:

  {{ list|first }}

  Returns the first item in a list.

  fix_ampersands

  Example:

  {{ string|fix_ampersands }}

  Replaces ampersands with &amp; entities.

  floatformat

  Examples:

  {{ value|floatformat }}

  {{ value|floatformat:"2" }}

  When used without an argument, rounds a floating-point number to one decimal place but only if theres a decimal part to be displayed, for example:

• 36.123 gets converted to 36.1 .

• 36.15 gets converted to 36.2 .

• 36 gets converted to 36 .

  If used with a numeric integer argument, floatformat rounds a number to that many decimal places:

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

Given a whole number, returns the requested digit of it, where 1 is the rightmost digit, 2 is the second-to-rightmost digit, and so forth. It returns the original value for invalid input (if the input or argument is not an integer, or if the argument is less than 1). Otherwise, output is always an integer.

join

例子：

{{ list|join:", " }}

Joins a list with a string, like Pythons str.join(list) .

length

例子：

{{ list|length }}返回对象的长度

length_is

Example:

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

...

{% endif %}

Returns a Boolean of whether the values length is the argument.

linebreaks

Example:

{{ string|linebreaks }}

Converts newlines into <p> and <br /> tags.

linebreaksbr

Example:

{{ string|linebreaksbr }}

Converts newlines into <br /> tags.

linenumbers

Example:

{{ string|linenumbers }} Displays text with line numbers.

ljust

Example:

{{ string|ljust:"50" }}

Left-aligns the value in a field of a given width.

lower

Example:

{{ string|lower }}

Converts a string into all lowercase.

make_list

Example:

{% for i in number|make_list %}

...

{% endfor %}

Returns the value turned into a list. For an integer, its a list of digits. For a string, its a list of characters.

phone2numeric

Example:

{{ string|phone2numeric }}

Converts a phone number (possibly containing letters) to its numerical equivalent. For example, '800-COLLECT' will be converted to '800-2655328' .

The input doesnt have to be a valid phone number. This will happily convert any string.

pluralize

Example:

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

Returns a plural suffix if the value is not 1. By default, this suffix is 's' . 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 }}

A wrapper around Pythons built-in pprint.pprint for debugging, really.

random

Example:

{{ list|random }}

Returns a random item from the list.

removetags

Example:

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

Removes a space-separated list of [X]HTML tags from the output.

rjust

Example:

{{ string|rjust:"50" }}

Right-aligns the value in a field of a given width.

slice

Example:

{{ some_list|slice:":2" }} Returns a slice of the list.

Uses the same syntax as Pythons list slicing. See http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice for an introduction.

slugify

Example:

{{ string|slugify }}

Converts to lowercase, removes nonword characters (alphanumerics and underscores), and converts spaces to hyphens. It also strips leading and trailing whitespace.

stringformat

Example:

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

Formats the variable according to the argument, a string formatting specifier. This specifier uses Python string-formatting syntax, with the exception that the leading % is dropped.

See http://docs.python.org/lib/typesseq-strings.html for documentation of Python string formatting.

striptags

Example:

{{ string|striptags }} Strips all [X]HTML tags.

time

Example:

{{ value|time:"P" }}

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

timesince

Examples:

{{ datetime|timesince }}

{{ datetime|timesince:"other_datetime" }}

Formats a date as the time since that date (e.g., 4 days, 6 hours).

Takes an optional argument that is a variable containing the date to use as the comparison point (without the argument, the comparison point is now ). For example, if blog_date is a date instance representing midnight on 1 June 2006, and comment_date is a date instance for 08:00 on 1 June 2006, then

{{ comment_date|timesince:blog_date }} would return 8 hours.

timeuntil

Examples:

{{ datetime|timeuntil }}

{{ datetime|timeuntil:"other_datetime" }}

Similar to timesince , except that it measures the time from now until the given date or datetime. For example, if today is 1 June 2006 and conference_date is a date instance holding 29 June 2006, then {{ conference_date|timeuntil }} will return 28 days.

Takes an optional argument that is a variable containing the date to use as the comparison point (instead of now ). If from_date contains 22 June 2006, then

{{ conference_date|timeuntil:from_date }} will return 7 days.

title

Example:

{{ string|titlecase }}

Converts a string into title case.

truncatewords

Example:

{{ string|truncatewords:"15" }}

Truncates a string after a certain number of words.

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>

Recursively takes a self-nested list and returns an HTML unordered list without

opening and closing <ul> tags.

The list is assumed to be in the proper format. For example, if var contains ['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois', []]]] , then

{{ var|unordered_list }} would return the following:

<li>States

<ul>

<li>Kansas

<ul>

</ul>

</li>

<li>Lawrence</li>

<li>Topeka</li>

</ul>

</li>

upper

例子：

<li>Illinois</li>

{{ string|upper }}

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

urlencode

例子：

<a href="{{ link|urlencode }}">linkage</a> Escapes a value for use in 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" }}

Given a string mapping values for True , False , and (optionally) None , returns one of those strings according to the value (see Table F-4).