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

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

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

autoescape

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

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

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

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

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

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

{% autoescape off %}
    {{ my_list|join:", "|escape }}
{% endautoescape %}

Приведенный выше код выведет объединенные элементы my_list без эскейпа. Это связано с тем, что последовательность фильтров сначала выполняет фильтр join на my_list (без применения экранирования к каждому элементу, поскольку autoescape является off), помечая результат как безопасный. Впоследствии этот безопасный результат будет передан фильтру escape, который не применяет второй раунд экранирования.

Чтобы правильно экранировать каждый элемент последовательности, используйте фильтр escapeseq:

{% autoescape off %}
    {{ my_list|escapeseq|join:", " }}
{% 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 использование {% 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

Выводит целую кучу отладочной информации, включая текущий контекст и импортированные модули. {% debug %} ничего не выводит, если параметр DEBUG равен 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 %} оценивает переменную, и если эта переменная «истинна» (т.е. существует, не пуста и не является ложным булевым значением), то содержимое блока выводится:

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

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

Вы можете передать шаблону дополнительный контекст с помощью аргументов-ключей:

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

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

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

Примечание

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

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

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, включая методы, атрибуты, ключи словаря и элементы списка. Например, если поле «страна» является внешним ключом к классу с атрибутом «описание», то можно использовать:

{% 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>Gareth</h1>
<p class="odd">Harry</p>
<p class="even">John</p>
<p class="odd">Nick</p>

<h1>John</h1>
<p class="odd">Andrea</p>
<p class="even">Melissa</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 #}

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

The {% templatetag openblock %} characters open a block.

Смотрите также тег verbatim для другого способа включения этих символов.

url

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

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

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

Первым аргументом является URL pattern name. Это может быть литерал в кавычках или любая другая контекстная переменная. Дополнительные аргументы являются необязательными и должны представлять собой разделенные пробелами значения, которые будут использоваться в качестве аргументов в 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

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

Использует формат, аналогичный функции PHP date() с некоторыми отличиями.

Примечание

Эти символы формата не используются в 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 цифры с ведущими нулями. '0001', …, '1999', …, '9999'
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, или пользовательским форматом, использующим спецификаторы формата, приведенные в таблице выше. Обратите внимание, что предопределенные форматы могут отличаться в зависимости от текущей локали.

Если предположить, что 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 %}

Цепочка escape с другими фильтрами

Как уже упоминалось в разделе autoescape, когда фильтры, включающие escape, соединены в цепочку, это может привести к неожиданным результатам, если предыдущие фильтры пометят потенциально опасную строку как безопасную из-за отсутствия экранирования, вызванного тем, что autoescape стал off.

В таких случаях цепочка escape не вернет строки, которые уже были помечены как безопасные.

Это особенно важно при использовании фильтров, оперирующих последовательностями, например join. Если вам нужно экранировать каждый элемент в последовательности, используйте специальный фильтр escapeseq.

escapejs

Экранирует символы для использования в качестве целого литерала строки JavaScript, заключенного в одинарные или двойные кавычки, как показано ниже. Этот фильтр не делает строку безопасной для использования в «шаблонных литералах JavaScript « (синтаксис JavaScript backtick). Любые другие варианты использования, не перечисленные выше, не поддерживаются. Обычно рекомендуется передавать данные с помощью атрибутов HTML data- или фильтра json_script, а не во встроенном JavaScript.

Например:

<script>
let myValue = '{{ value|escapejs }}'

escapeseq

New in Django 5.0.

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

{% autoescape off %}
    {{ my_list|escapeseq|join:", " }}
{% endautoescape %}

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

Вывод всегда локализован (независимо от тега {% localize off %}), если только аргумент, переданный в floatformat, не имеет суффикс u, который принудительно отключает локализацию. Например, когда активной локалью является pl (польский язык):

value Шаблон Выход
34.23234 {{ value|floatformat:"3" }} 34,232
34.23234 {{ value|floatformat:"3u" }} 34.232

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

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

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

Возвращает 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

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

Использует тот же синтаксис, что и нарезка списка в Python. Введение см. на https://diveinto.org/python3/native-datatypes.html#slicinglists.

Пример:

{{ 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. Если вы ищете что-то более надежное, воспользуйтесь сторонним инструментом санации HTML.

time

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

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

Например:

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

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

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

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

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

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

Если предположить, что 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 недели».

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

Размер входной строки

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

Changed in Django 3.2.22:

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

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 будут сохранены.

Размер входной строки

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

Changed in Django 3.2.22:

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

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

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

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 в STORAGES. Например:

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

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

{% load static %}
<link rel="stylesheet" href="{% static user_stylesheet %}" 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.

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