{"title":"表单渲染 API","version":"4.1","locale":"zh-hans","docname":"ref/forms/renderers","url":"/zh-hans/4.1/ref/forms/renderers/","canonical":"https://djangodocs.dev/zh-hans/4.1/ref/forms/renderers/","summary":"Django 的表单部件是使用 Django 的 模板引擎系统 渲染的。 表单渲染过程可以在几个层次上进行定制： 部件可以指定自定义模板名称。 表单和部件可以指定自定义渲染器类。 组件的模板可以被项目覆盖。（可重用的应用程序通常不应该覆盖内置模板，因为它们可能与项目的自定义模板相冲突。） 低级渲染 API Link to…","html":"<span id=\"the-form-rendering-api\"></span><h1>表单渲染 API<a class=\"heading-anchor\" href=\"#module-django.forms.renderers\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h1>\n<p>Django 的表单部件是使用 Django 的 <a class=\"reference internal\" href=\"/zh-hans/4.1/topics/templates/\"><span class=\"doc\">模板引擎系统</span></a> 渲染的。</p>\n<p>表单渲染过程可以在几个层次上进行定制：</p>\n<ul class=\"simple\">\n<li><p>部件可以指定自定义模板名称。</p></li>\n<li><p>表单和部件可以指定自定义渲染器类。</p></li>\n<li><p>组件的模板可以被项目覆盖。（可重用的应用程序通常不应该覆盖内置模板，因为它们可能与项目的自定义模板相冲突。）</p></li>\n</ul>\n<section id=\"the-low-level-render-api\">\n<span id=\"low-level-widget-render-api\"></span><h2>低级渲染 API<a class=\"heading-anchor\" href=\"#the-low-level-render-api\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>表单模板的渲染是由一个可定制的渲染器类控制的。可以通过更新 <a class=\"reference internal\" href=\"/zh-hans/4.1/ref/settings/#std-setting-FORM_RENDERER\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">FORM_RENDERER</span></code></a> 配置来指定自定义渲染器。它的默认值是 <code class=\"docutils literal notranslate\"><span class=\"pre\">'</span></code><a class=\"reference internal\" href=\"#django.forms.renderers.DjangoTemplates\" title=\"django.forms.renderers.DjangoTemplates\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">django.forms.renderers.DjangoTemplates</span></code></a><code class=\"docutils literal notranslate\"><span class=\"pre\">'</span></code>。</p>\n<p>By specifying a custom form renderer and overriding\n<a class=\"reference internal\" href=\"#django.forms.renderers.BaseRenderer.form_template_name\" title=\"django.forms.renderers.BaseRenderer.form_template_name\"><code class=\"xref py py-attr docutils literal notranslate\"><span class=\"pre\">form_template_name</span></code></a> you can adjust the default form\nmarkup across your project from a single place.</p>\n<p>You can also provide a custom renderer per-form or per-widget by setting the\n<a class=\"reference internal\" href=\"/zh-hans/4.1/ref/forms/api/#django.forms.Form.default_renderer\" title=\"django.forms.Form.default_renderer\"><code class=\"xref py py-attr docutils literal notranslate\"><span class=\"pre\">Form.default_renderer</span></code></a> attribute or by using the <code class=\"docutils literal notranslate\"><span class=\"pre\">renderer</span></code> argument\nof <a class=\"reference internal\" href=\"/zh-hans/4.1/ref/forms/api/#django.forms.Form.render\" title=\"django.forms.Form.render\"><code class=\"xref py py-meth docutils literal notranslate\"><span class=\"pre\">Form.render()</span></code></a>, or <a class=\"reference internal\" href=\"/zh-hans/4.1/ref/forms/widgets/#django.forms.Widget.render\" title=\"django.forms.Widget.render\"><code class=\"xref py py-meth docutils literal notranslate\"><span class=\"pre\">Widget.render()</span></code></a>.</p>\n<p>Matching points apply to formset rendering. See <a class=\"reference internal\" href=\"/zh-hans/4.1/topics/forms/formsets/#formset-rendering\"><span class=\"std std-ref\">在视图和模板中使用formset</span></a> for\ndiscussion.</p>\n<p>使用 <a class=\"reference internal\" href=\"#built-in-template-form-renderers\"><span class=\"std std-ref\">内置模板表单渲染器</span></a> 或实现你自己的模板表单渲染器。自定义渲染器必须实现一个 <code class=\"docutils literal notranslate\"><span class=\"pre\">render(template_name,</span> <span class=\"pre\">context,</span> <span class=\"pre\">request=None)</span></code> 方法。它应该返回一个已渲染的模板（作为一个字符串）或引发 <a class=\"reference internal\" href=\"/zh-hans/4.1/topics/templates/#django.template.TemplateDoesNotExist\" title=\"django.template.TemplateDoesNotExist\"><code class=\"xref py py-exc docutils literal notranslate\"><span class=\"pre\">TemplateDoesNotExist</span></code></a>。</p>\n<dl class=\"py class\">\n<dt class=\"sig sig-object py\" id=\"django.forms.renderers.BaseRenderer\">\n<em class=\"property\"><span class=\"k\"><span class=\"pre\">class</span></span><span class=\"w\"> </span></em><span class=\"sig-name descname\"><span class=\"pre\">BaseRenderer</span></span><a class=\"heading-anchor\" href=\"#django.forms.renderers.BaseRenderer\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>The base class for the built-in form renderers.</p>\n<dl class=\"py attribute\">\n<dt class=\"sig sig-object py\" id=\"django.forms.renderers.BaseRenderer.form_template_name\">\n<span class=\"sig-name descname\"><span class=\"pre\">form_template_name</span></span><a class=\"heading-anchor\" href=\"#django.forms.renderers.BaseRenderer.form_template_name\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><aside class=\"version-note version-added\" data-version=\"4.1\">\n<p class=\"version-note-title\">New in Django 4.1</p></aside>\n<p>The default name of the template to use to render a form.</p>\n<p>Defaults to <code class=\"docutils literal notranslate\"><span class=\"pre\">&quot;django/forms/default.html&quot;</span></code>, which is a proxy for\n<code class=\"docutils literal notranslate\"><span class=\"pre\">&quot;django/forms/table.html&quot;</span></code>.</p>\n<aside class=\"version-note version-deprecated\" data-version=\"4.1\">\n<p class=\"version-note-title\">Deprecated since Django 4.1</p><p><span class=\"versionmodified deprecated\">Deprecated since version 4.1.</span></p>\n</aside>\n<p>The <code class=\"docutils literal notranslate\"><span class=\"pre\">&quot;django/forms/default.html&quot;</span></code> template is deprecated and will be\nremoved in Django 5.0. The default will become\n<code class=\"docutils literal notranslate\"><span class=\"pre\">&quot;django/forms/div.html&quot;</span></code> at that time.</p>\n</dd></dl>\n\n<dl class=\"py attribute\">\n<dt class=\"sig sig-object py\" id=\"django.forms.renderers.BaseRenderer.formset_template_name\">\n<span class=\"sig-name descname\"><span class=\"pre\">formset_template_name</span></span><a class=\"heading-anchor\" href=\"#django.forms.renderers.BaseRenderer.formset_template_name\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><aside class=\"version-note version-added\" data-version=\"4.1\">\n<p class=\"version-note-title\">New in Django 4.1</p></aside>\n<p>The default name of the template to use to render a formset.</p>\n<p>Defaults to <code class=\"docutils literal notranslate\"><span class=\"pre\">&quot;django/forms/formsets/default.html&quot;</span></code>, which is a proxy\nfor <code class=\"docutils literal notranslate\"><span class=\"pre\">&quot;django/forms/formsets/table.html&quot;</span></code>.</p>\n<aside class=\"version-note version-deprecated\" data-version=\"4.1\">\n<p class=\"version-note-title\">Deprecated since Django 4.1</p><p><span class=\"versionmodified deprecated\">Deprecated since version 4.1.</span></p>\n</aside>\n<p>The <code class=\"docutils literal notranslate\"><span class=\"pre\">&quot;django/forms/formset/default.html&quot;</span></code> template is deprecated and\nwill be removed in Django 5.0. The default will become\n<code class=\"docutils literal notranslate\"><span class=\"pre\">&quot;django/forms/formset/div.html&quot;</span></code> template.</p>\n</dd></dl>\n\n<dl class=\"py method\">\n<dt class=\"sig sig-object py\" id=\"django.forms.renderers.BaseRenderer.get_template\">\n<span class=\"sig-name descname\"><span class=\"pre\">get_template</span></span><span class=\"sig-paren\">(</span><em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">template_name</span></span></em><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.forms.renderers.BaseRenderer.get_template\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>Subclasses must implement this method with the appropriate template\nfinding logic.</p>\n</dd></dl>\n\n<dl class=\"py method\">\n<dt class=\"sig sig-object py\" id=\"django.forms.renderers.BaseRenderer.render\">\n<span class=\"sig-name descname\"><span class=\"pre\">render</span></span><span class=\"sig-paren\">(</span><em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">template_name</span></span></em>, <em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">context</span></span></em>, <em class=\"sig-param\"><span class=\"n\"><span class=\"pre\">request</span></span><span class=\"o\"><span class=\"pre\">=</span></span><span class=\"default_value\"><span class=\"pre\">None</span></span></em><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.forms.renderers.BaseRenderer.render\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>Renders the given template, or raises\n<a class=\"reference internal\" href=\"/zh-hans/4.1/topics/templates/#django.template.TemplateDoesNotExist\" title=\"django.template.TemplateDoesNotExist\"><code class=\"xref py py-exc docutils literal notranslate\"><span class=\"pre\">TemplateDoesNotExist</span></code></a>.</p>\n</dd></dl>\n\n</dd></dl>\n\n</section>\n<section id=\"built-in-template-form-renderers\">\n<span id=\"id1\"></span><h2>内置模板表单渲染器<a class=\"heading-anchor\" href=\"#built-in-template-form-renderers\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<section id=\"djangotemplates\">\n<h3><code class=\"docutils literal notranslate\"><span class=\"pre\">DjangoTemplates</span></code><a class=\"heading-anchor\" href=\"#djangotemplates\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h3>\n<dl class=\"py class\">\n<dt class=\"sig sig-object py\" id=\"django.forms.renderers.DjangoTemplates\">\n<em class=\"property\"><span class=\"k\"><span class=\"pre\">class</span></span><span class=\"w\"> </span></em><span class=\"sig-name descname\"><span class=\"pre\">DjangoTemplates</span></span><a class=\"heading-anchor\" href=\"#django.forms.renderers.DjangoTemplates\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd></dd></dl>\n\n<p>这个渲染器使用一个独立的 <a class=\"reference internal\" href=\"/zh-hans/4.1/topics/templates/#django.template.backends.django.DjangoTemplates\" title=\"django.template.backends.django.DjangoTemplates\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">DjangoTemplates</span></code></a> 引擎（与你在 <a class=\"reference internal\" href=\"/zh-hans/4.1/ref/settings/#std-setting-TEMPLATES\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">TEMPLATES</span></code></a> 配置中设置的内容无关）。它首先从 <code class=\"docutils literal notranslate\"><span class=\"pre\">django/forms/templates</span></code> 内置的表单模板目录中加载模板，然后使用 <a class=\"reference internal\" href=\"/zh-hans/4.1/ref/templates/api/#django.template.loaders.app_directories.Loader\" title=\"django.template.loaders.app_directories.Loader\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">app_directories</span></code></a> 加载器从已安装的应用的模板目录中加载模板。</p>\n<p>如果你想用你的 <a class=\"reference internal\" href=\"/zh-hans/4.1/ref/settings/#std-setting-TEMPLATES\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">TEMPLATES</span></code></a> 配置中的自定义配置来渲染模板，例如上下文处理器，使用 <a class=\"reference internal\" href=\"#django.forms.renderers.TemplatesSetting\" title=\"django.forms.renderers.TemplatesSetting\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">TemplatesSetting</span></code></a> 渲染器。</p>\n<dl class=\"py class\">\n<dt class=\"sig sig-object py\" id=\"django.forms.renderers.DjangoDivFormRenderer\">\n<em class=\"property\"><span class=\"k\"><span class=\"pre\">class</span></span><span class=\"w\"> </span></em><span class=\"sig-name descname\"><span class=\"pre\">DjangoDivFormRenderer</span></span><a class=\"heading-anchor\" href=\"#django.forms.renderers.DjangoDivFormRenderer\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd></dd></dl>\n\n<aside class=\"version-note version-added\" data-version=\"4.1\">\n<p class=\"version-note-title\">New in Django 4.1</p></aside>\n<p>Subclass of <a class=\"reference internal\" href=\"#django.forms.renderers.DjangoTemplates\" title=\"django.forms.renderers.DjangoTemplates\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">DjangoTemplates</span></code></a> that specifies\n<a class=\"reference internal\" href=\"#django.forms.renderers.BaseRenderer.form_template_name\" title=\"django.forms.renderers.BaseRenderer.form_template_name\"><code class=\"xref py py-attr docutils literal notranslate\"><span class=\"pre\">form_template_name</span></code></a> and\n<a class=\"reference internal\" href=\"#django.forms.renderers.BaseRenderer.formset_template_name\" title=\"django.forms.renderers.BaseRenderer.formset_template_name\"><code class=\"xref py py-attr docutils literal notranslate\"><span class=\"pre\">formset_template_name</span></code></a> as <code class=\"docutils literal notranslate\"><span class=\"pre\">&quot;django/forms/div.html&quot;</span></code> and\n<code class=\"docutils literal notranslate\"><span class=\"pre\">&quot;django/forms/formset/div.html&quot;</span></code> respectively.</p>\n<p>This is a transitional renderer for opt-in to the new <code class=\"docutils literal notranslate\"><span class=\"pre\">&lt;div&gt;</span></code> based\ntemplates, which are the default from Django 5.0.</p>\n<p>Apply this via the <a class=\"reference internal\" href=\"/zh-hans/4.1/ref/settings/#std-setting-FORM_RENDERER\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">FORM_RENDERER</span></code></a> setting:</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><span class=\"n\">FORM_RENDERER</span> <span class=\"o\">=</span> <span class=\"s2\">&quot;django.forms.renderers.DjangoDivFormRenderer&quot;</span>\n</code></pre></div>\n<p>Once the <code class=\"docutils literal notranslate\"><span class=\"pre\">&lt;div&gt;</span></code> templates are the default, this transitional renderer will\nbe deprecated, for removal in Django 6.0. The <code class=\"docutils literal notranslate\"><span class=\"pre\">FORM_RENDERER</span></code> declaration can\nbe removed at that time.</p>\n</section>\n<section id=\"jinja2\">\n<h3><code class=\"docutils literal notranslate\"><span class=\"pre\">Jinja2</span></code><a class=\"heading-anchor\" href=\"#jinja2\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h3>\n<dl class=\"py class\">\n<dt class=\"sig sig-object py\" id=\"django.forms.renderers.Jinja2\">\n<em class=\"property\"><span class=\"k\"><span class=\"pre\">class</span></span><span class=\"w\"> </span></em><span class=\"sig-name descname\"><span class=\"pre\">Jinja2</span></span><a class=\"heading-anchor\" href=\"#django.forms.renderers.Jinja2\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd></dd></dl>\n\n<p>这个渲染器和 <a class=\"reference internal\" href=\"#django.forms.renderers.DjangoTemplates\" title=\"django.forms.renderers.DjangoTemplates\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">DjangoTemplates</span></code></a> 渲染器一样，只是它使用了 <a class=\"reference internal\" href=\"/zh-hans/4.1/topics/templates/#django.template.backends.jinja2.Jinja2\" title=\"django.template.backends.jinja2.Jinja2\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">Jinja2</span></code></a> 后台。内置部件的模板位于 <code class=\"docutils literal notranslate\"><span class=\"pre\">django/forms/jinja2</span></code>，安装的应用可以在 <code class=\"docutils literal notranslate\"><span class=\"pre\">jinja2</span></code> 目录下提供模板。</p>\n<p>要使用这个后端，你的项目及其第三方应用程序中的所有表单和部件必须有 Jinja2 模板。除非你为那些没有 Jinja2 模板的部件提供自己的 Jinja2 模板，否则你不能使用这个渲染器。例如， <a class=\"reference internal\" href=\"/zh-hans/4.1/ref/contrib/admin/#module-django.contrib.admin\" title=\"django.contrib.admin: Django's admin site.\"><code class=\"xref py py-mod docutils literal notranslate\"><span class=\"pre\">django.contrib.admin</span></code></a> 由于使用了 Django 模板标签，所以它的部件不包含 Jinja2 模板。</p>\n<dl class=\"py class\">\n<dt class=\"sig sig-object py\" id=\"django.forms.renderers.Jinja2DivFormRenderer\">\n<em class=\"property\"><span class=\"k\"><span class=\"pre\">class</span></span><span class=\"w\"> </span></em><span class=\"sig-name descname\"><span class=\"pre\">Jinja2DivFormRenderer</span></span><a class=\"heading-anchor\" href=\"#django.forms.renderers.Jinja2DivFormRenderer\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd></dd></dl>\n\n<aside class=\"version-note version-added\" data-version=\"4.1\">\n<p class=\"version-note-title\">New in Django 4.1</p></aside>\n<p>A transitional renderer as per <a class=\"reference internal\" href=\"#django.forms.renderers.DjangoDivFormRenderer\" title=\"django.forms.renderers.DjangoDivFormRenderer\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">DjangoDivFormRenderer</span></code></a> above, but\nsubclassing <a class=\"reference internal\" href=\"#django.forms.renderers.Jinja2\" title=\"django.forms.renderers.Jinja2\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">Jinja2</span></code></a> for use with the Jinja2 backend.</p>\n<p>Apply this via the <a class=\"reference internal\" href=\"/zh-hans/4.1/ref/settings/#std-setting-FORM_RENDERER\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">FORM_RENDERER</span></code></a> setting:</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><span class=\"n\">FORM_RENDERER</span> <span class=\"o\">=</span> <span class=\"s2\">&quot;django.forms.renderers.Jinja2DivFormRenderer&quot;</span>\n</code></pre></div>\n</section>\n<section id=\"templatessetting\">\n<h3><code class=\"docutils literal notranslate\"><span class=\"pre\">TemplatesSetting</span></code><a class=\"heading-anchor\" href=\"#templatessetting\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h3>\n<dl class=\"py class\">\n<dt class=\"sig sig-object py\" id=\"django.forms.renderers.TemplatesSetting\">\n<em class=\"property\"><span class=\"k\"><span class=\"pre\">class</span></span><span class=\"w\"> </span></em><span class=\"sig-name descname\"><span class=\"pre\">TemplatesSetting</span></span><a class=\"heading-anchor\" href=\"#django.forms.renderers.TemplatesSetting\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd></dd></dl>\n\n<p>这个渲染器让你完全控制表单和小工具模板的来源。它使用 <a class=\"reference internal\" href=\"/zh-hans/4.1/topics/templates/#django.template.loader.get_template\" title=\"django.template.loader.get_template\"><code class=\"xref py py-func docutils literal notranslate\"><span class=\"pre\">get_template()</span></code></a> 来查找基于 <a class=\"reference internal\" href=\"/zh-hans/4.1/ref/settings/#std-setting-TEMPLATES\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">TEMPLATES</span></code></a> 配置中所设置的模板。</p>\n<p>使用该渲染器和内置模板需要以下两种方法之一：</p>\n<ul>\n<li><p><code class=\"docutils literal notranslate\"><span class=\"pre\">'django.forms'</span></code> 在 <a class=\"reference internal\" href=\"/zh-hans/4.1/ref/settings/#std-setting-INSTALLED_APPS\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">INSTALLED_APPS</span></code></a> 和至少一个引擎有 <a class=\"reference internal\" href=\"/zh-hans/4.1/ref/settings/#std-setting-TEMPLATES-APP_DIRS\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">APP_DIRS=True</span></code></a>。</p></li>\n<li><p>在你的一个模板引擎的 <a class=\"reference internal\" href=\"/zh-hans/4.1/ref/settings/#std-setting-TEMPLATES-DIRS\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">DIRS</span></code></a> 中添加内置模板目录。要生成该路径：</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><span class=\"kn\">import</span><span class=\"w\"> </span><span class=\"nn\">django</span>\n<span class=\"n\">django</span><span class=\"o\">.</span><span class=\"n\">__path__</span><span class=\"p\">[</span><span class=\"mi\">0</span><span class=\"p\">]</span> <span class=\"o\">+</span> <span class=\"s1\">&#39;/forms/templates&#39;</span>  <span class=\"c1\"># or &#39;/forms/jinja2&#39;</span>\n</code></pre></div>\n</li>\n</ul>\n<p>使用这个渲染器需要你确保你的项目所需的表单模板可以被找到。</p>\n</section>\n</section>\n<section id=\"context-available-in-formset-templates\">\n<h2>表单集模板中可用的上下文<a class=\"heading-anchor\" href=\"#context-available-in-formset-templates\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<aside class=\"version-note version-added\" data-version=\"4.0\">\n<p class=\"version-note-title\">New in Django 4.0</p></aside>\n<p>表单集模板从 <a class=\"reference internal\" href=\"/zh-hans/4.1/topics/forms/formsets/#django.forms.formsets.BaseFormSet.get_context\" title=\"django.forms.formsets.BaseFormSet.get_context\"><code class=\"xref py py-meth docutils literal notranslate\"><span class=\"pre\">BaseFormSet.get_context()</span></code></a> 接收一个上下文。默认情况下，表单集接收一个具有以下值的字典：</p>\n<ul class=\"simple\">\n<li><p><code class=\"docutils literal notranslate\"><span class=\"pre\">formset</span></code>：表单集实例。</p></li>\n</ul>\n</section>\n<section id=\"context-available-in-form-templates\">\n<h2>表单模板中可用的上下文<a class=\"heading-anchor\" href=\"#context-available-in-form-templates\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<aside class=\"version-note version-added\" data-version=\"4.0\">\n<p class=\"version-note-title\">New in Django 4.0</p></aside>\n<p>表单模板从 <a class=\"reference internal\" href=\"/zh-hans/4.1/ref/forms/api/#django.forms.Form.get_context\" title=\"django.forms.Form.get_context\"><code class=\"xref py py-meth docutils literal notranslate\"><span class=\"pre\">Form.get_context()</span></code></a> 接收一个上下文。默认情况下，表单接收一个具有以下值的字典：</p>\n<ul class=\"simple\">\n<li><p><code class=\"docutils literal notranslate\"><span class=\"pre\">form</span></code>: 绑定表单</p></li>\n<li><p><code class=\"docutils literal notranslate\"><span class=\"pre\">fields</span></code>： 所有绑定字段，除了隐藏字段。</p></li>\n<li><p>·hidden_fields`： 所有隐藏的绑定字段。</p></li>\n<li><p><code class=\"docutils literal notranslate\"><span class=\"pre\">errors</span></code>： 所有与字段无关的或与隐藏字段有关的表单错误。</p></li>\n</ul>\n</section>\n<section id=\"context-available-in-widget-templates\">\n<h2>部件模板中可用的上下文<a class=\"heading-anchor\" href=\"#context-available-in-widget-templates\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>部件模板从 <a class=\"reference internal\" href=\"/zh-hans/4.1/ref/forms/widgets/#django.forms.Widget.get_context\" title=\"django.forms.Widget.get_context\"><code class=\"xref py py-meth docutils literal notranslate\"><span class=\"pre\">Widget.get_context()</span></code></a> 中接收一个上下文。默认情况下，部件在上下文中只接收一个值，<code class=\"docutils literal notranslate\"><span class=\"pre\">widget</span></code>。这是一个字典，其中包含的值如：</p>\n<ul class=\"simple\">\n<li><p><code class=\"docutils literal notranslate\"><span class=\"pre\">name</span></code></p></li>\n<li><p><code class=\"docutils literal notranslate\"><span class=\"pre\">value</span></code></p></li>\n<li><p><code class=\"docutils literal notranslate\"><span class=\"pre\">attrs</span></code></p></li>\n<li><p><code class=\"docutils literal notranslate\"><span class=\"pre\">is_hidden</span></code></p></li>\n<li><p><code class=\"docutils literal notranslate\"><span class=\"pre\">template_name</span></code></p></li>\n</ul>\n<p>有些部件会给上下文添加更多信息。例如，所有子类 <code class=\"docutils literal notranslate\"><span class=\"pre\">Input</span></code> 定义了 <code class=\"docutils literal notranslate\"><span class=\"pre\">widget['type']</span></code> 和 <a class=\"reference internal\" href=\"/zh-hans/4.1/ref/forms/widgets/#django.forms.MultiWidget\" title=\"django.forms.MultiWidget\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">MultiWidget</span></code></a> 定义了 <code class=\"docutils literal notranslate\"><span class=\"pre\">widget['subwidgets']</span></code> 用于循环。</p>\n</section>\n<section id=\"overriding-built-in-formset-templates\">\n<span id=\"id2\"></span><h2>覆盖内置的表单集模板<a class=\"heading-anchor\" href=\"#overriding-built-in-formset-templates\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<aside class=\"version-note version-added\" data-version=\"4.0\">\n<p class=\"version-note-title\">New in Django 4.0</p></aside>\n<p><a class=\"reference internal\" href=\"/zh-hans/4.1/topics/forms/formsets/#django.forms.formsets.BaseFormSet.template_name\" title=\"django.forms.formsets.BaseFormSet.template_name\"><code class=\"xref py py-attr docutils literal notranslate\"><span class=\"pre\">BaseFormSet.template_name</span></code></a></p>\n<p>要覆盖表单模板，你必须使用 <a class=\"reference internal\" href=\"#django.forms.renderers.TemplatesSetting\" title=\"django.forms.renderers.TemplatesSetting\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">TemplatesSetting</span></code></a> 渲染器。然后，覆盖部件模板的工作方式和覆盖你项目中的任何其他模板  <a class=\"reference internal\" href=\"/zh-hans/4.1/howto/overriding-templates/\"><span class=\"doc\">一样</span></a>。</p>\n</section>\n<section id=\"overriding-built-in-form-templates\">\n<span id=\"id3\"></span><h2>覆盖内置表单模板<a class=\"heading-anchor\" href=\"#overriding-built-in-form-templates\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<aside class=\"version-note version-added\" data-version=\"4.0\">\n<p class=\"version-note-title\">New in Django 4.0</p></aside>\n<p><a class=\"reference internal\" href=\"/zh-hans/4.1/ref/forms/api/#django.forms.Form.template_name\" title=\"django.forms.Form.template_name\"><code class=\"xref py py-attr docutils literal notranslate\"><span class=\"pre\">Form.template_name</span></code></a></p>\n<p>要覆盖表单模板，你必须使用 <a class=\"reference internal\" href=\"#django.forms.renderers.TemplatesSetting\" title=\"django.forms.renderers.TemplatesSetting\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">TemplatesSetting</span></code></a> 渲染器。然后，覆盖部件模板的工作方式与覆盖你项目中的任何其他模板  <a class=\"reference internal\" href=\"/zh-hans/4.1/howto/overriding-templates/\"><span class=\"doc\">一样</span></a> 。</p>\n</section>\n<section id=\"overriding-built-in-widget-templates\">\n<span id=\"id4\"></span><h2>覆盖内置部件模板<a class=\"heading-anchor\" href=\"#overriding-built-in-widget-templates\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>每个部件都有一个 <code class=\"docutils literal notranslate\"><span class=\"pre\">template_name</span></code> 属性，其值如 <code class=\"docutils literal notranslate\"><span class=\"pre\">input.html</span></code>。内建的部件模板存储在 <code class=\"docutils literal notranslate\"><span class=\"pre\">django/forms/widgets</span></code> 路径中，你可以为 <code class=\"docutils literal notranslate\"><span class=\"pre\">input.html</span></code> 提供一个自定义模板。你可以通过定义 <code class=\"docutils literal notranslate\"><span class=\"pre\">django/forms/widgets/input.html</span></code> 来为 <code class=\"docutils literal notranslate\"><span class=\"pre\">input.html</span></code> 提供一个自定义模板，例如。参见 <a class=\"reference internal\" href=\"/zh-hans/4.1/ref/forms/widgets/#built-in-widgets\"><span class=\"std std-ref\">内置部件</span></a> 了解每个部件的模板名称。</p>\n<p>要覆盖部件模板，你必须使用 <a class=\"reference internal\" href=\"#django.forms.renderers.TemplatesSetting\" title=\"django.forms.renderers.TemplatesSetting\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">TemplatesSetting</span></code></a> 渲染器。然后覆盖部件模板的工作原理 <a class=\"reference internal\" href=\"/zh-hans/4.1/howto/overriding-templates/\"><span class=\"doc\">和覆盖项目中的任何其他模板一样</span></a>。</p>\n</section>","rootId":"module-django.forms.renderers","toc":[{"title":"低级渲染 API","anchor":"the-low-level-render-api","children":[]},{"title":"内置模板表单渲染器","anchor":"built-in-template-form-renderers","children":[{"title":"DjangoTemplates","anchor":"djangotemplates","children":[]},{"title":"Jinja2","anchor":"jinja2","children":[]},{"title":"TemplatesSetting","anchor":"templatessetting","children":[]}]},{"title":"表单集模板中可用的上下文","anchor":"context-available-in-formset-templates","children":[]},{"title":"表单模板中可用的上下文","anchor":"context-available-in-form-templates","children":[]},{"title":"部件模板中可用的上下文","anchor":"context-available-in-widget-templates","children":[]},{"title":"覆盖内置的表单集模板","anchor":"overriding-built-in-formset-templates","children":[]},{"title":"覆盖内置表单模板","anchor":"overriding-built-in-form-templates","children":[]},{"title":"覆盖内置部件模板","anchor":"overriding-built-in-widget-templates","children":[]}],"breadcrumbs":[{"docname":"ref/index","title":"API 参考","url":"/zh-hans/4.1/ref/"},{"docname":"ref/forms/index","title":"表单","url":"/zh-hans/4.1/ref/forms/"}],"prev":{"docname":"ref/forms/formsets","title":"表单集函数","url":"/zh-hans/4.1/ref/forms/formsets/"},"next":{"docname":"ref/forms/widgets","title":"部件","url":"/zh-hans/4.1/ref/forms/widgets/"},"formats":{"html":"/zh-hans/4.1/ref/forms/renderers/","markdown":"/zh-hans/4.1/ref/forms/renderers.md","json":"/zh-hans/4.1/ref/forms/renderers.json"},"source":"https://github.com/django/django/blob/stable/4.1.x/docs/ref/forms/renderers.txt","official":"https://docs.djangoproject.com/zh-hans/4.1/ref/forms/renderers/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0"],"inLocales":["en","zh-hans","fr","ja","id","it","pt-br","ko","es","el","pl"]}