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 [source]

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

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) [source]: Подклассы должны реализовать этот метод с соответствующей логикой поиска шаблонов.

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

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

`DjangoTemplates`

class DjangoTemplates [source]

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

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

class DjangoDivFormRenderer [source]

Устаревшее с версии 5.0.

Псевдоним для DjangoTemplates.

`Jinja2`

class Jinja2 [source]

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

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

class Jinja2DivFormRenderer [source]

Устаревшее с версии 5.0.

Псевдоним для Jinja2.

`TemplatesSetting`

class TemplatesSetting [source]

Этот рендер предоставляет вам полный контроль над тем, как подгружаются шаблоны форм и виджетов. Он использует 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/5.2/ref/forms/renderers/