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

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

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

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

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

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

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

You can also provide a custom renderer per-form or per-widget by setting the Form.default_renderer attribute or by using the renderer argument of Form.render(), or Widget.render().

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

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

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

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

form_template_name
New in Django Development version.

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

По умолчанию используется значение "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 Development version.

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

По умолчанию используется значение "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[исходный код]

This renderer uses a standalone DjangoTemplates engine (unconnected to what you might have configured in the TEMPLATES setting). It loads templates first from the built-in form templates directory in django/forms/templates and then from the installed apps“ templates directories using the app_directories loader.

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

class DjangoDivFormRenderer
New in Django Development version.

Подкласс 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[исходный код]

This renderer is the same as the DjangoTemplates renderer except that it uses a Jinja2 backend. Templates for the built-in widgets are located in django/forms/jinja2 and installed apps can provide templates in a jinja2 directory.

To use this backend, all the forms and widgets in your project and its third-party apps must have Jinja2 templates. Unless you provide your own Jinja2 templates for widgets that don’t have any, you can’t use this renderer. For example, django.contrib.admin doesn’t include Jinja2 templates for its widgets due to their usage of Django template tags.

class Jinja2DivFormRenderer
New in Django Development version.

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

Примените это с помощью настройки FORM_RENDERER:

FORM_RENDERER = "django.forms.renderers.Jinja2DivFormRenderer"

TemplatesSetting

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

This renderer gives you complete control of how form and widget templates are sourced. It uses get_template() to find templates based on what’s configured in the TEMPLATES setting.

Using this renderer along with the built-in templates requires either:

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

  • Adding the built-in templates directory in DIRS of one of your template engines. To generate that path:

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

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

Context available in formset templates

Formset templates receive a context from BaseFormSet.get_context(). By default, formsets receive a dictionary with the following values:

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

Context available in form templates

Form templates receive a context from Form.get_context(). By default, forms receive a dictionary with the following values:

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

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

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

  • name
  • value
  • attrs
  • is_hidden
  • template_name

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

Overriding built-in formset templates

BaseFormSet.template_name

To override formset templates, you must use the TemplatesSetting renderer. Then overriding widget templates works the same as overriding any other template in your project.

Overriding built-in form templates

Form.template_name

To override form templates, you must use the TemplatesSetting renderer. Then overriding widget templates works the same as overriding any other template in your project.

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

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

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

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