# Django 5.2.8 documentation

# 表单渲染 API

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

表单渲染过程可以在几个层次上进行定制：

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

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

- 组件的模板可以被项目覆盖。（可重用的应用程序通常不应该覆盖内置模板，因为它们可能与项目的自定义模板相冲突。）

## 低级渲染 API

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

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

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

相同的要点也适用于表单集的渲染。有关详细信息，请参阅 在视图和模板中使用formset。

Use one of the built-in template form renderers or implement your own. Custom renderers must implement a `render(template_name, context, request=None)` method. It should return a rendered template (as a string) or raise `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.

    The default class used to represent form fields across the project.

    Defaults to `BoundField` class.

    This can be customized further using `Form.bound_field_class` for per-form overrides, or `Field.bound_field_class` for per-field overrides.

  get_template(template_name)

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

  render(template_name, context, request=None)

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

## 内置模板表单渲染器

### `DjangoTemplates`

class DjangoTemplates

这个渲染器使用一个独立的 `DjangoTemplates` 引擎（与你在 `TEMPLATES` 设置中配置的可能不同）。它首先从 django/forms/templates 中的内置表单模板目录加载模板，然后使用 `app_directories` 加载程序从已安装的应用程序模板目录加载模板。

如果你想用你的 `TEMPLATES` 配置中的自定义配置来渲染模板，例如上下文处理器，使用 `TemplatesSetting` 渲染器。

### `Jinja2`

class Jinja2

这个渲染器与 `DjangoTemplates` 渲染器相同，唯一的区别是它使用了 `Jinja2` 后端。内置小部件的模板位于 django/forms/jinja2 中，已安装的应用程序可以在 `jinja2` 目录中提供模板。

要使用这个后端，你的项目及其第三方应用程序中的所有表单和部件必须有 Jinja2 模板。除非你为那些没有 Jinja2 模板的部件提供自己的 Jinja2 模板，否则你不能使用这个渲染器。例如， `django.contrib.admin` 由于使用了 Django 模板标签，所以它的部件不包含 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`： 所有与字段无关的或与隐藏字段有关的表单错误。

## 字段模板中可用的上下文

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

- `field`: `BoundField`.

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

部件模板从 `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` 渲染器。然后，重写表单模板的工作方式与重写项目中的任何其他模板 相同。

## 覆盖内置字段模板

`Field.template_name`

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

## 覆盖内置部件模板

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

要覆盖部件模板，你必须使用 `TemplatesSetting` 渲染器。然后覆盖部件模板的工作原理 和覆盖项目中的任何其他模板一样。