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

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
New in Django 5.0.

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

По умолчанию "django/forms/field.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

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

Псевдоним DjangoTemplates.

Джинджа2

class Jinja2

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

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

class Jinja2DivFormRenderer

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

Псевдоним Jinja2.

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

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

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

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

New in Django 5.0.

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

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

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

  • name

  • value

  • атрисы

  • is_hidden

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

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

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

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

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

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

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

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

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

New in Django 5.0.

Field.template_name

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

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

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

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

Back to Top