表单渲染 API

Django 的表单部件使用 Django 的模板引擎系统进行渲染。

表单渲染过程可以在多个级别进行自定义

  • 部件可以指定自定义模板名称。

  • 表单和部件可以指定自定义渲染器类。

  • 项目可以覆盖部件的模板。(可重用应用程序通常不应该覆盖内置模板，因为它们可能会与项目的自定义模板冲突。)

低级渲染 API

表单模板的渲染由可自定义的渲染器类控制。可以通过更新FORM_RENDERER设置来指定自定义渲染器。它默认为'django.forms.renderers.DjangoTemplates'。

通过指定自定义表单渲染器并覆盖form_template_name，您可以从一个地方调整整个项目的默认表单标记。

您还可以通过设置Form.default_renderer属性或使用Form.render()或Widget.render()的renderer参数，为每个表单或每个部件提供自定义渲染器。

匹配点适用于表单集渲染。有关讨论，请参见在视图和模板中使用表单集。

使用内置模板表单渲染器之一或实现您自己的渲染器。自定义渲染器必须实现一个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
Django 5.0 新特性。

用于渲染BoundField的模板的默认名称。

默认为"django/forms/field.html"

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 模板的小部件提供自己的 Jinja2 模板，否则您无法使用此渲染器。例如，django.contrib.admin不包含其部件的 Jinja2 模板，因为它们使用了 Django 模板标签。

class Jinja2DivFormRenderer[source]

自 5.0 版本起已弃用。

Jinja2的别名。

TemplatesSetting

class TemplatesSetting[source]

此渲染器使您可以完全控制表单和部件模板的来源。它使用get_template()根据TEMPLATES设置中配置的内容查找模板。

将此渲染器与内置模板一起使用需要：

  • INSTALLED_APPS中包含'django.forms'，并且至少有一个引擎具有APP_DIRS=True。

  • 在您其中一个模板引擎的DIRS中添加内置模板目录。要生成该路径

    import django

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

使用此渲染器需要确保项目所需的表单模板可以找到。

Formset 模板中可用的上下文

Formset 模板从 BaseFormSet.get_context() 接收上下文。默认情况下，formset 会收到包含以下值的字典

  • formset: Formset 实例。

Form 模板中可用的上下文

Form 模板从 Form.get_context() 接收上下文。默认情况下，form 会收到包含以下值的字典

  • form: 已绑定的表单。

  • fields: 所有已绑定的字段，隐藏字段除外。

  • hidden_fields: 所有已绑定的隐藏字段。

  • errors: 所有与字段无关或与隐藏字段无关的表单错误。

字段模板中可用的上下文

Django 5.0 新特性。

字段模板从 BoundField.get_context() 接收上下文。默认情况下，字段会收到包含以下值的字典

Widget 模板中可用的上下文

Widget 模板从 Widget.get_context() 接收上下文。默认情况下，widget 在上下文中只接收一个值，widget。这是一个包含以下值的字典：

  • name

  • value

  • attrs

  • is_hidden

  • template_name

一些 widget 会向上下文添加更多信息。例如，所有继承自 Input 的 widget 都定义了 widget['type']，而 MultiWidget 为了循环目的定义了 widget['subwidgets']。

覆盖内置 Formset 模板

BaseFormSet.template_name

要覆盖 formset 模板，必须使用 TemplatesSetting 渲染器。然后覆盖 formset 模板的方法与覆盖项目中的任何其他模板相同。

覆盖内置 Form 模板

Form.template_name

要覆盖 form 模板，必须使用 TemplatesSetting 渲染器。然后覆盖 form 模板的方法与覆盖项目中的任何其他模板相同。

覆盖内置字段模板

Django 5.0 新特性。

Field.template_name

要覆盖字段模板，必须使用 TemplatesSetting 渲染器。然后覆盖字段模板的方法与覆盖项目中的任何其他模板相同。

覆盖内置 Widget 模板

每个 Widget 都有一个 template_name 属性，其值为例如 input.html。内置 Widget 模板存储在 django/forms/widgets 路径下。例如，可以通过定义 django/forms/widgets/input.html 来提供 input.html 的自定义模板。请参阅 内置 Widget 以了解每个 Widget 模板的名称。

要覆盖 widget 模板，必须使用 TemplatesSetting 渲染器。然后覆盖 widget 模板的方法与覆盖项目中的任何其他模板相同。

Formset 函数
Widgets
返回顶部