Django Book 翻译

Appendix F: Built-in Template Tags and Filters
----------------------------------------------

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

Chapter 4 lists a number of the most useful built-in template tags and filters.
However, Django ships with many more built-in tags and filters. This appendix lists
the ones that were included at the time this book was written, but new tags get
added fairly regularly.

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

The best reference to all the available tags and filters is directly in your admin
interface. Djangos admin interface includes a complete reference of all tags and
filters available for a given site. To see it, go to your admin interface and click
the Documentation link at the upper right of the page.

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

The tags and filters sections of the built-in documentation describe all the
built-in tags (in fact, the tag and filter references in this appendix come
directly from those pages) as well as any custom tag libraries available.

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

For those without an admin site available, reference for the stock tags and filters
follows. Because Django is highly customizable, the reference in your admin site
should be considered the final word on the available tags and filters and what they
do.

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

Built-in Tag Reference
``````````````````````

内建标签参考
````````````

block
'''''

block
'''''

Defines a block that can be overridden by child templates. See the section on
template inheritance in Chapter 4 for more information.

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

comment
'''''''

comment
'''''''

Ignores everything between ``{% comment %}`` and ``{% endcomment %}`` .

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

cycle
'''''

cycle
'''''

Cycles among the given strings each time this tag is encountered.

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

Within a loop, it cycles among the given strings each time through the loop:

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

Outside of a loop, give the values a unique name the first time you call it, and
then use that name each successive time through:

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

You can use any number of values, separated by commas. Make sure not to put spaces
between the values only commas.

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

debug
'''''

debug
'''''

Outputs a whole load of debugging information, including the current context and
imported modules.

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

extends
'''''''

extends
'''''''

Signals that this template extends a parent template.

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

This tag can be used in two ways:

这个标签有两种用法：

*   ``{% extends "base.html" %}`` (with quotes) uses the literal value
    ``"base.html"`` as the name of the parent template to extend.

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

*   ``{% extends variable %}`` uses the value of ``variable`` . If the variable
    evaluates to a string, Django will use that string as the name of the parent
    template. If the variable evaluates to a ``Template`` object, Django will use
    that object as the parent template.

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

See Chapter 4 for many usage examples.

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

filter
''''''

filter
''''''

Filters the contents of the variable through variable filters.

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

Filters can also be piped through each other, and they can have arguments just like
in variable syntax.

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

Heres a sample usage:

看这个用法实例：

firstof
'''''''

firstof
'''''''

Outputs the first variable passed that is not ``False`` . Outputs nothing if all
the passed variables are ``False`` .

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

Heres a sample usage:

看这个用法实例：

This is equivalent to the following:

这等同于如下内容：

for
'''

for
'''

Loops over each item in an array. For example, to display a list of athletes given
``athlete_list`` :

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

You can also loop over a list in reverse by using ``{% for obj in list reversed
%}`` .

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

The ``for`` loop sets a number of variables available within the loop (see Table
F-1).

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

.. table:: Table F-1. Variables Available Inside {% for %}Loops

    +-----------------------+---------------------------------------------------------+
    |Variable               |Description                                              |
    +=======================+=========================================================+
    |``forloop.counter``    |The current iteration of the loop (1-indexed).           |
    +-----------------------+---------------------------------------------------------+
    |``forloop.counter0``   |The current iteration of the loop (0-indexed).           |
    +-----------------------+---------------------------------------------------------+
    |``forloop.revcounter`` |The number of iterations from the end of the loop        |
    |                       |(1-indexed).                                             |
    +-----------------------+---------------------------------------------------------+
    |``forloop.revcounter0``|The number of iterations from the end of the loop        |
    |                       |(0-indexed).                                             |
    +-----------------------+---------------------------------------------------------+
    |``forloop.first``      |``True`` if this is the first time through the loop.     |
    +-----------------------+---------------------------------------------------------+
    |``forloop.last``       |``True`` if this is the last time through the loop.      |
    +-----------------------+---------------------------------------------------------+
    |``forloop.parentloop`` |For nested loops, this is the loop above the current one.|
    +-----------------------+---------------------------------------------------------+
    

