• 3.1
  • 3.2
  • 5.0
  • Версия документации: 6.1

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

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

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

  • Виджеты могут указывать собственные имена шаблонов.

  • Формы и виджеты могут указывать собственные классы отрисовки.

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

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

Отрисовка шаблонов форм контролируется настраиваемым классом отрисовки. Пользовательский рендерер можно указать, обновив настройку 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
New in 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.

Джинджа2

class Jinja2

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

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

Настройка шаблонов

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: все скрытые связанные поля.

  • ошибки: все ошибки формы, не связанные с полями или скрытые поля.

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

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

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

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

  • name

  • value

  • атрисы

  • is_hidden

  • имя_шаблона

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

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

BaseFormSet.имя_шаблона

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

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

Form.имя_шаблона

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

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

Field.template_name

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

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

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

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

Back to Top