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

Виджеты форм Django отображаются с помощью template engines system.

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

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

Низкоуровневый API рендеринга

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

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

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

Точки совпадения применяются к рендерингу набора форм. См. раздел Использование набора форм в представлениях и шаблонах для обсуждения.

Используйте один из built-in template form renderers или реализуйте свой собственный. Пользовательские рендереры должны реализовать метод render(template_name, context, request=None). Он должен возвращать отрендеренные шаблоны (в виде строки) или поднимать вопрос TemplateDoesNotExist.

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

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

form_template_name
New in Django 4.1.

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

По умолчанию используется значение "django/forms/default.html", которое является прокси для "django/forms/table.html".

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

Шаблон "django/forms/default.html" устарел и будет удален в Django 5.0. В то время по умолчанию будет использоваться "django/forms/div.html".

formset_template_name
New in Django 4.1.

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

По умолчанию используется значение "django/forms/formsets/default.html", которое является прокси для "django/forms/formsets/table.html".

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

Шаблон "django/forms/formset/default.html" является устаревшим и будет удален в Django 5.0. По умолчанию будет использоваться шаблон "django/forms/formset/div.html".

get_template(template_name)[исходный код]

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

render(template_name, context, request=None)[исходный код]

Верстает заданный шаблон, или выдает TemplateDoesNotExist.

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

DjangoTemplates

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

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

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

class DjangoDivFormRenderer
New in Django 4.1.

Подкласс DjangoTemplates, определяющий form_template_name и formset_template_name как "django/forms/div.html" и "django/forms/formset/div.html" соответственно.

Это переходный рендерер для перехода на новые шаблоны на основе <div>, которые используются по умолчанию в Django 5.0.

Примените это через настройку FORM_RENDERER:

FORM_RENDERER = "django.forms.renderers.DjangoDivFormRenderer"

Когда шаблоны <div> станут шаблонами по умолчанию, этот переходный рендерер будет устаревшим и будет удален в Django 6.0. Объявление FORM_RENDERER может быть удалено в это время.

Jinja2

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

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

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

class Jinja2DivFormRenderer
New in Django 4.1.

Переходный рендерер, как DjangoDivFormRenderer выше, но подкласс Jinja2 для использования с бэкендом Jinja2.

Примените это через настройку FORM_RENDERER:

FORM_RENDERER = "django.forms.renderers.Jinja2DivFormRenderer"

TemplatesSetting

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

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

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

  • 'django.forms' в INSTALLED_APPS и по крайней мере один двигатель с APP_DIRS=True.

  • Добавление каталога встроенных шаблонов в DIRS одного из ваших шаблонизаторов. Чтобы сгенерировать этот путь:

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

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

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

New in Django 4.0.

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

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

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

New in Django 4.0.

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

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

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

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

  • name
  • value
  • attrs
  • is_hidden
  • template_name

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

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

New in Django 4.0.

BaseFormSet.template_name

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

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

New in Django 4.0.

Form.template_name

Чтобы переопределить шаблоны форм, вы должны использовать рендерер TemplatesSetting. Тогда переопределение шаблонов виджетов работает the same as как переопределение любого другого шаблона в вашем проекте.

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

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

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

Функции набора форм
Виджеты
Вернуться на верх