.. table:: 表F-1. {% for %}循环中的可用变量

    +-----------------------+---------------------------------------------------------+
    |变量名                 |描述                                                     |
    +=======================+=========================================================+
    |``forloop.counter``    |当前循环次数（索引最小为1）。                            |
    +-----------------------+---------------------------------------------------------+
    |``forloop.counter0``   |当前循环次数 (索引最小为0)。                             |
    +-----------------------+---------------------------------------------------------+
    |``forloop.revcounter`` |剩余循环次数 (索引最小为1)。                             |
    +-----------------------+---------------------------------------------------------+
    |``forloop.revcounter0``|剩余循环次数 (索引最小为0)。                             |
    +-----------------------+---------------------------------------------------------+
    |``forloop.first``      |第一次循环时为 ``True`` 。                               |
    +-----------------------+---------------------------------------------------------+
    |``forloop.last``       |最后一次循环时为 ``True`` 。                             |
    +-----------------------+---------------------------------------------------------+
    |``forloop.parentloop`` |用于嵌套循环，表示当前循环外层的循环。                   |
    +-----------------------+---------------------------------------------------------+
    

if
''

if
''

The ``{% if %}`` tag evaluates a variable, and if that variable is true (i.e., it
exists, is not empty, and is not a false Boolean value), the contents of the block
are output:

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

If ``athlete_list`` is not empty, the number of athletes will be displayed by the
``{{ athlete_list|length }}`` variable.

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

As you can see, the ``if`` tag can take an optional ``{% else %}`` clause that will
be displayed if the test fails.

正如你所见， ``if`` 标签有可选的 ``{% else %}`` 从句，若条件不成立则显示该从句。

``if`` tags may use ``and`` , ``or`` , or ``not`` to test a number of variables or
to negate a given variable:

``if`` 语句可使用 ``and`` 、 ``or`` 和 ``not`` 来测试变量或者对给定的变量取反：

``if`` tags dont allow ``and`` and ``or`` clauses within the same tag, because the
order of logic would be ambiguous. For example, this is invalid:

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

If you need to combine ``and`` and ``or`` to do advanced logic, just use nested
``if`` tags, for example:

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

Multiple uses of the same logical operator are fine, as long as you use the same
operator. For example, this is valid:

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

ifchanged
'''''''''

ifchanged
'''''''''

Checks if a value has changed from the last iteration of a loop.

检查循环中一个值从最近一次重复其是否改变。

The ``ifchanged`` block tag is used within a loop. It has two possible uses:

``ifchanged`` 语句块用于循环中，其作用有两个：

    It checks its own rendered contents against its previous state and only
    displays the content if it has changed. For example, this displays a list of
    days, only displaying the month if it changes:

    它会把要渲染的内容与前一次作比较，发生变化时才显示它。例如，下面要显示一个日期列表，只有月份改变时才会显示它：

    If given a variable, it checks whether that variable has changed:

    如果给的是一个变量，就会检查它是否发生改变。

    The preceding shows the date every time it changes, but it only shows the hour
    if both the hour and the date have changed.

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

ifequal
'''''''

ifequal
'''''''

Outputs the contents of the block if the two arguments equal each other.

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

Heres an example:

举个例子：

As in the ``{% if %}`` tag, an ``{% else %}`` clause is optional.

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

The arguments can be hard-coded strings, so the following is valid:

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

It is only possible to compare an argument to template variables or strings. You
cannot check for equality with Python objects such as ``True`` or ``False`` . If
you need to test if something is true or false, use the ``if`` tag instead.

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

ifnotequal
''''''''''

ifnotequal
''''''''''

Just like ``ifequal`` , except it tests that the two arguments are *not* equal.

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

include
'''''''

include
'''''''

Loads a template and renders it with the current context. This is a way of
including other templates within a template.

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

