{"title":"表单渲染 API","version":"5.0","locale":"zh-hans","docname":"ref/forms/renderers","url":"/zh-hans/5.0/ref/forms/renderers/","canonical":"https://djangodocs.dev/zh-hans/5.0/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/5.0/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/5.0/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>通过指定自定义的表单渲染器并覆盖 <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>，你可以从一个地方调整整个项目中的默认表单标记。</p>\n<p>你还可以通过设置 <a class=\"reference internal\" href=\"/zh-hans/5.0/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> 属性，或者使用 <a class=\"reference internal\" href=\"/zh-hans/5.0/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> 或 <a class=\"reference internal\" href=\"/zh-hans/5.0/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> 的 <code class=\"docutils literal notranslate\"><span class=\"pre\">renderer</span></code> 参数，为每个表单或小部件提供自定义渲染器。</p>\n<p>相同的要点也适用于表单集的渲染。有关详细信息，请参阅 <a class=\"reference internal\" href=\"/zh-hans/5.0/topics/forms/formsets/#formset-rendering\"><span class=\"std std-ref\">在视图和模板中使用formset</span></a>。</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/5.0/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>用于内置表单渲染器的基类。</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><p>用于渲染表单的默认模板名称。</p>\n<p>默认为模板 <code class=\"docutils literal notranslate\"><span class=\"pre\">&quot;django/forms/div.html&quot;</span></code>。</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><p>用于渲染表单集的默认模板名称。</p>\n<p>默认为模板 <code class=\"docutils literal notranslate\"><span class=\"pre\">&quot;django/forms/formsets/div.html&quot;</span></code>。</p>\n</dd></dl>\n\n<dl class=\"py attribute\">\n<dt class=\"sig sig-object py\" id=\"django.forms.renderers.BaseRenderer.field_template_name\">\n<span class=\"sig-name descname\"><span class=\"pre\">field_template_name</span></span><a class=\"heading-anchor\" href=\"#django.forms.renderers.BaseRenderer.field_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=\"5.0\">\n<p class=\"version-note-title\">New in Django 5.0</p></aside>\n<p>用于渲染 <code class=\"docutils literal notranslate\"><span class=\"pre\">BoundField</span></code> 的模板的默认名称。</p>\n<p>默认为 <code class=\"docutils literal notranslate\"><span class=\"pre\">&quot;django/forms/field.html&quot;</span></code>。</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>子类必须使用适当的模板查找逻辑来实现此方法。</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>渲染给定的模板，或引发 <a class=\"reference internal\" href=\"/zh-hans/5.0/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/5.0/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/5.0/ref/settings/#std-setting-TEMPLATES\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">TEMPLATES</span></code></a> 设置中配置的可能不同）。它首先从 <a class=\"extlink-source reference external\" href=\"https://github.com/django/django/blob/stable/5.0.x/django/forms/templates\">django/forms/templates</a> 中的内置表单模板目录加载模板，然后使用 <a class=\"reference internal\" href=\"/zh-hans/5.0/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/5.0/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-deprecated\" data-version=\"5.0\">\n<p class=\"version-note-title\">Deprecated since Django 5.0</p><p><span class=\"versionmodified deprecated\">Deprecated since version 5.0.</span></p>\n</aside>\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> 的别名。</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/5.0/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> 后端。内置小部件的模板位于 <a class=\"extlink-source reference external\" href=\"https://github.com/django/django/blob/stable/5.0.x/django/forms/jinja2\">django/forms/jinja2</a> 中，已安装的应用程序可以在 <code class=\"docutils literal notranslate\"><span class=\"pre\">jinja2</span></code> 目录中提供模板。</p>\n<p>要使用这个后端，你的项目及其第三方应用程序中的所有表单和部件必须有 Jinja2 模板。除非你为那些没有 Jinja2 模板的部件提供自己的 Jinja2 模板，否则你不能使用这个渲染器。例如， <a class=\"reference internal\" href=\"/zh-hans/5.0/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-deprecated\" data-version=\"5.0\">\n<p class=\"version-note-title\">Deprecated since Django 5.0</p><p><span class=\"versionmodified deprecated\">Deprecated since version 5.0.</span></p>\n</aside>\n<p><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> 的别名。</p>\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/5.0/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/5.0/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/5.0/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/5.0/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/5.0/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\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=\"s2\">&quot;/forms/templates&quot;</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<p>表单集模板从 <a class=\"reference internal\" href=\"/zh-hans/5.0/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<p>表单模板从 <a class=\"reference internal\" href=\"/zh-hans/5.0/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><code class=\"docutils literal notranslate\"><span class=\"pre\">hidden_fields</span></code>： 所有隐藏的绑定字段。</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-field-templates\">\n<h2>字段模板中可用的上下文<a class=\"heading-anchor\" href=\"#context-available-in-field-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=\"5.0\">\n<p class=\"version-note-title\">New in Django 5.0</p></aside>\n<p>字段模板从 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/forms/api/#django.forms.BoundField.get_context\" title=\"django.forms.BoundField.get_context\"><code class=\"xref py py-meth docutils literal notranslate\"><span class=\"pre\">BoundField.get_context()</span></code></a> 接收上下文。默认情况下，字段接收一个包含以下值的字典：</p>\n<ul class=\"simple\">\n<li><p><code class=\"docutils literal notranslate\"><span class=\"pre\">field</span></code>: <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/forms/api/#django.forms.BoundField\" title=\"django.forms.BoundField\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">BoundField</span></code></a>.</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/5.0/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/5.0/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<p><a class=\"reference internal\" href=\"/zh-hans/5.0/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/5.0/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<p><a class=\"reference internal\" href=\"/zh-hans/5.0/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/5.0/howto/overriding-templates/\"><span class=\"doc\">相同</span></a>。</p>\n</section>\n<section id=\"overriding-built-in-field-templates\">\n<span id=\"id4\"></span><h2>覆盖内置字段模板<a class=\"heading-anchor\" href=\"#overriding-built-in-field-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=\"5.0\">\n<p class=\"version-note-title\">New in Django 5.0</p></aside>\n<p><a class=\"reference internal\" href=\"/zh-hans/5.0/ref/forms/fields/#django.forms.Field.template_name\" title=\"django.forms.Field.template_name\"><code class=\"xref py py-attr docutils literal notranslate\"><span class=\"pre\">Field.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/5.0/howto/overriding-templates/\"><span class=\"doc\">相同</span></a>。</p>\n</section>\n<section id=\"overriding-built-in-widget-templates\">\n<span id=\"id5\"></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/5.0/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/5.0/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-field-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-field-templates","children":[]},{"title":"覆盖内置部件模板","anchor":"overriding-built-in-widget-templates","children":[]}],"breadcrumbs":[{"docname":"ref/index","title":"API 参考","url":"/zh-hans/5.0/ref/"},{"docname":"ref/forms/index","title":"表单","url":"/zh-hans/5.0/ref/forms/"}],"prev":{"docname":"ref/forms/formsets","title":"表单集函数","url":"/zh-hans/5.0/ref/forms/formsets/"},"next":{"docname":"ref/forms/widgets","title":"部件","url":"/zh-hans/5.0/ref/forms/widgets/"},"formats":{"html":"/zh-hans/5.0/ref/forms/renderers/","markdown":"/zh-hans/5.0/ref/forms/renderers.md","json":"/zh-hans/5.0/ref/forms/renderers.json"},"source":"https://github.com/django/django/blob/stable/5.0.x/docs/ref/forms/renderers.txt","official":"https://docs.djangoproject.com/zh-hans/5.0/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"]}