表单渲染 API — Django 文档
表单渲染 API
Django 的表单小部件使用 Django 的 模板引擎系统 呈现。
表单渲染过程可以在几个层次上进行定制:
- 部件可以指定自定义模板名称。
- 表单和部件可以指定自定义渲染器类。
- 小部件的模板可以被项目覆盖。 (可重用应用程序通常不应覆盖内置模板,因为它们可能与项目的自定义模板冲突。)
低级渲染 API
表单模板的呈现由可定制的呈现器类控制。 可以通过更新 :setting:`FORM_RENDERER` 设置来指定自定义渲染器。 它默认为 '
django.forms.renderers.DjangoTemplates'
。
您还可以通过设置 Form.default_renderer 属性或使用 Widget.render() 的 renderer
参数来提供自定义渲染器。
使用 内置模板表单渲染器 之一或实现您自己的。 自定义渲染器必须实现 render(template_name, context, request=None)
方法。 它应该返回呈现的模板(作为字符串)或引发 TemplateDoesNotExist。
内置模板表单渲染器
DjangoTemplates
- class DjangoTemplates
此渲染器使用独立的 DjangoTemplates 引擎(与您可能在 :setting:`TEMPLATES` 设置中配置的内容无关)。 它首先从 django/forms/templates
中的内置表单模板目录中加载模板,然后使用 app_directories 加载器从已安装的应用程序的模板目录中加载模板。
如果您想使用来自 :setting:`TEMPLATES` 设置的自定义来渲染模板,例如上下文处理器,请使用 TemplatesSetting 渲染器。
Jinja2
- class Jinja2
此渲染器与 DjangoTemplates 渲染器相同,只是它使用 Jinja2 后端。 内置小部件的模板位于 django/forms/jinja2
中,安装的应用程序可以在 jinja2
目录中提供模板。
要使用此后端,您项目中的所有小部件及其第三方应用程序都必须具有 Jinja2 模板。 除非您为没有的小部件提供自己的 Jinja2 模板,否则您不能使用此渲染器。 例如,django.contrib.admin 不包括 Jinja2 模板,因为它们使用了 Django 模板标签。
TemplatesSetting
- class TemplatesSetting
此渲染器使您可以完全控制小部件模板的来源。 它使用 get_template() 根据 :setting:`TEMPLATES` 设置中的配置来查找小部件模板。
使用这个渲染器和内置的部件模板有以下两种方式:
'django.forms'
在 :设置:`INSTALLED_APPS` 和至少一台发动机 :设置:`APP_DIRS =真 ` .在中添加内置小部件模板目录 :setting:`目录 ` 您的模板引擎之一。 要生成该路径:
import django django.__path__[0] + '/forms/templates' # or '/forms/jinja2'
使用这个渲染器需要你确保你的项目所需的表单模板可以被找到。
部件模板中可用的上下文
小部件模板从 Widget.get_context() 接收上下文。 默认情况下,小部件在上下文中接收单个值,widget
。 这是一个包含以下值的字典:
name
value
attrs
is_hidden
template_name
一些小部件向上下文添加更多信息。 例如,所有子类 Input
定义 widget['type']
和 MultiWidget 定义 widget['subwidgets']
用于循环目的的小部件。
覆盖内置部件模板
每个小部件都有一个 template_name
属性,其值为 input.html
。 内置小部件模板存储在 django/forms/widgets
路径中。 例如,您可以通过定义 django/forms/widgets/input.html
为 input.html
提供自定义模板。 有关每个小部件模板的名称,请参阅 内置小部件 。
要覆盖小部件模板,您必须使用 TemplatesSetting 渲染器。 然后覆盖小部件模板的工作方式 与覆盖项目中的任何其他模板的 相同。