Встроенные теги и фильтры шаблонов

Этот документ описывает встроенные теги и фильтры шаблонов Django. Рекомендуется использовать автоматическую документацию, если таковая имеется, поскольку она также будет включать документацию для любых установленных пользовательских тегов или фильтров.

Справочник по встроенным тегам

autoescape

Управляет текущим автоматическим экранированием. Этот тег принимает в качестве аргумента либо on, либо off и определяет, действует ли автоматическое экранирование внутри блока. Блок закрывается конечным тегом endautoescape.

Когда действует автоматическое экранирование, ко всему содержимому переменных применяется экранирование HTML перед помещением результата в вывод (но после применения любых фильтров). Это эквивалентно применению фильтра escape вручную к каждой переменной.

Единственными исключениями являются переменные, которые уже помечены как «безопасные» от экранирования либо кодом, который заполняет переменную, либо потому, что к ним применены фильтры safe или escape.

Образец использования:

{% autoescape on %}
    {{ body }}
{% endautoescape %}

block

Определяет блок, который может быть переопределен дочерними шаблонами. Смотрите Наследование шаблонов для получения дополнительной информации.

comment

Игнорирует все, что находится между {% comment %} и {% endcomment %}. Необязательное примечание может быть вставлено в первый тег. Например, это полезно при комментировании кода для документирования того, почему код был отключен.

Образец использования:

<p>Rendered text with {{ pub_date|date:"c" }}</p>
{% comment "Optional note" %}
    <p>Commented out text with {{ create_date|date:"c" }}</p>
{% endcomment %}

Теги comment не могут быть вложенными.

csrf_token

Этот тег используется для защиты CSRF, как описано в документации для Подделки межсайтовых запросов.

cycle

Производит один из своих аргументов каждый раз, когда встречается этот тег. Первый аргумент возникает при первой встрече, второй аргумент - при второй встрече и так далее. Как только все аргументы исчерпаны, тег циклически переходит к первому аргументу и производит его снова.

Этот тег особенно полезен в цикле:

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

Первая итерация создает HTML-код, который ссылается на класс row1, второй - на row2, третий снова на row1 и так далее для каждой итерации цикла.

Вы также можете использовать переменные. Например, если у вас есть две переменные шаблона, rowvalue1 и rowvalue2, вы можете чередовать их значения следующим образом:

{% for o in some_list %}
    <tr class="{% cycle rowvalue1 rowvalue2 %}">
        ...
    </tr>
{% endfor %}

Переменные, включенные в цикл, будут экранированы. Вы можете отключить автоматическое экранирование с помощью:

{% for o in some_list %}
    <tr class="{% autoescape off %}{% cycle rowvalue1 rowvalue2 %}{% endautoescape %}">
        ...
    </tr>
{% endfor %}

Вы можете смешивать переменные и строки:

{% for o in some_list %}
    <tr class="{% cycle 'row1' rowvalue2 'row3' %}">
        ...
    </tr>
{% endfor %}

В некоторых случаях вы можете захотеть сослаться на текущее значение цикла без перехода к следующему значению. Для этого дайте тегу {% cycle %} имя, используя «as», например, так:

{% cycle 'row1' 'row2' as rowcolors %}

С этого момента вы можете вставить текущее значение цикла в любое место вашего шаблона, указав имя цикла как контекстную переменную. Если вы хотите переместить цикл к следующему значению независимо от исходного тега cycle, вы можете использовать другой тег cycle и указать имя переменной. Итак, следующий шаблон:

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

выведет:

<tr>
    <td class="row1">...</td>
    <td class="row1">...</td>
</tr>
<tr>
    <td class="row2">...</td>
    <td class="row2">...</td>
</tr>

