表单呈现 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

内置表单渲染器的基类。

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)

子类必须使用适当的模板查找逻辑实现此方法。

render(template_name, context, request=None)

渲染给定的模板，或引发 TemplateDoesNotExist。

内置模板表单渲染器

DjangoTemplates

class DjangoTemplates

此渲染器使用独立的 DjangoTemplates 引擎（与您可能在 TEMPLATES 设置中配置的内容无关）。它首先从 django/forms/templates 中的内置表单模板目录加载模板，然后使用 app_directories 加载器从已安装应用的模板目录加载模板。

如果您想使用 TEMPLATES 设置中的自定义项（例如上下文处理器）来渲染模板，请使用 TemplatesSetting 渲染器。

class DjangoDivFormRenderer

自 5.0 版本起已弃用。

DjangoTemplates 的别名。

Jinja2

class Jinja2

此渲染器与 DjangoTemplates 渲染器相同，但它使用 Jinja2 后端。内置小组件的模板位于 django/forms/jinja2 中，已安装的应用可以在 jinja2 目录中提供模板。

要使用此后端，项目及其第三方应用中的所有表单和小组件都必须具有 Jinja2 模板。除非你为没有 Jinja2 模板的小组件提供自己的 Jinja2 模板，否则你无法使用此渲染器。例如，django.contrib.admin 由于使用了 Django 模板标签，因此不为其小组件包含 Jinja2 模板。

class Jinja2DivFormRenderer

自 5.0 版本起已弃用。

Jinja2 的别名。

TemplatesSetting

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：所有隐藏绑定字段。
  • errors：所有非字段相关或隐藏字段相关的表单错误。

字段模板中可用的上下文

Django 5.0 中的新增功能。

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

小部件模板中可用的上下文

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

  • name
  • value
  • attrs
  • is_hidden
  • template_name

一些小部件会向上下文中添加更多信息。例如，所有继承 Input 的小部件都会定义 widget['type']，而 MultiWidget 会定义 widget['subwidgets'] 以便循环使用。

覆盖内置表单集模板

BaseFormSet.template_name

要覆盖表单集模板，必须使用 TemplatesSetting 渲染器。然后，覆盖表单集模板的工作方式与 覆盖 项目中的任何其他模板的工作方式相同。

覆盖内置表单模板

Form.template_name

要覆盖表单模板，您必须使用 TemplatesSetting 渲染器。然后覆盖表单模板的工作方式 与 覆盖项目中的任何其他模板相同。

覆盖内置字段模板

Django 5.0 中的新增功能。

Field.template_name

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

覆盖内置小组件模板

每个小组件都有一个 template_name 属性，其值如 input.html。内置小组件模板存储在 django/forms/widgets 路径中。例如，您可以通过定义 django/forms/widgets/input.html 来为 input.html 提供自定义模板。有关每个小组件模板的名称，请参见 内置小组件。

要覆盖小组件模板，您必须使用 TemplatesSetting 渲染器。然后覆盖小组件模板的工作方式 与 覆盖项目中的任何其他模板相同。

表单集函数
小组件
返回顶部