The template name can be either a variable or a hard-coded (quoted) string, in
either single or double quotes.

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

This example includes the contents of the template ``"foo/bar.html"`` :

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

This example includes the contents of the template whose name is contained in the
variable ``template_name`` :

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

load
''''

load
''''

Loads a custom template library. See Chapter 10 for information about custom
template libraries.

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

now
'''

now
'''

Displays the date, formatted according to the given string.

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

This tag was inspired by, and uses the same format as, a PHPs ``date()`` function
(`http://php.net/date`_). Djangos version, however, has some custom extensions.

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

Table F-2 shows the available format strings.

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

.. table:: Table F-2. Available Date Format Strings

    +---------+--------------------------------------------------------+--------------+
    |Format   |Description                                             |Example Output|
    |Character|                                                        |              |
    +=========+========================================================+==============+
    |a        |``'a.m.'`` or ``'p.m.'`` . (Note that this is slightly  |``'a.m.'``    |
    |         |different from PHPs output, because this includes       |              |
    |         |periods to match Associated Press style.)               |              |
    +---------+--------------------------------------------------------+--------------+
    |A        |``'AM'`` or ``'PM'`` .                                  |``'AM'``      |
    +---------+--------------------------------------------------------+--------------+
    |b        |Month, textual, three letters, lowercase                |``'jan'``     |
    +---------+--------------------------------------------------------+--------------+
    |d        |Day of the month, two digits with leading zeros.        |``'01'`` to   |
    |         |                                                        |``'31'``      |
    +---------+--------------------------------------------------------+--------------+
    |D        |Day of the week, textual, three letters.                |``'Fri'``     |
    +---------+--------------------------------------------------------+--------------+
    |f        |Time, in 12-hour hours and minutes, with minutes left   |``'1'`` ,     |
    |         |off if theyre zero.                                     |``'1:30'``    |
    +---------+--------------------------------------------------------+--------------+
    |F        |Month, textual, long.                                   |``'January'`` |
    +---------+--------------------------------------------------------+--------------+
    |g        |Hour, 12-hour format without leading zeros.             |``'1'`` to    |
    |         |                                                        |``'12'``      |
    +---------+--------------------------------------------------------+--------------+
    |G        |Hour, 24-hour format without leading zeros.             |``'0'`` to    |
    |         |                                                        |``'23'``      |
    +---------+--------------------------------------------------------+--------------+
    |h        |Hour, 12-hour format.                                   |``'01'`` to   |
    |         |                                                        |``'12'``      |
    +---------+--------------------------------------------------------+--------------+
    |H        |Hour, 24-hour format.                                   |``'00'`` to   |
    |         |                                                        |``'23'``      |
    +---------+--------------------------------------------------------+--------------+
    |i        |Minutes.                                                |``'00'`` to   |
    |         |                                                        |``'59'``      |
    +---------+--------------------------------------------------------+--------------+
    |j        |Day of the month without leading zeros.                 |``'1'`` to    |
    |         |                                                        |``'31'``      |
    +---------+--------------------------------------------------------+--------------+
    |l        |Day of the week, textual, long.                         |``'Friday'``  |
    +---------+--------------------------------------------------------+--------------+
    |L        |Boolean for whether its a leap year.                    |``True`` or   |
    |         |                                                        |``False``     |
    +---------+--------------------------------------------------------+--------------+
    |m        |Month, two digits with leading zeros.                   |``'01'`` to   |
    |         |                                                        |``'12'``      |
    +---------+--------------------------------------------------------+--------------+
    |M        |Month, textual, three letters.                          |``'Jan'``     |
    +---------+--------------------------------------------------------+--------------+
    |n        |Month without leading zeros.                            |``'1'`` to    |
    |         |                                                        |``'12'``      |
    +---------+--------------------------------------------------------+--------------+
    |N        |Month abbreviation in Associated Press style.           |``'Jan.'`` ,  |
    |         |                                                        |``'Feb.'`` ,  |
    |         |                                                        |``'March'`` , |
    |         |                                                        |``'May'``     |
    +---------+--------------------------------------------------------+--------------+
    |O        |Difference to Greenwich Mean Time in hours.             |``'+0200'``   |
    +---------+--------------------------------------------------------+--------------+
    |P        |Time, in 12-hour hours, minutes, and a.m./p.m., with    |``'1 a.m.'`` ,|
    |         |minutes left off if theyre zero and the special-case    |``'1:30       |
    |         |strings ``'midnight'`` and ``'noon'`` if appropriate.   |p.m.'`` ,     |
    |         |                                                        |``'midnight'``|
    |         |                                                        |, ``'noon'`` ,|
    |         |                                                        |``'12:30      |
    |         |                                                        |p.m.'``       |
    +---------+--------------------------------------------------------+--------------+
    |r        |RFC 822 formatted date.                                 |``'Thu, 21 Dec|
    |         |                                                        |2000 16:01:07 |
    |         |                                                        |+0200'``      |
    +---------+--------------------------------------------------------+--------------+
    |s        |Seconds, two digits with leading zeros.                 |``'00'`` to   |
    |         |                                                        |``'59'``      |
    +---------+--------------------------------------------------------+--------------+
    |S        |English ordinal suffix for day of the month, two        |``'st'`` ,    |
    |         |characters.                                             |``'nd'`` ,    |
    |         |                                                        |``'rd'`` or   |
    |         |                                                        |``'th'``      |
    +---------+--------------------------------------------------------+--------------+
    |t        |Number of days in the given month.                      |``28`` to     |
    |         |                                                        |``31``        |
    +---------+--------------------------------------------------------+--------------+
    |T        |Time zone of this machine.                              |``'EST'`` ,   |
    |         |                                                        |``'MDT'``     |
    +---------+--------------------------------------------------------+--------------+
    |w        |Day of the week, digits without leading zeros.          |``'0'``       |
    |         |                                                        |(Sunday) to   |
    |         |                                                        |``'6'``       |
    |         |                                                        |(Saturday)    |
    +---------+--------------------------------------------------------+--------------+
    |W        |ISO-8601 week number of year, with weeks starting on    |``1`` , ``23``|
    |         |Monday.                                                 |              |
    +---------+--------------------------------------------------------+--------------+
    |y        |Year, two digits.                                       |``'99'``      |
    +---------+--------------------------------------------------------+--------------+
    |Y        |Year, four digits.                                      |``'1999'``    |
    +---------+--------------------------------------------------------+--------------+
    |z        |Day of the year.                                        |``0`` to      |
    |         |                                                        |``365``       |
    +---------+--------------------------------------------------------+--------------+
    |Z        |Time zone offset in seconds. The offset for time zones  |``-43200`` to |
    |         |west of UTC is always negative, and for those east of   |``43200``     |
    |         |UTC it is always positive.                              |              |
    +---------+--------------------------------------------------------+--------------+
    

