表单渲染API

Django中的新功能1.11：

在旧版本中，使用Python渲染窗口小部件。 本文档中描述的所有API都是新的。

Django的表单小部件使用Django的template engines system进行渲染。

表单渲染过程可以在几个级别进行定制：

  • 小部件可以指定自定义模板名称。
  • 窗体和窗口小部件可以指定自定义渲染器类。
  • 小部件的模板可以被项目覆盖。 （可重用的应用程序通常不应该覆盖内置模板，因为它们可能与项目的自定义模板冲突。）

低级渲染API

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

您还可以通过设置Form.default_renderer属性或使用Widget.render()的renderer参数来提供自定义渲染器。

使用built-in template form renderers之一或实现您自己的。 自定义渲染器必须实现render（template_name， 上下文， request = None）方法。 它应该返回一个渲染的模板（作为一个字符串）或者提高TemplateDoesNotExist。

内置模板格式渲染器

DjangoTemplates

类 DjangoTemplates[source]

此渲染器使用独立的DjangoTemplates引擎（未连接到您在TEMPLATES设置中配置的内容）。 它首先从django/forms/templates中的内置表单模板目录加载模板，然后使用app_directories

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

Jinja2

类 Jinja2[source]

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

要使用此后端，项目中的所有小部件及其第三方应用程序都必须具有Jinja2模板。 除非您为没有任何的小部件提供您自己的Jinja2模板，否则不能使用此渲染器。 例如，由于使用了Django模板标签，django.contrib.admin不包含用于其小部件的Jinja2模板。

TemplatesSetting

类 TemplatesSetting[source]

此渲染器可以完全控制如何提供小部件模板。 它使用get_template()根据TEMPLATES设置中的配置来查找窗口小部件模板。

使用此渲染器以及内置的小部件模板需要：

  1. 'django.forms'在INSTALLED_APPS中，至少有一个引擎具有APP_DIRS=True。

  2. 在您的一个模板引擎的DIRS中添加内置的小部件模板目录。 要生成该路径：

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

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

Context available in widget templates

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

  • 名称
  • 值
  • ATTRS
  • is_hidden
  • TEMPLATE_NAME

一些小部件向上下文添加进一步的信息。 例如，子类Input的所有小部件都定义widget['type']和MultiWidget定义了widget['subwidgets']

Overriding built-in widget templates

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

如果您使用TemplatesSetting渲染器，覆盖小部件模板的作用与覆盖项目中的任何其他模板相同。 您不能使用其他内置渲染器覆盖内置的窗口小部件模板。