API рендеринга форм

Виджеты форм Django отображаются с помощью системы шаблонизаторов Django.

Процесс рендеринга форм можно настраивать на нескольких уровнях:

Для виджетов можно указать пользовательские имена шаблонов.
Для форм и виджетов можно указать пользовательские классы рендереров.
Шаблон виджета можно переопределить в проекте. (Повторно используемым приложениям обычно не следует переопределять встроенные шаблоны, поскольку они могут конфликтовать с пользовательскими шаблонами проекта.)

Рендеринг шаблонов форм контролируется настраиваемым классом рендерера. Пользовательский рендерер можно указать, обновив настройку FORM_RENDERER. По умолчанию используется 'django.forms.renderers.DjangoTemplates'.

Указав пользовательский рендерер форм и переопределив form_template_name, вы можете изменить стандартную разметку форм во всём проекте в одном месте.

Вы также можете указать пользовательский рендерер для каждой формы или каждого виджета, задав атрибут Form.default_renderer или используя аргумент renderer метода Form.render() либо Widget.render().

Аналогичные возможности доступны для рендеринга наборов форм. Подробнее см. в разделе Использование набора форм в представлениях и шаблонах.

Используйте один из встроенных рендереров шаблонов форм или реализуйте собственный. Пользовательские рендереры должны реализовать метод render(template_name, context, request=None). Он должен возвращать отрендеренный шаблон (в виде строки) или вызывать исключение TemplateDoesNotExist.

class BaseRenderer [исходный код]

Базовый класс встроенных рендереров форм.

form_template_name

Имя шаблона, используемого по умолчанию для рендеринга формы.

По умолчанию используется шаблон "django/forms/div.html".

formset_template_name

Имя шаблона, используемого по умолчанию для рендеринга набора форм.

По умолчанию используется шаблон "django/forms/formsets/div.html".

field_template_name

Имя шаблона, используемого по умолчанию для рендеринга BoundField.

По умолчанию используется "django/forms/field.html"

bound_field_class

Добавлено в Django 5.2.

Класс, используемый по умолчанию для представления полей форм во всём проекте.

По умолчанию используется класс BoundField.

Его можно дополнительно настроить с помощью Form.bound_field_class для переопределения в отдельной форме или с помощью Field.bound_field_class для переопределения в отдельном поле.

get_template(template_name) [исходный код]: Подклассы должны реализовать этот метод с подходящей логикой поиска шаблонов.

render(template_name, context, request=None) [исходный код]: Рендерит указанный шаблон или вызывает исключение TemplateDoesNotExist.

Встроенные рендереры шаблонов форм

`DjangoTemplates`

class DjangoTemplates [исходный код]

Этот рендерер использует автономный движок DjangoTemplates (не связанный с тем, который вы могли настроить в параметре TEMPLATES). Сначала он загружает шаблоны из каталога встроенных шаблонов форм django/forms/templates, а затем из каталогов шаблонов установленных приложений с помощью загрузчика app_directories.

Чтобы рендерить шаблоны с настройками из параметра TEMPLATES, например с процессорами контекста, используйте рендерер TemplatesSetting.

`Jinja2`

class Jinja2 [исходный код]

Этот рендерер аналогичен рендереру DjangoTemplates, но использует бэкенд Jinja2. Шаблоны встроенных виджетов находятся в django/forms/jinja2, а установленные приложения могут предоставлять шаблоны в каталоге jinja2.

Чтобы использовать этот бэкенд, все формы и виджеты в вашем проекте и сторонних приложениях должны иметь шаблоны Jinja2. Если вы не предоставите собственные шаблоны Jinja2 для виджетов, у которых их нет, использовать этот рендерер нельзя. Например, django.contrib.admin не содержит шаблонов Jinja2 для своих виджетов из-за использования тегов шаблонов Django.

`TemplatesSetting`

class TemplatesSetting [исходный код]

Этот рендерер предоставляет полный контроль над источниками шаблонов форм и виджетов. Он использует get_template() для поиска шаблонов с учётом конфигурации параметра TEMPLATES.

Для использования этого рендерера со встроенными шаблонами требуется одно из следующего:

'django.forms' в INSTALLED_APPS и как минимум один движок с параметром APP_DIRS=True.
Добавить каталог встроенных шаблонов в параметр DIRS одного из движков шаблонов. Чтобы получить этот путь:
```
import django

django.__path__[0] + "/forms/templates"  # or '/forms/jinja2'
```

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

Контекст, доступный в шаблонах наборов форм

Шаблоны наборов форм получают контекст от BaseFormSet.get_context(). По умолчанию наборы форм получают словарь со следующими значениями:

formset: экземпляр набора форм.

Контекст, доступный в шаблонах форм

Шаблоны форм получают контекст от Form.get_context(). По умолчанию формы получают словарь со следующими значениями:

form: связанная форма.
fields: все связанные поля, кроме скрытых.
hidden_fields: все связанные скрытые поля.
errors: все ошибки формы, не относящиеся к полям или относящиеся к скрытым полям.

Контекст, доступный в шаблонах полей

Шаблоны полей получают контекст от BoundField.get_context(). По умолчанию поля получают словарь со следующим значением:

field: объект BoundField.

Шаблоны виджетов получают контекст от Widget.get_context(). По умолчанию виджеты получают одно значение в контексте — widget. Это словарь, содержащий такие значения, как:

name
value
attrs
is_hidden
template_name

Некоторые виджеты добавляют в контекст дополнительные данные. Например, все виджеты, являющиеся подклассами Input, определяют widget['type'], а MultiWidget определяет widget['subwidgets'] для перебора элементов.

Переопределение встроенных шаблонов наборов форм

BaseFormSet.template_name

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

Переопределение встроенных шаблонов форм

Form.template_name

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

Переопределение встроенных шаблонов полей

Field.template_name

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

Переопределение встроенных шаблонов виджетов

У каждого виджета есть атрибут template_name со значением, например input.html. Встроенные шаблоны виджетов хранятся по пути django/forms/widgets. Вы можете предоставить пользовательский шаблон для input.html, например, определив django/forms/widgets/input.html. Названия шаблонов каждого виджета см. в разделе Встроенные виджеты.

Чтобы переопределить шаблоны виджетов, необходимо использовать рендерер TemplatesSetting. После этого шаблоны виджетов переопределяются так же, как и любые другие шаблоны в вашем проекте.

© Django Software Foundation and individual contributors
Licensed under the BSD License.
https://docs.djangoproject.com/en/6.0/ref/forms/renderers/