.. table:: 表F-2. 可用的日期格式字符串

    +---------+--------------------------------------------------------+--------------+
    |格式字符 |描述                                                    |示例输出      |
    |串       |                                                        |              |
    +=========+========================================================+==============+
    |a        |``'a.m.'`` 或者 ``'p.m.'`` 。（这与PHP中的输出略有不同，|``'a.m.'``    |
    |         |因为为了匹配美联社风格，它包含了句点。                  |              |
    +---------+--------------------------------------------------------+--------------+
    |A        |``'AM'`` 或者 ``'PM'`` 。                               |``'AM'``      |
    +---------+--------------------------------------------------------+--------------+
    |b        |月份，文字式的，三个字母，小写。                        |``'jan'``     |
    +---------+--------------------------------------------------------+--------------+
    |d        |一月的第几天，两位数字，带前导零。                      |``'01'`` 到   |
    |         |                                                        |``'31'``      |
    +---------+--------------------------------------------------------+--------------+
    |D        |一周的第几天，文字式的，三个字母。                      |``'Fri'``     |
    +---------+--------------------------------------------------------+--------------+
    |f        |时间，12小时制的小时和分钟数，如果分钟数为零则不显示。  |``'1'`` ,     |
    |         |                                                        |``'1:30'``    |
    +---------+--------------------------------------------------------+--------------+
    |F        |月份，文字式的，全名。                                  |``'January'`` |
    +---------+--------------------------------------------------------+--------------+
    |g        |小时，12小时制，没有前导零。                            |``'1'`` 到    |
    |         |                                                        |``'12'``      |
    +---------+--------------------------------------------------------+--------------+
    |G        |小时，24小时制，没有前导零。                            |``'0'`` 到    |
    |         |                                                        |``'23'``      |
    +---------+--------------------------------------------------------+--------------+
    |h        |小时，12小时制。                                        |``'01'`` 到   |
    |         |                                                        |``'12'``      |
    +---------+--------------------------------------------------------+--------------+
    |H        |小时，24小时制。                                        |``'00'`` 到   |
    |         |                                                        |``'23'``      |
    +---------+--------------------------------------------------------+--------------+
    |i        |分钟。                                                  |``'00'`` 到   |
    |         |                                                        |``'59'``      |
    +---------+--------------------------------------------------------+--------------+
    |j        |一月的第几天，不带前导零。                              |``'1'`` 到    |
    |         |                                                        |``'31'``      |
    +---------+--------------------------------------------------------+--------------+
    |l        |一周的第几天，文字式的，全名。                          |``'Friday'``  |
    +---------+--------------------------------------------------------+--------------+
    |L        |是否为闰年的布尔值。                                    |``True`` 到   |
    |         |                                                        |``False``     |
    +---------+--------------------------------------------------------+--------------+
    |m        |月份，两位数字，带前导零。                              |``'01'`` 到   |
    |         |                                                        |``'12'``      |
    +---------+--------------------------------------------------------+--------------+
    |M        |月份，文字式的，三个字母。                              |``'Jan'``     |
    +---------+--------------------------------------------------------+--------------+
    |n        |月份，没有前导零。                                      |``'1'`` 到    |
    |         |                                                        |``'12'``      |
    +---------+--------------------------------------------------------+--------------+
    |N        |美联社风格的月份缩写。                                  |``'Jan.'`` ,  |
    |         |                                                        |``'Feb.'`` ,  |
    |         |                                                        |``'March'`` , |
    |         |                                                        |``'May'``     |
    +---------+--------------------------------------------------------+--------------+
    |O        |与格林威治标准时间的时间差（以小时计）。                |``'+0200'``   |
    +---------+--------------------------------------------------------+--------------+
    |P        |时间，12小时制的小时分钟数以及a.m./p.m.，分钟数如果为零 |``'1 a.m.'`` ,|
    |         |则不显示，用字符串表示特殊时间点，如 ``'midnight'`` 和  |``'1:30       |
    |         |``'noon'`` 。                                           |p.m.'`` ,     |
    |         |                                                        |``'midnight'``|
    |         |                                                        |, ``'noon'`` ,|
    |         |                                                        |``'12:30      |
    |         |                                                        |p.m.'``       |
    +---------+--------------------------------------------------------+--------------+
    |r        |RFC 822 格式的日期。                                    |``'Thu, 21 Dec|
    |         |                                                        |2000 16:01:07 |
    |         |                                                        |+0200'``      |
    +---------+--------------------------------------------------------+--------------+
    |s        |秒数，两位数字，带前导零。                              |``'00'`` 到   |
    |         |                                                        |``'59'``      |
    +---------+--------------------------------------------------------+--------------+
    |S        |英语序数后缀，用于表示一个月的第几天，两个字母。        |``'st'`` ,    |
    |         |                                                        |``'nd'`` ,    |
    |         |                                                        |``'rd'`` 到   |
    |         |                                                        |``'th'``      |
    +---------+--------------------------------------------------------+--------------+
    |t        |指定月份的天数。                                        |``28`` 到     |
    |         |                                                        |``31``        |
    +---------+--------------------------------------------------------+--------------+
    |T        |本机的时区。                                            |``'EST'`` ,   |
    |         |                                                        |``'MDT'``     |
    +---------+--------------------------------------------------------+--------------+
    |w        |一周的第几天，数字，带前导零。                          |``'0'``       |
    |         |                                                        |(Sunday) 到   |
    |         |                                                        |``'6'``       |
    |         |                                                        |(Saturday)    |
    +---------+--------------------------------------------------------+--------------+
    |W        |ISO-8601 一年中的第几周，一周从星期一开始。             |``1`` , ``23``|
    +---------+--------------------------------------------------------+--------------+
    |y        |年份，两位数字。                                        |``'99'``      |
    +---------+--------------------------------------------------------+--------------+
    |Y        |年份，四位数字。                                        |``'1999'``    |
    +---------+--------------------------------------------------------+--------------+
    |z        |一年的第几天。                                          |``0`` 到      |
    |         |                                                        |``365``       |
    +---------+--------------------------------------------------------+--------------+
    |Z        |以秒计的时区偏移量，这个偏移量对于UTC西部时区总是负数， |``-43200`` 到 |
    |         |对于UTC东部时区总是正数。                               |``43200``     |
    +---------+--------------------------------------------------------+--------------+
    