В теге цикла можно использовать любое количество значений, разделенных пробелами. Значения, заключенные в одинарные кавычки (') или двойные кавычки ("), обрабатываются как строковые литералы, а значения без кавычек обрабатываются как переменные шаблона.

По умолчанию, когда вы используете ключевое слово as с тегом цикла, использование {% cycle %}, которое запускает цикл, само генерирует первое значение в цикле. Это может быть проблемой, если вы хотите использовать значение во вложенном цикле или во включенном шаблоне. Если вы хотите только объявить цикл, но не вывести первое значение, вы можете добавить ключевое слово silent в качестве последнего ключевого слова в теге. Например:

{% for obj in some_list %}
    {% cycle 'row1' 'row2' as rowcolors silent %}
    <tr class="{{ rowcolors }}">{% include "subtemplate.html" %}</tr>
{% endfor %}

Это выведет список элементов <tr>, где class чередуется между row1 и row2. Подшаблон будет иметь доступ к rowcolors в своем контексте, а значение будет соответствовать классу окружающего его элемента <tr>. Если бы ключевое слово silent было опущено, row1 и row2 были бы выданы как обычный текст, за пределами элемента <tr>.

Когда ключевое слово silent используется в определении цикла, тишина автоматически применяется ко всем последующим использованиям этого конкретного тега цикла. Следующий шаблон выведет ничего, даже если второй вызов {% cycle %} не указывает silent:

{% cycle 'row1' 'row2' as rowcolors silent %}
{% cycle rowcolors %}

Вы можете использовать тег resetcycle, чтобы перезапустить тег {% cycle %} с его первого значения, когда он встретится в следующий раз.

debug

Outputs a whole load of debugging information, including the current context and imported modules. {% debug %} outputs nothing when the DEBUG setting is False.

Changed in Django 2.2.27:

В старых версиях отладочная информация отображалась, когда параметр DEBUG имел значение False.

extends

Сигнализирует, что этот шаблон расширяет родительский шаблон.

Этот тег можно использовать двумя способами:

  • {% extends "base.html" %} (в кавычках) использует буквальное значение "base.html" в качестве имени родительского шаблона для расширения.
  • {% extends variable %} использует значение variable. Если переменная вычисляется как строка, Django будет использовать эту строку как имя родительского шаблона. Если переменная оценивается как объект Template, Django будет использовать этот объект в качестве родительского шаблона.

Смотрите Наследование шаблона для получения дополнительной информации.

Обычно имя шаблона указывается относительно корневого каталога загрузчика шаблонов. Строковый аргумент также может быть относительным путем, начинающимся с ./ или ../. Например, предположим следующую структуру каталогов:

dir1/
    template.html
    base2.html
    my/
        base3.html
base1.html

В шаблоне template.html допустимы следующие пути:

{% extends "./base2.html" %}
{% extends "../base1.html" %}
{% extends "./my/base3.html" %}

filter

Фильтрует содержимое блока с помощью одного или нескольких фильтров. С помощью конвейеров можно указать несколько фильтров, а фильтры могут иметь аргументы, как и в синтаксисе переменных.

Обратите внимание, что блок включает весь текст между тегами filter и endfilter.

Образец использования:

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

Примечание

Фильтры escape и :filter:`safe` не являются приемлемыми аргументами. Вместо этого используйте тег autoescape для управления автоматическим экранированием блоков кода шаблона.

firstof

Выводит первую переменную аргумента, которая не является «ложной» (т.е. существует, не пуста, не является ложным булевым значением и не является нулевым числовым значением). Ничего не выводит, если все переданные переменные «ложные».

Образец использования:

{% firstof var1 var2 var3 %}

Это эквивалентно:

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

Вы также можете использовать буквальную строку в качестве резервного значения в случае, если все переданные переменные имеют значение False:

{% firstof var1 var2 var3 "fallback value" %}

Этот тег автоматически экранирует значения переменных. Вы можете отключить автоматическое экранирование с помощью:

{% autoescape off %}
    {% firstof var1 var2 var3 "<strong>fallback value</strong>" %}
{% endautoescape %}

Или, если нужно экранировать только некоторые переменные, вы можете использовать:

{% firstof var1 var2|safe var3 "<strong>fallback value</strong>"|safe %}

Вы можете использовать синтаксис {% firstof var1 var2 var3 as value %} для сохранения вывода внутри переменной.

for

делает цикл по каждому элементу в массиве, делая элемент доступным в переменной контекста. Например, чтобы отобразить список спортсменов из athlete_list:

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

Вы можете перебрать список в обратном порядке, используя {% for obj in list reversed %}.

Если вам нужно перебрать список списков, вы можете распаковать значения в каждом подсписке в отдельные переменные. Например, если ваш контекст содержит список координат (x, y), называемый points, вы можете использовать следующее для вывода списка точек:

{% for x, y in points %}
    There is a point at {{ x }},{{ y }}
{% endfor %}

Это также может быть полезно, если вам нужно получить доступ к элементам в словаре. Например, если ваш контекст содержит словарь data, следующее будет отображать ключи и значения словаря:

{% for key, value in data.items %}
    {{ key }}: {{ value }}
{% endfor %}

Имейте в виду, что для оператора точки поиск ключа словаря имеет приоритет над поиском метода. Поэтому, если словарь data содержит ключ с именем 'items', data.items вернет data['items'] вместо data.items(). Избегайте добавления ключей с именами как словарные методы, если вы хотите использовать эти методы в шаблоне (items, values, keys и т.д.). Дополнительные сведения о порядке поиска оператора точки смотрите в документации по переменным шаблона.

Цикл for устанавливает ряд переменных, доступных в цикле:

Переменная Описание
forloop.counter Текущая итерация цикла (начинается с индекса 1)
forloop.counter0 Текущая итерация цикла (начинается с индекса 0)
forloop.revcounter Количество итераций с конца цикла (начинается с индекса 1)
forloop.revcounter0 Количество итераций с конца цикла (начинается с индекса 0)
forloop.first True, если это первый раз в цикле
forloop.last True, если это последняя итерация цикла
forloop.parentloop Для вложенных циклов это цикл, окружающий текущий.

forempty

Тег for может принимать необязательное предложение {% empty %}, текст которого отображается, если данный массив пуст или не может быть найден:

<ul>
{% for athlete in athlete_list %}
    <li>{{ athlete.name }}</li>
{% empty %}
    <li>Sorry, no athletes in this list.</li>
{% endfor %}
</ul>

Вышеупомянутое эквивалентно - но короче, чище и, возможно, быстрее - следующему:

<ul>
  {% if athlete_list %}
    {% for athlete in athlete_list %}
      <li>{{ athlete.name }}</li>
    {% endfor %}
  {% else %}
    <li>Sorry, no athletes in this list.</li>
  {% endif %}
</ul>

if

Тег {% if %} оценивает переменную, и если эта переменная имеет значение «истина» (т.е. существует, не пуста и не является логическим значением false), выводится содержимое блока:

{% if athlete_list %}
    Number of athletes: {{ athlete_list|length }}
{% elif athlete_in_locker_room_list %}
    Athletes should be out of the locker room soon!
{% else %}
    No athletes.
{% endif %}

В приведенном выше примере, если athlete_list не пустой, количество спортсменов будет отображаться переменной {{ athlete_list|length}}.

Как видите, тег if может принимать одно или несколько предложений {% elif %}, а также предложение {% 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.
{% endif %}

{% if athlete_list and not coach_list %}
    There are some athletes and absolutely no coaches.
{% endif %}

Допускается использование предложений and и or в одном теге, причем and имеет более высокий приоритет, чем or, например:

{% if athlete_list and coach_list or cheerleader_list %}

будет интерпретироваться как:

if (athlete_list and coach_list) or cheerleader_list

Использование круглых скобок в теге if является недопустимым синтаксисом. Если вам нужно, чтобы они указывали приоритет, вы должны использовать вложенные теги if.

В теге if также можно использовать операторы ==, !=, <, >, <=, >=, in, not in, is, и is not которые работают следующим образом:

оператор ==

Равенство. Пример:

{% if somevar == "x" %}
  This appears if variable somevar equals the string "x"
{% endif %}
Оператор !=

Неравенство. Пример:

{% if somevar != "x" %}
  This appears if variable somevar does not equal the string "x",
  or if somevar is not found in the context
{% endif %}
Оператор <

Меньше, чем. Пример:

{% if somevar < 100 %}
  This appears if variable somevar is less than 100.
{% endif %}
Оператор >

Больше чем. Пример:

{% if somevar > 0 %}
  This appears if variable somevar is greater than 0.
{% endif %}
Оператор <=

Меньше или равно. Пример:

{% if somevar <= 100 %}
  This appears if variable somevar is less than 100 or equal to 100.
{% endif %}
Оператор >=

Больше или равно. Пример:

{% if somevar >= 1 %}
  This appears if variable somevar is greater than 1 or equal to 1.
{% endif %}
Оператор in

Содержится в. Этот оператор поддерживается многими контейнерами Python, чтобы проверить, находится ли данное значение в контейнере. Ниже приведены несколько примеров того, как будет интерпретироваться x in y:

{% if "bc" in "abcdef" %}
  This appears since "bc" is a substring of "abcdef"
{% endif %}

{% if "hello" in greetings %}
  If greetings is a list or set, one element of which is the string
  "hello", this will appear.
{% endif %}

{% if user in users %}
  If users is a QuerySet, this will appear if user is an
  instance that belongs to the QuerySet.
{% endif %}
Оператор not in

Не содержится внутри. Это отрицание оператора in.

Оператор is

Идентичность объекта. Проверяет, являются ли два значения одним и тем же объектом. Пример:

{% if somevar is True %}
  This appears if and only if somevar is True.
{% endif %}

{% if somevar is None %}
  This appears if somevar is None, or if somevar is not found in the context.
{% endif %}
Оператор is not

Отрицательная идентичность объекта. Проверяет, не являются ли два значения одним и тем же объектом. Это отрицание оператора is. Пример:

{% if somevar is not True %}
  This appears if somevar is not True, or if somevar is not found in the
  context.
{% endif %}

{% if somevar is not None %}
  This appears if and only if somevar is not None.
{% endif %}

Фильтры

Вы также можете использовать фильтры в выражении if. Например:

{% if messages|length >= 100 %}
   You have lots of messages today!
{% endif %}

Сложные выражения

Все вышеперечисленное можно комбинировать для образования сложных выражений. Для таких выражений может быть важно знать, как группируются операторы при вычислении выражения, то есть правила приоритета. Приоритет операторов, от низшего к высшему, следующий:

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

(Это в точности соответствует Python). Так, например, следующий комплекс if:

{% if a == b or c == d and e %}

…будет интерпретироваться как:

(a == b) or ((c == d) and e)

Если вам нужен другой приоритет, вам нужно будет использовать вложенные теги if. Иногда это лучше для ясности, для тех, кто не знает правил приоритета.

Операторы сравнения не могут быть связаны, как в Python или в математической нотации. Например, вместо использования:

{% if a > b > c %}  (WRONG)

вы должны использовать:

{% if a > b and b > c %}

ifequal и ifnotequal

Не рекомендуется, начиная с версии 3.1.

{% ifequal a b %} ... {% endifequal %} - это устаревший способ записи {% if a == b %} ... {% endif %}. Аналогично, {% ifnotequal a b %} ... {% endifnotequal %} вытесняется {% if a != b %} ... {% endif %}.

ifchanged

Проверьте, изменилось ли значение с последней итерации цикла.

Тег блока {% ifchanged %} используется внутри цикла. У него есть два возможных применения.

  1. Проверяет собственное отображаемое содержимое на соответствие его предыдущему состоянию и отображает содержимое только в том случае, если оно изменилось. Например, здесь отображается список дней, а месяц отображается только в случае его изменения:

    <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 %}
    
  2. Если задана одна или несколько переменных, проверяет, не изменилась ли какая-либо переменная. Например, следующее показывает дату каждый раз, когда она изменяется, и показывает час, если час или дата изменились:

    {% for date in days %}
        {% ifchanged date.date %} {{ date.date }} {% endifchanged %}
        {% ifchanged date.hour date.date %}
            {{ date.hour }}
        {% endifchanged %}
    {% endfor %}
    

Тег ifchanged также может принимать необязательное предложение {% else %}, которое будет отображаться, если значение не изменилось:

{% for match in matches %}
    <div style="background-color:
        {% ifchanged match.ballot_id %}
            {% cycle "red" "blue" %}
        {% else %}
            gray
        {% endifchanged %}
    ">{{ match }}</div>
{% endfor %}

include

Загружает шаблон и отображает его с текущим контекстом. Это способ «включения» других шаблонов в шаблон.

Имя шаблона может быть переменной или жестко закодированной (заключенной в кавычки) строкой в одинарных или двойных кавычках.

Этот пример включает содержимое шаблона "foo/bar.html":

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

Обычно имя шаблона указывается относительно корневого каталога загрузчика шаблонов. Строковый аргумент также может быть относительным путем, начинающимся с ./ Или ../, как описано в теге extends.

Этот пример включает содержимое шаблона, имя которого содержится в переменной template_name:

{% include template_name %}

Переменная также может быть любым объектом с методом render(), который принимает контекст. Это позволяет вам ссылаться на скомпилированный Template в вашем контексте.

Кроме того, переменная может быть итерабельной по именам шаблонов, в этом случае будет использоваться первое, которое может быть загружено, согласно select_template().

Включенный шаблон отображается в контексте шаблона, который его включает. В этом примере создается вывод "Hello, John!":

  • Контекст: для переменной person установлено значение "John", а для переменной greeting - значение "Hello".

  • Шаблон:

    {% include "name_snippet.html" %}
    
  • Шаблон name_snippet.html:

    {{ greeting }}, {{ person|default:"friend" }}!
    

Вы можете передать дополнительный контекст в шаблон, используя ключевое слово arguments:

{% include "name_snippet.html" with person="Jane" greeting="Hello" %}

Если вы хотите отображать контекст только с предоставленными переменными (или даже без переменных), используйте параметр only. Для включенного шаблона нет других переменных:

{% include "name_snippet.html" with greeting="Hi" only %}

Примечание

Тег include следует рассматривать как реализацию «отрисовать этот подшаблон и включить HTML», а не как «проанализировать этот подшаблон и включить его содержимое, как если бы оно было частью родительского». Это означает, что между включенными шаблонами нет общего состояния - каждое включение - это полностью независимый процесс рендеринга.

Блоки оцениваются перед включением. Это означает, что шаблон, который включает блоки из другого, будет содержать блоки, которые уже были оценены и обработаны, а не блоки, которые могут быть переопределены, например, расширяющимся шаблоном.

Changed in Django 3.1:

Добавлена поддержка итераций имен шаблонов.

load

Загружает настраиваемый набор тегов шаблона.

Например, следующий шаблон загрузит все теги и фильтры, зарегистрированные в somelibrary и otherlibrary, расположенных в пакете package:

{% load somelibrary package.otherlibrary %}

Вы также можете выборочно загружать отдельные фильтры или теги из библиотеки, используя аргумент from. В этом примере теги/фильтры шаблона с именами foo и bar будут загружены из somelibrary:

{% load foo bar from somelibrary %}

Смотрите Пользовательские библиотеки тегов и фильтров для получения дополнительной информации.

lorem

Отображает случайный латинский текст «lorem ipsum». Это полезно для предоставления образцов данных в шаблонах.

Использование:

{% lorem [count] [method] [random] %}

Тег {% lorem %} может использоваться с нулем, одним, двумя или тремя аргументами. Аргументы следующие:

Аргумент Описание
count Число (или переменная), содержащее количество абзацев или слов для создания (по умолчанию 1).
method w для слов, p для абзацев HTML или b для блоков абзацев с обычным текстом (по умолчанию - b).
random Слово random, если оно задано, не использует общий абзац («Lorem ipsum dolor sit amet…») при генерации текста.

Примеры:

  • {% lorem %} выведет общий абзац «lorem ipsum».
  • {% lorem 3 p %} выведет общий абзац «lorem ipsum» и два случайных абзаца, каждый из которых заключен в теги HTML <p>.
  • {% lorem 2 w random %} выведет два случайных латинских слова.

now

Отображает текущую дату и/или время в формате, соответствующем заданной строке. Такая строка может содержать символы спецификаторов формата, как описано в разделе фильтра date.

Пример:

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

Обратите внимание, что вы можете экранировать строку формата с помощью обратной косой черты, если хотите использовать «сырое» значение. В этом примере и «o», и «f» экранированы обратной косой чертой, потому что в противном случае каждая из них представляет собой строку формата, которая отображает год и время соответственно:

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

Это будет отображаться как «It is the 4th of September».

Примечание

Переданный формат также может быть одним из предопределенных DATE_FORMAT, DATETIME_FORMAT, SHORT_DATE_FORMAT или SHORT_DATETIME_FORMAT. Предопределенные форматы могут различаться в зависимости от текущей локали и, если Локализация формата включен, например:

It is {% now "SHORT_DATETIME_FORMAT" %}

Вы также можете использовать синтаксис {% now "Y" as current_year %} для хранения вывода (в виде строки) внутри переменной. Это полезно, если вы хотите использовать {% now %} внутри тега шаблона, например blocktranslate:

{% now "Y" as current_year %}
{% blocktranslate %}Copyright {{ current_year }}{% endblocktranslate %}

regroup

Группирует список похожих объектов по общему атрибуту.

Этот сложный тег лучше всего проиллюстрировать на примере: скажем, что cities - это список городов, представленных словарями, содержащими "name", "population" и "country" ключи:

cities = [
    {'name': 'Mumbai', 'population': '19,000,000', 'country': 'India'},
    {'name': 'Calcutta', 'population': '15,000,000', 'country': 'India'},
    {'name': 'New York', 'population': '20,000,000', 'country': 'USA'},
    {'name': 'Chicago', 'population': '7,000,000', 'country': 'USA'},
    {'name': 'Tokyo', 'population': '33,000,000', 'country': 'Japan'},
]

…и вы хотите отобразить иерархический список, отсортированный по странам, например:

  • Индия
    • Мумбаи: 19,000,000
    • Калькутта: 15,000,000
  • USA
    • New York: 20,000,000
    • Chicago: 7,000,000
  • Japan
    • Tokyo: 33,000,000

Вы можете использовать тег {% regroup %}, чтобы сгруппировать список городов по странам. Следующий фрагмент кода шаблона выполнит это:

{% regroup cities by country as country_list %}

<ul>
{% for country in country_list %}
    <li>{{ country.grouper }}
    <ul>
        {% for city in country.list %}
          <li>{{ city.name }}: {{ city.population }}</li>
        {% endfor %}
    </ul>
    </li>
{% endfor %}
</ul>

Давайте рассмотрим этот пример. {% regroup %} принимает три аргумента: список, который вы хотите перегруппировать, атрибут, по которому нужно группировать, и имя результирующего списка. Здесь мы перегруппируем список cities по атрибуту country и вызываем результат country_list.

{% regroup %} создает список (в данном случае country_list) групповых объектов. Объекты группы - это экземпляры namedtuple() с двумя полями:

  • grouper – элемент, который был сгруппирован (например, строка «India» или «Japan»).
  • list – список всех элементов в этой группе (например, список всех городов с country=“India“).

Поскольку {% regroup %} производит объекты namedtuple(), вы также можете записать предыдущий пример как:

{% regroup cities by country as country_list %}

<ul>
{% for country, local_cities in country_list %}
    <li>{{ country }}
    <ul>
        {% for city in local_cities %}
          <li>{{ city.name }}: {{ city.population }}</li>
        {% endfor %}
    </ul>
    </li>
{% endfor %}
</ul>

Обратите внимание, что {% regroup %} не упорядочивает свой ввод! Наш пример основан на том факте, что список cities был упорядочен в первую очередь по country. Если бы список cities не упорядочивал своих участников по country, перегруппировка наивно отображала бы более одной группы для одной страны. Например, предположим, что список cities был настроен на это (обратите внимание, что страны не сгруппированы вместе):

cities = [
    {'name': 'Mumbai', 'population': '19,000,000', 'country': 'India'},
    {'name': 'New York', 'population': '20,000,000', 'country': 'USA'},
    {'name': 'Calcutta', 'population': '15,000,000', 'country': 'India'},
    {'name': 'Chicago', 'population': '7,000,000', 'country': 'USA'},
    {'name': 'Tokyo', 'population': '33,000,000', 'country': 'Japan'},
]

С этим вводом для cities пример кода шаблона {% regroup %}, приведенный выше, приведет к следующему результату:

  • Индия
    • Мумбаи: 19,000,000
  • USA
    • New York: 20,000,000
  • Индия
    • Калькутта: 15,000,000
  • USA
    • Chicago: 7,000,000
  • Japan
    • Tokyo: 33,000,000

Самое простое решение этой проблемы - убедиться в коде представления, что данные упорядочены в соответствии с тем, как вы хотите их отображать.

Другое решение - отсортировать данные в шаблоне с помощью фильтра dictsort, если ваши данные находятся в списке словарей:

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

Группировка по другим свойствам

Любой допустимый поиск в шаблоне является допустимым атрибутом группировки для тега перегруппировки, включая методы, атрибуты, ключи словаря и элементы списка. Например, если поле «страна» является внешним ключом для класса с атрибутом «описание», вы можете использовать:

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

Или, если country`- это поле с ``choices, у него будет метод get_FOO_display(), доступный как атрибут, позволяющий группировать по строке описания, а не ключу choices:

{% regroup cities by get_country_display as country_list %}

{{ country.grouper }} теперь будет отображать поля значений из набора choices, а не ключи.

resetcycle

Сбрасывает предыдущий cycle, так что он перезапускается с первого элемента при следующем проходе. Без аргументов {% resetcycle %} сбросит последний {% cycle %}, определенный в шаблоне.

Пример использования:

{% for coach in coach_list %}
    <h1>{{ coach.name }}</h1>
    {% for athlete in coach.athlete_set.all %}
        <p class="{% cycle 'odd' 'even' %}">{{ athlete.name }}</p>
    {% endfor %}
    {% resetcycle %}
{% endfor %}

Этот пример вернет этот HTML:

<h1>José Mourinho</h1>
<p class="odd">Thibaut Courtois</p>
<p class="even">John Terry</p>
<p class="odd">Eden Hazard</p>

<h1>Carlo Ancelotti</h1>
<p class="odd">Manuel Neuer</p>
<p class="even">Thomas Müller</p>

Обратите внимание, как первый блок заканчивается на class="odd", а новый начинается на class="odd". Без тега {% resetcycle %} второй блок будет начинаться с class="even".

Вы также можете сбросить именованные теги цикла:

{% for item in list %}
    <p class="{% cycle 'odd' 'even' as stripe %} {% cycle 'major' 'minor' 'minor' 'minor' 'minor' as tick %}">
        {{ item.data }}
    </p>
    {% ifchanged item.category %}
        <h1>{{ item.category }}</h1>
        {% if not forloop.first %}{% resetcycle tick %}{% endif %}
    {% endifchanged %}
{% endfor %}

В этом примере у нас есть как чередующиеся нечетные/четные строки, так и «основная» строка в каждой пятой строке. При изменении категории сбрасывается только пятистрочный цикл.

spaceless

Удаляет пробелы между тегами HTML. Сюда входят символы табуляции и новые строки.

Пример использования:

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

Этот пример вернет этот HTML:

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

Удаляется только пробел между тегами, но не пробел между тегами и текстом. В этом примере пространство вокруг Hello не будет удалено:

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

templatetag

Выводит один из синтаксических символов, используемых для создания тегов шаблона.

Поскольку в системе шаблонов нет концепции «экранирования», для отображения одного из битов, используемых в тегах шаблона, вы должны использовать тег {% templatetag %}.

Аргумент сообщает, какой бит шаблона выводить:

Аргумент Выходы
openblock {%
closeblock %}
openvariable {{
closevariable }}
openbrace {
closebrace }
opencomment {#
closecomment #}

Образец использования:

{% templatetag openblock %} url 'entry_list' {% templatetag closeblock %}

url

Возвращает ссылку на абсолютный путь (URL без имени домена), соответствующую заданному представлению и необязательным параметрам. Любые специальные символы в полученном пути будут закодированы с использованием iri_to_uri().

Это способ вывода ссылок без нарушения принципа DRY за счет необходимости жесткого кодирования URL-адресов в ваших шаблонах:

{% url 'some-url-name' v1 v2 %}

Первый аргумент - это Имя шаблона URL. Это может быть литерал в кавычках или любая другая контекстная переменная. Дополнительные аргументы являются необязательными и должны быть значениями, разделенными пробелами, которые будут использоваться в качестве аргументов в URL-адресе. В приведенном выше примере показана передача позиционных аргументов. В качестве альтернативы вы можете использовать синтаксис ключевого слова:

{% url 'some-url-name' arg1=v1 arg2=v2 %}

Не смешивайте позиционный синтаксис и синтаксис ключевых слов в одном вызове. Должны присутствовать все аргументы, требуемые URLconf.

Например, предположим, что у вас есть представление app_views.client, URLconf которого принимает идентификатор клиента (здесь client() - это метод внутри файла представлений app_views.py). Строка URLconf может выглядеть так:

path('client/<int:id>/', app_views.client, name='app-views-client')

Если URLconf этого приложения включен в URLconf проекта по следующему пути:

path('clients/', include('project_name.app_name.urls'))

…затем в шаблоне вы можете создать ссылку на это представление следующим образом:

{% url 'app-views-client' client.id %}

Тег шаблона выведет строку /clients/client/123/.

Обратите внимание: если URL-адрес, который вы определяете, не существует, вы получите исключение NoReverseMatch, которое приведет к отображению страницы с ошибкой на вашем сайте.

Если вы хотите получить URL-адрес, не отображая его, вы можете использовать немного другой вызов:

{% url 'some-url-name' arg arg2 as the_url %}

<a href="{{ the_url }}">I'm linking to {{ the_url }}</a>

Область видимости переменной, созданной синтаксисом as var, - это {% block %}, в которой появляется тег {% url %}.

Этот синтаксис {% url ... as var %} не вызовет ошибку, если представление отсутствует. На практике вы будете использовать это для ссылки на необязательные представления:

{% url 'some-url-name' as the_url %}
{% if the_url %}
  <a href="{{ the_url }}">Link to optional stuff</a>
{% endif %}

Если вы хотите получить URL-адрес в пространстве имен, укажите полное имя:

{% url 'myapp:view-name' %}

Это будет следовать обычной стратегии :ref:`разрешения URL-адресов в пространстве имен <topics-http-reversing-url-namespaces>, включая использование любых подсказок, предоставляемых контекстом для текущего приложения.

Предупреждение

Не забудьте заключить в кавычки шаблон URL-адреса name, иначе значение будет интерпретировано как переменная контекста!

verbatim

Останавливает механизм шаблонов от рендеринга содержимого этого тега блока.

Обычно используется для разрешения в шаблоне JavaScript, который конфликтует с синтаксисом Django. Например:

{% verbatim %}
    {{if dying}}Still alive.{{/if}}
{% endverbatim %}

Вы также можете назначить специальный закрывающий тег, позволяющий использовать {% endverbatim %} как часть неотрисованного содержимого:

{% verbatim myblock %}
    Avoid template rendering via the {% verbatim %}{% endverbatim %} block.
{% endverbatim myblock %}

widthratio

Для создания гистограмм и т.п. этот тег вычисляет отношение заданного значения к максимальному значению, а затем применяет это отношение к константе.

Например:

<img src="bar.png" alt="Bar"
     height="10" width="{% widthratio this_value max_value max_width %}">

Если this_value равно 175, max_value равно 200, а max_width равно 100, изображение в приведенном выше примере будет иметь ширину 88 пикселей (потому что 175/200 = 0,875; 0,875 * 100 = 87,5, что округляется до 88).

В некоторых случаях вы можете захотеть записать результат widthratio в переменную. Это может быть полезно, например, в blocktranslate, как это:

{% widthratio this_value max_value max_width as width %}
{% blocktranslate %}The width is: {{ width }}{% endblocktranslate %}

with

Кэширует сложную переменную под более простым именем. Это полезно при многократном доступе к «дорогостоящему» методу (например, тот, который делает запрос в базу данных).

Например:

{% with total=business.employees.count %}
    {{ total }} employee{{ total|pluralize }}
{% endwith %}

Заполненная переменная (в приведенном выше примере total) доступна только между тегами {% with %} и {% endwith %}.

Вы можете назначить более одной контекстной переменной:

{% with alpha=1 beta=2 %}
    ...
{% endwith %}

Примечание

По-прежнему поддерживается предыдущий более подробный формат: {% with business.employees.count as total %}

Справочник по встроенному фильтру

add

Добавляет аргумент к значению.

Например:

{{ value|add:"2" }}

Если value равно 4, то на выходе будет 6.

Этот фильтр сначала попытается преобразовать оба значения в целые числа. Если это не удастся, он все равно попытается сложить значения. Это будет работать с некоторыми типами данных (строки, список и т.д.) И не работать с другими. В случае неудачи результатом будет пустая строка.

Например, если у нас есть:

{{ first|add:second }}

и first равно [1, 2, 3], а second - [4, 5, 6], тогда вывод будет [1, 2, 3 , 4, 5, 6].

Предупреждение

Строки, которые можно привести к целым числам, будут суммироваться, а не объединяться, как в первом примере выше.

addslashes

Добавляет косую черту перед кавычками. Полезно, например, для экранирования строк в CSV.

Например:

{{ value|addslashes }}

Если value равно "I'm using Django", вывод будет "I\'m using Django".

capfirst

Делает первый символ значения заглавным. Если первый символ не является буквой, этот фильтр не действует.

Например:

{{ value|capfirst }}

Если value равно django, вывод будет Django.

center

Центрирует значение в поле заданной ширины.

Например:

"{{ value|center:"15" }}"

Если value равно "Django", вывод будет "     Django    ".

cut

Удаляет все значения arg из данной строки.

Например:

{{ value|cut:" " }}

Если value равно "String with spaces", вывод будет "Stringwithspaces".

date

Форматирует дату в соответствии с заданным форматом.

Uses a similar format to PHP’s date() function with some differences.

Примечание

Эти символы формата не используются в Django вне шаблонов. Они были разработаны, чтобы быть совместимыми с PHP, чтобы облегчить переход для дизайнеров.

Доступные форматные строки:

Формат символа Описание Пример вывода
День    
d День месяца, 2 цифры с ведущими нулями. От '01'``до ``'31'
j День месяца без ведущих нулей. От '1'``до ``'31'
D День недели, текстовый, 3 буквы. 'Fri'
l День недели, текстовый, длинный. 'Friday'
S Английский порядковый суффикс дня месяца, 2 символа. 'st', 'nd', 'rd' или 'th'
w День недели, цифры без ведущих нулей. '0' (Воскресенье) - '6' (Суббота)
z День года. От 1 до 366
Неделя    
W Номер недели в году согласно ISO-8601, недели начинаются с понедельника. 1, 53
Месяц    
m Месяц, 2 цифры с ведущими нулями. От '01' до '12'
n Месяц без ведущих нулей. '1' - '12'
M Месяц, текстовый, 3 буквы. 'Jan'
b Месяц, текстовое, 3 буквы, строчные. 'jan'
E Месяц, альтернативное представление для конкретной локали, обычно используемое для представления длинной даты. 'listopada' (для польского языка, в отличие от 'Listopad')
F Месяц, текстовый, длинный. 'January'
N Аббревиатура месяца в стиле Associated Press. Собственное расширение. 'Jan.', 'Feb.', 'March', 'May'
t Количество дней в данном месяце. 28 to 31
Год    
y Год, 2 цифры с ведущими нулями. от '00' до '99'
Y Год, 4 цифры. '1999'
L Логическое значение високосного года. True или False
o Год нумерации недель ISO-8601, соответствующий номеру недели ISO-8601 (W), в котором используются високосные недели. Смотрите Y для более распространенного формата года. '1999'
Время    
g Часовой 12-часовой формат без ведущих нулей. '1' - '12'
G Часовой, 24-часовой формат без ведущих нулей. '0' - '23'
h Часовой, 12-часовой формат. От '01' до '12'
H Часовой, 24-часовой формат. '00' - '23'
i Минуты. '00' - '59'
s Секунды, 2 цифры с ведущими нулями. '00' - '59'
u Микросекунды. 000000 - 999999
a 'a.m.' или 'p.m.' (обратите внимание, что это немного отличается от вывода PHP, потому что он включает точки, соответствующие стилю Associated Press.) 'a.m.'
A 'AM' или 'PM'. 'AM'
f Время в 12-часовых часах и минутах с отсечкой минут, если они равны нулю. Собственное расширение. '1', '1:30'
P Время в 12-часовых часах, минутах и „a.m.“/“p.m.“, с оставленными минутами, если они равны нулю, и специальными строками «полночь» и «полдень», если необходимо. Собственное расширение. '1 a.m.', '1:30 p.m.', 'midnight', 'noon', '12:30 p.m.'
Часовой пояс    
e Название часового пояса. Может быть в любом формате или может возвращать пустую строку в зависимости от даты и времени. '', 'GMT', '-500', 'US/Eastern' и т.п.
I Летнее время, независимо от того, действует оно или нет. '1' или '0'
O Разница в часах по Гринвичу. '+0200'
T Часовой пояс этой машины. 'EST', 'MDT'
Z Смещение часового пояса в секундах. Смещение для часовых поясов к западу от UTC всегда отрицательно, а для часовых поясов к востоку от UTC всегда положительно. -43200 - 43200
Дата/Время    
c Формат ISO 8601. (Примечание: в отличие от других форматеров, таких как «Z», «O» или «r», форматер «c» не добавляет смещение часового пояса, если значение является наивным datetime (см. datetime.tzinfo). 2008-01-02T10:30:00.000123+02:00, или 2008-01-02T10:30:00.000123, если дататайм является наивным
r RFC 5322 форматированная дата. 'Thu, 21 Dec 2000 16:01:07 +0200'
U Секунды с эпохи Unix (1 января 1970 00:00:00 UTC).  

Например:

{{ value|date:"D d M Y" }}

Если value является объектом datetime (например, результатом datetime.datetime.now()), то на выходе будет строка 'Wed 09 Jan 2008'.

Передаваемый формат может быть одним из предопределенных форматов DATE_FORMAT, DATETIME_FORMAT, SHORT_DATE_FORMAT или SHORT_DATETIME_FORMAT, или пользовательским форматом, использующим спецификаторы формата, приведенные в таблице выше. Обратите внимание, что предопределенные форматы могут отличаться в зависимости от текущей локали.

Если предположить, что USE_L10N есть True, а LANGUAGE_CODE есть, например, "es", то для:

{{ value|date:"SHORT_DATE_FORMAT" }}

на выходе будет строка "09/01/2008" (спецификатором формата "SHORT_DATE_FORMAT" для локали es, поставляемой с Django, является "d/m/Y").

При использовании без строки формата используется спецификатор формата DATE_FORMAT. Предполагая те же настройки, что и в предыдущем примере:

{{ value|date }}

выводит 9 de Enero de 2008 (спецификатором формата DATE_FORMAT для локали es является r'j \d\e F \d\e Y'). И «d», и «e» имеют обратную косую черту, поскольку в противном случае каждая из них является форматной строкой, отображающей день и название часового пояса, соответственно.

Вы можете комбинировать date с фильтром time, чтобы получить полное представление значения datetime. Например:

{{ value|date:"D d M Y" }} {{ value|time:"H:i" }}

default

Если значение равно False, используется заданное значение по умолчанию. В противном случае используется значение.

Например:

{{ value|default:"nothing" }}

Если value равно "" (пустая строка), то на выходе будет nothing.

default_if_none

Если (и только если) значение равно None, используется заданное значение по умолчанию. В противном случае используется значение.

Обратите внимание, что если задана пустая строка, значение по умолчанию не будет использоваться. Используйте фильтр default, если вы хотите отступать для пустых строк.

Например:

{{ value|default_if_none:"nothing" }}

Если value равно None, то на выходе будет nothing.

dictsort

Принимает список словарей и возвращает этот список, отсортированный по ключу, указанному в аргументе.

Например:

{{ value|dictsort:"name" }}

Если value есть:

[
    {'name': 'zed', 'age': 19},
    {'name': 'amy', 'age': 22},
    {'name': 'joe', 'age': 31},
]

тогда вывод будет таким:

[
    {'name': 'amy', 'age': 22},
    {'name': 'joe', 'age': 31},
    {'name': 'zed', 'age': 19},
]

Вы также можете делать более сложные вещи, например:

{% for book in books|dictsort:"author.age" %}
    * {{ book.title }} ({{ book.author.name }})
{% endfor %}

Если books есть:

[
    {'title': '1984', 'author': {'name': 'George', 'age': 45}},
    {'title': 'Timequake', 'author': {'name': 'Kurt', 'age': 75}},
    {'title': 'Alice', 'author': {'name': 'Lewis', 'age': 33}},
]

тогда на выходе будет:

* Alice (Lewis)
* 1984 (George)
* Timequake (Kurt)

dictsort может также упорядочить список списков (или любой другой объект, реализующий __getitem__()) по элементам с указанным индексом. Например:

{{ value|dictsort:0 }}

Если value есть:

[
    ('a', '42'),
    ('c', 'string'),
    ('b', 'foo'),
]

тогда вывод будет таким:

[
    ('a', '42'),
    ('b', 'foo'),
    ('c', 'string'),
]

Вы должны передать индекс как целое число, а не как строку. Следующие команды выдают пустой результат:

{{ values|dictsort:"0" }}

Упорядочивание по элементам с указанным индексом не поддерживается для словарей.

Changed in Django 2.2.26:

В старых версиях для словарей поддерживалось упорядочивание элементов по указанному индексу.

dictsortreversed

Принимает список словарей и возвращает этот список, отсортированный в обратном порядке по ключу, указанному в аргументе. Это работает точно так же, как и фильтр выше, но возвращаемое значение будет в обратном порядке.

divisibleby

Возвращает True, если значение делится на аргумент.

Например:

{{ value|divisibleby:"3" }}

Если value будет 21, то выходом будет True.

escape

Экранирует HTML строки. В частности, он выполняет следующие замены:

  • < преобразуется в &lt;
  • > преобразуется в &gt;
  • ' (одинарная кавычка) конвертируется в &#x27;
  • " (двойная кавычка) преобразуется в &quot;
  • & преобразуется в &amp;

Применение escape к переменной, к которой обычно применяется автоэскейпинг, приведет к тому, что результат будет экранирован только один раз. Поэтому эту функцию безопасно использовать даже в средах с автоэскейпингом. Если вы хотите, чтобы было применено несколько проходов экранирования, используйте фильтр force_escape.

Например, вы можете применить escape к полям, когда autoescape выключено:

{% autoescape off %}
    {{ title|escape }}
{% endautoescape %}

escapejs

Экранирует символы для использования в строках JavaScript. Это не делает строку безопасной для использования в HTML или литералах шаблонов JavaScript, но защищает вас от синтаксических ошибок при использовании шаблонов для генерации JavaScript/JSON.

Например:

{{ value|escapejs }}

Если value равно "testing\r\njavascript 'string\" <b>escaping</b>", то на выходе будет "testing\\u000D\\u000Ajavascript \\u0027string\\u0022 \\u003Cb\\u003Eescaping\\u003C/b\\u003E".

filesizeformat

Форматирует значение как «человекочитаемый» размер файла (т.е. '13 KB', '4.1 MB', '102 bytes' и т.д.).

Например:

{{ value|filesizeformat }}

Если value равно 123456789, то на выходе будет 117.7 MB.

Размеры файлов и единицы СИ

Строго говоря, filesizeformat не соответствует Международной системе единиц, которая рекомендует использовать KiB, MiB, GiB и т.д., когда размер байта вычисляется в 1024 разрядах (как в данном случае). Вместо этого Django использует традиционные названия единиц (KB, MB, GB и т.д.), соответствующие названиям, которые чаще всего используются.

first

Возвращает первый элемент в списке.

Например:

{{ value|first }}

Если value является списком ['a', 'b', 'c'], то на выходе будет 'a'.

floatformat

При использовании без аргумента округляет число с плавающей точкой до одного десятичного знака - но только если есть десятичная часть, которую нужно отобразить. Например:

value Шаблон Выход
34.23234 {{ value|floatformat }} 34.2
34.00000 {{ value|floatformat }} 34
34.26000 {{ value|floatformat }} 34.3

Если используется с целочисленным аргументом, floatformat округляет число до такого количества знаков после запятой. Например:

value Шаблон Выход
34.23234 {{ value|floatformat:3 }} 34.232
34.00000 {{ value|floatformat:3 }} 34.000
34.26000 {{ value|floatformat:3 }} 34.260

Особенно полезно передавать 0 (ноль) в качестве аргумента, что приведет к округлению плавающей величины до ближайшего целого числа.

value Шаблон Выход
34.23234 {{ value|floatformat:"0" }} 34
34.00000 {{ value|floatformat:"0" }} 34
39.56000 {{ value|floatformat:"0" }} 40

Если аргумент, переданный в floatformat, отрицательный, он округлит число до такого количества знаков после запятой - но только если есть десятичная часть, которую нужно отобразить. Например:

value Шаблон Выход
34.23234 {{ value|floatformat:"-3" }} 34.232
34.00000 {{ value|floatformat:"-3" }} 34
34.26000 {{ value|floatformat:"-3" }} 34.260

Если аргумент, переданный в floatformat, имеет суффикс g, это заставит группировку по THOUSAND_SEPARATOR для активной локали. Например, если активной локалью является en (английский):

value Шаблон Выход
34232.34 {{ value|floatformat:"2g" }} 34,232.34
34232.06 {{ value|floatformat:"g" }} 34,232.1
34232.00 {{ value|floatformat:"-3g" }} 34,232

Использование floatformat без аргумента эквивалентно использованию floatformat с аргументом -1.

Changed in Django 3.1:

В старых версиях для отрицательных чисел, которые округляются до нуля, возвращался отрицательный ноль -0.

Changed in Django Development version:

Добавлен суффикс g для принудительной группировки по разделителям тысяч.

force_escape

Применяет экранирование HTML к строке (подробнее см. фильтр escape). Этот фильтр применяется немедленно и возвращает новую строку с экранированием. Это полезно в редких случаях, когда требуется многократное экранирование или вы хотите применить другие фильтры к результатам экранирования. Обычно вы хотите использовать фильтр escape.

Например, если вы хотите перехватить элементы HTML <p>, созданные фильтром linebreaks:

{% autoescape off %}
    {{ body|linebreaks|force_escape }}
{% endautoescape %}

get_digit

При задании целого числа возвращает запрашиваемую цифру, где 1 - крайняя правая цифра, 2 - вторая крайняя правая цифра и т.д. Возвращает исходное значение при некорректном вводе (если ввод или аргумент не является целым числом, или если аргумент меньше 1). В противном случае на выходе всегда целое число.

Например:

{{ value|get_digit:"2" }}

Если value равно 123456789, то на выходе будет 8.

iriencode

Преобразует IRI (интернационализированный идентификатор ресурса) в строку, пригодную для включения в URL. Это необходимо, если вы пытаетесь использовать в URL строки, содержащие символы, отличные от ASCII.

Безопасно использовать этот фильтр на строке, которая уже прошла через фильтр urlencode.

Например:

{{ value|iriencode }}

Если value равно "?test=1&me=2", то на выходе будет "?test=1&amp;me=2".

join

Объединяет список со строкой, как в Python str.join(list)

Например:

{{ value|join:" // " }}

Если value является списком ['a', 'b', 'c'], то выходом будет строка "a // b // c".

json_script

Безопасный вывод объекта Python в формате JSON, обернутый в тег <script>, готовый для использования в JavaScript.

Аргумент: HTML «id» тега <script>.

Например:

{{ value|json_script:"hello-data" }}

Если value является словарем {'hello': 'world'}, вывод будет следующим:

<script id="hello-data" type="application/json">{"hello": "world"}</script>

К полученным данным можно получить доступ в JavaScript следующим образом:

const value = JSON.parse(document.getElementById('hello-data').textContent);

XSS-атаки смягчаются путем экранирования символов «<», «>» и «&». Например, если value является {'hello': 'world</script>&amp;'}, то вывод будет следующим:

<script id="hello-data" type="application/json">{"hello": "world\\u003C/script\\u003E\\u0026amp;"}</script>

Это совместимо со строгой политикой безопасности контента, которая запрещает выполнение сценариев на странице. Также поддерживается чистое разделение между пассивными данными и исполняемым кодом.

last

Возвращает последний элемент в списке.

Например:

{{ value|last }}

Если value является списком ['a', 'b', 'c', 'd'], то выходом будет строка "d".

length

Возвращает длину значения. Это работает как для строк, так и для списков.

Например:

{{ value|length }}

Если value равно ['a', 'b', 'c', 'd'] или "abcd", то на выходе будет 4.

Фильтр возвращает 0 для неопределенной переменной.

length_is

Возвращает True, если длина значения равна аргументу, или False в противном случае.

Например:

{{ value|length_is:"4" }}

Если value равно ['a', 'b', 'c', 'd'] или "abcd", то на выходе будет True.

linebreaks

Заменяет переносы строк в обычном тексте на соответствующие HTML; одиночная новая строка становится переносом строки HTML (<br>), а новая строка, за которой следует пустая строка, становится переносом абзаца (</p>).

Например:

{{ value|linebreaks }}

Если value равно Joel\nis a slug, то на выходе будет <p>Joel<br>is a slug</p>.

linebreaksbr

Преобразует все новые строки в фрагменте обычного текста в разрывы строк HTML (<br>).

Например:

{{ value|linebreaksbr }}

Если value равно Joel\nis a slug, то на выходе будет Joel<br>is a slug.

linenumbers

Отображает текст с номерами строк.

Например:

{{ value|linenumbers }}

Если value есть:

one
two
three

на выходе будет:

1. one
2. two
3. three

ljust

Выравнивает влево значение в поле заданной ширины.

Аргумент: размер поля

Например:

"{{ value|ljust:"10" }}"

Если value равно Django, то на выходе будет "Django    ".

lower

Преобразует строку в строчные буквы.

Например:

{{ value|lower }}

Если value равно Totally LOVING this Album!, то на выходе будет totally loving this album!.

make_list

Возвращает значение, преобразованное в список. Для строки это список символов. Для целого числа аргумент приводится к строке перед созданием списка.

Например:

{{ value|make_list }}

Если value является строкой "Joel", то выходом будет список ['J', 'o', 'e', 'l']. Если value является строкой 123, то выходом будет список ['1', '2', '3'].

phone2numeric

Преобразует номер телефона (возможно, содержащий буквы) в его числовой эквивалент.

Вводимые данные не обязательно должны быть действительным номером телефона. Он легко преобразует любую строку.

Например:

{{ value|phone2numeric }}

Если value равно 800-COLLECT, то на выходе будет 800-2655328.

pluralize

Возвращает суффикс множественного числа, если значение не является 1, '1' или объектом длины 1. По умолчанию этот суффикс равен 's'.

Пример:

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

Если num_messages равно 1, то на выходе будет You have 1 message. Если num_messages равно 2, то на выходе будет You have 2 messages.

Для слов, для которых требуется суффикс, отличный от 's', можно указать альтернативный суффикс в качестве параметра фильтра.

Пример:

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

Для слов, которые не образуют множественное число с помощью простого суффикса, вы можете указать суффикс единственного и множественного числа, разделив их запятой.

Пример:

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

Примечание

Используйте blocktranslate для перевода строк во множественном числе.

pprint

Обертка вокруг pprint.pprint() - для отладки, на самом деле.

random

Возвращает случайный элемент из заданного списка.

Например:

{{ value|random }}

Если value является списком ['a', 'b', 'c', 'd'], то выходом может быть "b".

rjust

Выравнивает вправо значение в поле заданной ширины.

Аргумент: размер поля

Например:

"{{ value|rjust:"10" }}"

Если value равно Django, то на выходе будет "    Django".

safe

Помечает строку как не требующую дальнейшего экранирования HTML перед выводом. Когда автоэскейпинг выключен, этот фильтр не действует.

Примечание

Если вы используете цепочку фильтров, то фильтр, примененный после safe, может снова сделать содержимое небезопасным. Например, следующий код печатает переменную как есть, без расшифровки:

{{ var|safe|escape }}

safeseq

Применяет фильтр safe к каждому элементу последовательности. Используется в сочетании с другими фильтрами, работающими с последовательностями, например join. Например:

{{ some_list|safeseq|join:", " }}

В этом случае нельзя напрямую использовать фильтр safe, так как он сначала преобразует переменную в строку, а не работает с отдельными элементами последовательности.

slice

Возвращает фрагмент списка.

Uses the same syntax as Python’s list slicing. See https://diveinto.org/python3/native-datatypes.html#slicinglists for an introduction.

Пример:

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

Если some_list равно ['a', 'b', 'c'], то на выходе будет ['a', 'b'].

slugify

Преобразует в ASCII. Преобразует пробелы в дефисы. Удаляет символы, не являющиеся алфавитно-цифровыми, подчеркиванием или дефисом. Преобразует в нижний регистр. Также удаляет ведущие и последующие пробельные символы.

Например:

{{ value|slugify }}

Если value равно "Joel is a slug", то на выходе будет "joel-is-a-slug".

stringformat

Форматирует переменную в соответствии с аргументом - спецификатором форматирования строки. Этот спецификатор использует синтаксис printf-style String Formatting, за исключением того, что ведущий «%» опускается.

Например:

{{ value|stringformat:"E" }}

Если value равно 10, то на выходе будет 1.000000E+01.

striptags

Прилагает все возможные усилия для удаления всех тегов [X]HTML.

Например:

{{ value|striptags }}

Если value равно "<b>Joel</b> <button>is</button> a <span>slug</span>", то на выходе будет "Joel is a slug".

Отсутствие гарантии безопасности

Обратите внимание, что striptags не дает никаких гарантий того, что его вывод будет безопасным для HTML, особенно при не валидном вводе HTML. Поэтому НИКОГДА не применяйте фильтр safe к выводу striptags. Если вы ищете что-то более надежное, вы можете использовать библиотеку bleach Python, в частности, ее метод clean.

time

Форматирует время в соответствии с заданным форматом.

Заданный формат может быть предопределенным форматом TIME_FORMAT, или пользовательским форматом, таким же, как фильтр date. Обратите внимание, что предопределенный формат зависит от локали.

Например:

{{ value|time:"H:i" }}

Если value эквивалентно datetime.datetime.now(), то на выходе будет строка "01:23".

Обратите внимание, что вы можете отменить обратную косую черту в строке формата, если хотите использовать «сырое» значение. В этом примере «h» и «m» выделены обратным слешем, поскольку в противном случае каждая из них является форматной строкой, отображающей час и месяц соответственно:

{% value|time:"H\h i\m" %}

Это отобразится как «01h 23m».

Другой пример:

Если предположить, что USE_L10N есть True, а LANGUAGE_CODE есть, например, "de", то для:

{{ value|time:"TIME_FORMAT" }}

на выходе будет строка "01:23" (Спецификатор формата "TIME_FORMAT" для локали de, поставляемой с Django, равен "H:i").

Фильтр time будет принимать в строке форматирования только те параметры, которые относятся ко времени суток, а не к дате. Если вам нужно отформатировать значение date, используйте вместо него фильтр date (или вместе с time, если вам нужно вывести полное значение datetime).

Существует одно исключение из вышеуказанного правила: При передаче значения datetime с присоединенной информацией о временной зоне (экземпляр time-zone-aware datetime) фильтр time будет принимать связанные с временной зоной значения format specifiers 'e', 'O' , 'T' и 'Z'.

При использовании без строки формата используется спецификатор формата TIME_FORMAT:

{{ value|time }}

это то же самое, что:

{{ value|time:"TIME_FORMAT" }}

timesince

Форматирует дату как время, прошедшее с этой даты (например, «4 дня, 6 часов»).

Принимает необязательный аргумент, который является переменной, содержащей дату, используемую в качестве точки сравнения (без аргумента точкой сравнения является теперь). Например, если blog_date является экземпляром даты, представляющим полночь 1 июня 2006 года, а comment_date является экземпляром даты для 08:00 1 июня 2006 года, то следующее действие вернет «8 часов»:

{{ blog_date|timesince:comment_date }}

При сравнении датировок, не учитывающих смещение, и датировок, учитывающих смещение, будет возвращена пустая строка.

Минуты являются наименьшей используемой единицей, и «0 минут» будет возвращено для любой даты, которая находится в будущем относительно точки сравнения.

timeuntil

Аналогичен timesince, за исключением того, что измеряет время от настоящего момента до заданной даты или времени. Например, если сегодня 1 июня 2006 года, а conference_date - экземпляр даты, содержащий 29 июня 2006 года, то {{ conference_date|timeuntil }} вернет «4 недели».

Принимает необязательный аргумент, который является переменной, содержащей дату, используемую в качестве точки сравнения (вместо сейчас). Если from_date содержит 22 июня 2006 года, то следующие действия вернут «1 неделю»:

{{ conference_date|timeuntil:from_date }}

При сравнении датировок, не учитывающих смещение, и датировок, учитывающих смещение, будет возвращена пустая строка.

Минуты являются наименьшей используемой единицей, и «0 минут» будет возвращено для любой даты, которая находится в прошлом относительно точки сравнения.

title

Преобразует строку в заглавный регистр, заставляя слова начинаться с прописного символа, а остальные символы - со строчного. Этот тег не прилагает никаких усилий, чтобы сохранить «тривиальные слова» в нижнем регистре.

Например:

{{ value|title }}

Если value равно "my FIRST post", то на выходе будет "My First Post".

truncatechars

Усекает строку, если ее длина превышает указанное количество символов. Усеченные строки будут заканчиваться переводимым символом многоточия (»…»).

Аргумент: Количество символов для усечения до

Например:

{{ value|truncatechars:7 }}

Если value равно "Joel is a slug", то на выходе будет "Joel i…".

truncatechars_html

Аналогичен truncatechars, за исключением того, что он знает о тегах HTML. Любые теги, открытые в строке и не закрытые до точки усечения, закрываются сразу после усечения.

Например:

{{ value|truncatechars_html:7 }}

Если value равно "<p>Joel is a slug</p>", то на выходе будет "<p>Joel i…</p>".

Новые строки в содержимом HTML будут сохранены.

truncatewords

Усекает строку после определенного количества слов.

Аргумент: Количество слов, после которых следует усекать.

Например:

{{ value|truncatewords:2 }}

Если value равно "Joel is a slug", то на выходе будет "Joel is …".

Новые строки в строке будут удалены.

truncatewords_html

Аналогичен truncatewords, за исключением того, что он знает о тегах HTML. Любые теги, открытые в строке и не закрытые до точки усечения, закрываются сразу после усечения.

Это менее эффективно, чем truncatewords, поэтому его следует использовать только при передаче HTML-текста.

Например:

{{ value|truncatewords_html:2 }}

Если value равно "<p>Joel is a slug</p>", то на выходе будет "<p>Joel is …</p>".

Новые строки в содержимом HTML будут сохранены.

unordered_list

Рекурсивно принимает самовложенный список и возвращает неупорядоченный список HTML – БЕЗ открывающих и закрывающих тегов <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

Преобразует строку во все заглавные буквы.

Например:

{{ value|upper }}

Если value равно "Joel is a slug", то на выходе будет "JOEL IS A SLUG".

urlencode

Экранирует значение для использования в URL.

Например:

{{ value|urlencode }}

Если value равно "https://www.example.org/foo?a=b&c=d", то на выходе будет "https%3A//www.example.org/foo%3Fa%3Db%26c%3Dd".

Можно указать дополнительный аргумент, содержащий символы, которые не должны экранироваться.

Если символ „/“ не указан, он считается безопасным. Пустая строка может быть указана, если необходимо экранировать все символы. Например:

{{ value|urlencode:"" }}

Если value равно "https://www.example.org/", то на выходе будет "https%3A%2F%2Fwww.example.org%2F".

urlize

Преобразует URL-адреса и адреса электронной почты в тексте в кликабельные ссылки.

Этот тег шаблона работает для ссылок с префиксом http://, https:// или www.. Например, https://goo.gl/aia1t будет преобразована, а goo.gl/aia1t - нет.

Он также поддерживает ссылки, заканчивающиеся на один из оригинальных доменов верхнего уровня (.com, .edu, .gov, .int, .mil, .net и .org). Например, djangoproject.com преобразуется.

Ссылки могут иметь концевую пунктуацию (точки, запятые, закрывающие знаки) и ведущую пунктуацию (открывающие знаки), и urlize все равно сделает все правильно.

Ссылки, созданные с помощью urlize, имеют добавленный к ним атрибут rel="nofollow".

Например:

{{ value|urlize }}

Если value равно "Check out www.djangoproject.com", то на выходе будет "Check out <a href="http://www.djangoproject.com" rel="nofollow">www.djangoproject.com</a>".

Помимо веб-ссылок, urlize также преобразует адреса электронной почты в ссылки mailto:. Если value является "Send questions to foo@example.com", то на выходе будет "Send questions to <a href="mailto:foo@example.com">foo@example.com</a>".

Фильтр urlize также принимает необязательный параметр autoescape. Если autoescape имеет значение True, то текст ссылки и URL будут экранированы с помощью встроенного в Django фильтра escape. Значение по умолчанию для autoescape равно True.

Примечание

Если urlize применяется к тексту, который уже содержит HTML-разметку, или к адресам электронной почты, содержащим одинарные кавычки ('), все будет работать не так, как ожидалось. Применяйте этот фильтр только к обычному тексту.

urlizetrunc

Преобразует URL и адреса электронной почты в кликабельные ссылки, как и urlize, но усекает URL, длина которых превышает заданный лимит символов.

Аргумент: Количество символов, до которого должен быть усечен текст ссылки, включая многоточие, которое добавляется, если усечение необходимо.

Например:

{{ value|urlizetrunc:15 }}

Если value будет "Check out www.djangoproject.com", то выходом будет 'Check out <a href="http://www.djangoproject.com" rel="nofollow">www.djangoproj…</a>'.

Как и в случае с urlize, этот фильтр следует применять только к обычному тексту.

wordcount

Возвращает количество слов.

Например:

{{ value|wordcount }}

Если value равно "Joel is a slug", то на выходе будет 4.

wordwrap

Обертывает слова на заданную длину строки.

Аргумент: количество символов, на которое нужно обернуть текст

Например:

{{ value|wordwrap:5 }}

Если value будет Joel is a slug, то на выходе будет:

Joel
is a
slug

yesno

Сопоставляет значения для True, False и (опционально) None со строками «yes», «no», «maybe» или пользовательским отображением, переданным в виде списка, разделенного запятыми, и возвращает одну из этих строк в соответствии со значением:

Например:

{{ value|yesno:"yeah,no,maybe" }}
Значение Аргумент Выходы
True   yes
True "yeah,no,maybe" yeah
False "yeah,no,maybe" no
None "yeah,no,maybe" maybe
None "yeah,no" no (преобразует None в False, если не указано отображение для None)

Теги и фильтры интернационализации

Django предоставляет теги шаблонов и фильтры для управления каждым аспектом internationalization в шаблонах. Они позволяют детально контролировать переводы, форматирование и преобразование часовых поясов.

i18n

Эта библиотека позволяет указывать переводимый текст в шаблонах. Чтобы включить ее, установите USE_I18N в True, затем загрузите ее с помощью {% load i18n %}.

См. Интернационализация: в коде шаблона.

l10n

Эта библиотека обеспечивает контроль над локализацией значений в шаблонах. Вам нужно загрузить библиотеку только с помощью {% load l10n %}, но вы часто будете устанавливать USE_L10N на True, чтобы локализация была активна по умолчанию.

См. Управление локализацией в шаблонах.

tz

Эта библиотека обеспечивает контроль над преобразованием часовых поясов в шаблонах. Как и l10n, вам нужно загрузить библиотеку только с помощью {% load tz %}, но обычно вы также устанавливаете USE_TZ в True, чтобы преобразование в местное время происходило по умолчанию.

См. Вывод в шаблонах с учетом часового пояса.

Другие библиотеки тегов и фильтров

Django поставляется с парой других библиотек шаблонов-тегов, которые вы должны включить явно в настройках INSTALLED_APPS и включить в шаблоне с помощью тега {% load %}.

django.contrib.humanize

Набор шаблонных фильтров Django, полезных для добавления «человеческого прикосновения» к данным. См. django.contrib.humanize.

static

static

Для ссылки на статические файлы, которые сохраняются в STATIC_ROOT Django поставляется с тегом шаблона static. Если установлено приложение django.contrib.staticfiles, тег будет обслуживать файлы, используя url() метод хранения, указанный STATICFILES_STORAGE. Например:

{% load static %}
<img src="{% static 'images/hi.jpg' %}" alt="Hi!">

Он также может использовать стандартные контекстные переменные, например, предполагая, что переменная user_stylesheet передается в шаблон:

{% load static %}
<link rel="stylesheet" href="{% static user_stylesheet %}" type="text/css" media="screen">

Если вы хотите получить статический URL без его отображения, вы можете использовать немного другой вызов:

{% load static %}
{% static "images/hi.jpg" as myphoto %}
<img src="{{ myphoto }}">

Использование шаблонов Jinja2?

Информацию об использовании тега Jinja2 в Jinja2 смотрите в static.

get_static_prefix

Вы должны предпочесть тег шаблона static, но если вам нужно больше контроля над тем, где и как именно STATIC_URL вводится в шаблон, вы можете использовать тег шаблона get_static_prefix:

{% load static %}
<img src="{% get_static_prefix %}images/hi.jpg" alt="Hi!">

Существует также вторая форма, которую можно использовать, чтобы избежать дополнительной обработки, если вам нужно значение несколько раз:

{% load static %}
{% get_static_prefix as STATIC_PREFIX %}

<img src="{{ STATIC_PREFIX }}images/hi.jpg" alt="Hi!">
<img src="{{ STATIC_PREFIX }}images/hi2.jpg" alt="Hello!">

get_media_prefix

Аналогично get_static_prefix, get_media_prefix заполняет переменную шаблона префиксом медиа MEDIA_URL, например:

{% load static %}
<body data-media-url="{% get_media_prefix %}">

Сохраняя значение в атрибуте данных, мы обеспечиваем его соответствующую экранировку, если хотим использовать его в контексте JavaScript.

Вернуться на верх