Heres an example:

看这个例子：

Note that you can backslash-escape a format string if you want to use the raw
value. In this example, f is backslash-escaped, because otherwise f is a format
string that displays the time. The o doesnt need to be escaped, because its not a
format character:

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

This would display as It is the 4th of September.

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

regroup
'''''''

regroup
'''''''

Regroups a list of alike objects by a common attribute.

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

This complex tag is best illustrated by use of an example. Say that ``people`` is a
list of ``Person`` objects that have ``first_name`` , ``last_name`` , and
``gender`` attributes, and youd like to display a list that looks like this:

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

The following snippet of template code would accomplish this dubious task:

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

As you can see, ``{% regroup %}`` populates a variable with a list of objects with
``grouper`` and ``list`` attributes. ``grouper`` contains the item that was grouped
by; ``list`` contains the list of objects that share that ``grouper`` . In this
case, ``grouper`` would be ``Male`` , ``Female`` , and ``Unknown`` , and ``list``
is the list of people with those genders.

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

Note that ``{% regroup %}`` does not work when the list to be grouped is not sorted
by the key you are grouping by! This means that if your list of people was not
sorted by gender, youd need to make sure it is sorted before using it, that is:

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

spaceless
'''''''''

spaceless
'''''''''

Removes whitespace between HTML tags. This includes tab characters and newlines.

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

Heres an example:

例如：

This example would return this HTML:

返回结果如下：

Only space between *tags* is removed not space between tags and text. In this
example, the space around ``Hello`` wont be stripped:

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

ssi
'''

ssi
'''

Outputs the contents of a given file into the page.

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

Like a simple include tag, ``{% ssi %}`` includes the contents of another file
which must be specified using an absolute path in the current page:

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

If the optional parsed parameter is given, the contents of the included file are
evaluated as template code, within the current context:

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

Note that if you use ``{% ssi %}`` , youll need to define ALLOWED_INCLUDE_ROOTS in
your Django settings, as a security measure.

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

Most of the time ``{% include %}`` works better than ``{% ssi %}`` ; ``{% ssi %}``
exists mostly for backward compatibility.

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

templatetag
'''''''''''

templatetag
'''''''''''

Outputs one of the syntax characters used to compose template tags.

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

Since the template system has no concept of escaping, to display one of the bits
used in template tags, you must use the ``{% templatetag %}`` tag.

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

The argument tells which template bit to output (see Table F-3).

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

.. table:: Table F-3. Valid Arguments to templatetag

    +-----------------+------+
    |Argument         |Output|
    +=================+======+
    |``openblock``    |``{%``|
    +-----------------+------+
    |``closeblock``   |``%}``|
    +-----------------+------+
    |``openvariable`` |``{{``|
    +-----------------+------+
    |``closevariable``|``}}``|
    +-----------------+------+
    |``openbrace``    |``{`` |
    +-----------------+------+
    |``closebrace``   |``}`` |
    +-----------------+------+
    |``opencomment``  |``{#``|
    +-----------------+------+
    |``closecomment`` |``#}``|
    +-----------------+------+
    

.. table:: 表F-3. templatetag的有效参数

    +-----------------+------+
    |参数             |输出  |
    +=================+======+
    |``openblock``    |``{%``|
    +-----------------+------+
    |``closeblock``   |``%}``|
    +-----------------+------+
    |``openvariable`` |``{{``|
    +-----------------+------+
    |``closevariable``|``}}``|
    +-----------------+------+
    |``openbrace``    |``{`` |
    +-----------------+------+
    |``closebrace``   |``}`` |
    +-----------------+------+
    |``opencomment``  |``{#``|
    +-----------------+------+
    |``closecomment`` |``#}``|
    +-----------------+------+
    

url
'''

url
'''

Returns an absolute URL (i.e., a URL without the domain name) matching a given view
function and optional parameters. This is a way to output links without violating
the DRY principle by having to hard-code URLs in your templates:

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

The first argument is a path to a view function in the format
``package.package.module.function`` . Additional arguments are optional and should
be comma-separated values that will be used as positional and keyword arguments in
the URL. All arguments required by the URLconf should be present.

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

For example, suppose you have a view, ``app_name.client`` , whose URLconf takes a
client ID. The URLconf line might look like this:

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

If this applications URLconf is included into the projects URLconf under a path
such as this:

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

then, in a template, you can create a link to this view like this:

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

The template tag will output the string ``/clients/client/123/`` .

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

widthratio
''''''''''

widthratio，寬度的比率

For creating bar charts and such, this tag calculates the ratio of a given value to
a maximum value, and then applies that ratio to a constant.

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

Heres an example:

一些实例：

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
'''

Example:

例如：

Adds the argument to the value.

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

addslashes
''''''''''

Example:

例如：

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

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

capfirst
''''''''

Example:

例如：

Capitalizes the first character of the string.

将字符串的首字母大写

center
''''''

Example:

例如：

Centers the string in a field of a given width.

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

cut
'''

Example:

例如：

Removes all values of the argument from the given string.

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

date
''''

Example:

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

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

default
'''''''

Example:

例如：

If the value is unavailable, use the given default.

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

default_if_none
'''''''''''''''

Example:

例如：

If the value is ``None`` , use the given default.

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

dictsort
''''''''

Example:

例如：

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

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

dictsortreversed
''''''''''''''''

Example:

例子:

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

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

divisibleby
'''''''''''

Example:

Returns ``True`` if the value is divisible by the argument.

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

escape
''''''

Example:

例如：

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

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

*   ``"&"`` to ``"&"``

*   ``<`` to ``"&lt;"``

*   ``>`` to ``">"``

*   ``'"'`` (double quote) to ``'"'``

*   ``"'"`` (single quote) to ``'''``

filesizeformat
''''''''''''''

Example:

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

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

first
'''''

Example:

Returns the first item in a list.

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

fix_ampersands
''''''''''''''

Example:

Replaces ampersands with ``&`` entities.

将 & 符号替换为 & 实体

floatformat
'''''''''''

Examples:

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:

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

*   ``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:

如果使用同一个数字的整数参数，“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:

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.

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

join
''''

Example:

例子：

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

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

length
''''''

Example:

例子：

Returns the length of the value.

返回对象的长度

length_is
'''''''''

Example:

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

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

linebreaks
''''''''''

Example:

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

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

linebreaksbr
''''''''''''

Example:

Converts newlines into ``<br />`` tags.

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

linenumbers
'''''''''''

Example:

Displays text with line numbers.

带行号显示文本

ljust
'''''

Example:

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

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

lower
'''''

Example:

Converts a string into all lowercase.

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

make_list
'''''''''

Example:

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:

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

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

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

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

pluralize
'''''''''

Example:

Returns a plural suffix if the value is not 1. By default, this suffix is ``'s'`` .

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

Example:

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

Example:

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

Example:

pprint
''''''

Example:

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

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

random
''''''

Example:

Returns a random item from the list.

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

removetags
''''''''''

Example:

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

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

rjust
'''''

Example:

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

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

slice
'''''

Example:

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.

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

slugify
'''''''

Example:

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

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

stringformat
''''''''''''

Example:

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.

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

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

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

striptags
'''''''''

Example:

Strips all [X]HTML tags.

过滤掉[X]HTML标签.

time
''''

Example:

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

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

timesince
'''''''''

Examples:

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

格式化一个日期,这个日期是从给定日期到现在的天数和小时数(比如: "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.

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

timeuntil
'''''''''

Examples:

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.

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

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

title
'''''

Example:

Converts a string into title case.

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

truncatewords
'''''''''''''

Example:

Truncates a string after a certain number of words.

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

truncatewords_html
''''''''''''''''''

Example:

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:

Recursively takes a self-nested list and returns an HTML unordered list *without*
opening and closing <ul> tags.

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

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:

假定该列表是合适的格式. 举例来说, 如果 var 的值为 ['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois', []]]], 那么 {{ var|unordered_list }} 就会返回:

upper
'''''

Example:

例子：

Converts a string into all uppercase.

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

urlencode
'''''''''

Example:

例子：

Escapes a value for use in a URL.

转义该值以用于 URL.

urlize
''''''

Example:

例子：

Converts URLs in plain text into clickable links.

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

urlizetrunc
'''''''''''

Example:

例子：

Converts URLs into clickable links, truncating URLs to the given character limit.

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

wordcount
'''''''''

wordcount
'''''''''

Example:

例如：

Returns the number of words.

返回单词数。

wordwrap
''''''''

wordwrap
''''''''

Example:

例如：

Wraps words at a specified line length.

在指定长度将文字换行。

yesno
'''''

yesno
'''''

Example:

例如：

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

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

.. table:: Table F-4. Examples of the yesno Filter

    +---------+-------------------+---------------------------------------------------+
    |Value    |Argument           |Output                                             |
    +=========+===================+===================================================+
    |``True`` |``"yeah,no,maybe"``|``yeah``                                           |
    +---------+-------------------+---------------------------------------------------+
    |``False``|``"yeah,no,maybe"``|``no``                                             |
    +---------+-------------------+---------------------------------------------------+
    |``None`` |``"yeah,no,maybe"``|``maybe``                                          |
    +---------+-------------------+---------------------------------------------------+
    |``None`` |``"yeah,no"``      |``"no"`` (converts ``None`` to ``False`` if no     |
    |         |                   |mapping for ``None`` is given)                     |
    +---------+-------------------+---------------------------------------------------+
    

.. table:: 表F-4. yesno过滤器示例

    +---------+-------------------+---------------------------------------------------+
    |值       |参数               |输出                                               |
    +=========+===================+===================================================+
    |``True`` |``"yeah,no,maybe"``|``yeah``                                           |
    +---------+-------------------+---------------------------------------------------+
    |``False``|``"yeah,no,maybe"``|``no``                                             |
    +---------+-------------------+---------------------------------------------------+
    |``None`` |``"yeah,no,maybe"``|``maybe``                                          |
    +---------+-------------------+---------------------------------------------------+
    |``None`` |``"yeah,no"``      |``"no"`` (如果不存在 ``None`` 的映射，将 ``None``  |
    |         |                   |变为 ``False`` )                                   |
    +---------+-------------------+---------------------------------------------------+