{"title":"表单渲染 API","version":"3.1","locale":"zh-hans","docname":"ref/forms/renderers","url":"/zh-hans/3.1/ref/forms/renderers/","canonical":"https://djangodocs.dev/zh-hans/3.1/ref/forms/renderers/","summary":"Django 的表单部件是使用 Django 的模板引擎系统渲染的。表单渲染过程可以在几个层次上进行定制：部件可以指定自定义模板名称、表单和部件可以指定自定义渲染器类、组件…","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/3.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/3.1/ref/settings/#std-setting-FORM_RENDERER\"><code class=\"xref std std-setting docutils literal notranslate\">FORM_RENDERER</code></a> 配置来指定自定义渲染器。它的默认值是 <code class=\"docutils literal notranslate\">'</code><a class=\"reference internal\" href=\"#django.forms.renderers.DjangoTemplates\" title=\"django.forms.renderers.DjangoTemplates\"><code class=\"xref py py-class docutils literal notranslate\">django.forms.renderers.DjangoTemplates</code></a><code class=\"docutils literal notranslate\">'</code>。</p>\n<p>你也可以通过设置 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/forms/api/#django.forms.Form.default_renderer\" title=\"django.forms.Form.default_renderer\"><code class=\"xref py py-attr docutils literal notranslate\">Form.default_renderer</code></a> 属性或使用 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/forms/widgets/#django.forms.Widget.render\" title=\"django.forms.Widget.render\"><code class=\"xref py py-meth docutils literal notranslate\">Widget.render()</code></a> 的 <code class=\"docutils literal notranslate\">renderer</code> 参数来提供一个自定义的渲染器。</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\">render(template_name, context, request=None)</code> 方法。它应该返回一个已渲染的模板（作为一个字符串）或引发 <a class=\"reference internal\" href=\"/zh-hans/3.1/topics/templates/#django.template.TemplateDoesNotExist\" title=\"django.template.TemplateDoesNotExist\"><code class=\"xref py py-exc docutils literal notranslate\">TemplateDoesNotExist</code></a>。</p>\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\">DjangoTemplates</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\">class</span> </em><span class=\"sig-name descname\">DjangoTemplates</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/3.1/topics/templates/#django.template.backends.django.DjangoTemplates\" title=\"django.template.backends.django.DjangoTemplates\"><code class=\"xref py py-class docutils literal notranslate\">DjangoTemplates</code></a> 引擎（与你在 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/settings/#std-setting-TEMPLATES\"><code class=\"xref std std-setting docutils literal notranslate\">TEMPLATES</code></a> 配置中设置的内容无关）。它首先从 <code class=\"docutils literal notranslate\">django/forms/templates</code> 内置的表单模板目录中加载模板，然后使用 <a class=\"reference internal\" href=\"/zh-hans/3.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\">app_directories</code></a> 加载器从已安装的应用的模板目录中加载模板。</p>\n<p>如果你想用你的 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/settings/#std-setting-TEMPLATES\"><code class=\"xref std std-setting docutils literal notranslate\">TEMPLATES</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\">TemplatesSetting</code></a> 渲染器。</p>\n</section>\n<section id=\"jinja2\">\n<h3><code class=\"docutils literal notranslate\">Jinja2</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\">class</span> </em><span class=\"sig-name descname\">Jinja2</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\">DjangoTemplates</code></a> 渲染器一样，只是它使用了 <a class=\"reference internal\" href=\"/zh-hans/3.1/topics/templates/#django.template.backends.jinja2.Jinja2\" title=\"django.template.backends.jinja2.Jinja2\"><code class=\"xref py py-class docutils literal notranslate\">Jinja2</code></a> 后台。内置部件的模板位于 <code class=\"docutils literal notranslate\">django/forms/jinja2</code>，安装的应用可以在 <code class=\"docutils literal notranslate\">jinja2</code> 目录下提供模板。</p>\n<p>要使用这个后端，你项目中的所有部件和它的第三方应用程序必须有 Jinja2 模板。除非你提供自己的 Jinja2 模板给没有模板的部件，否则你不能使用这个渲染器。例如， <a class=\"reference internal\" href=\"/zh-hans/3.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\">django.contrib.admin</code></a> 由于使用了 Django 模板标签，所以没有为其部件提供 Jinja2 模板。</p>\n</section>\n<section id=\"templatessetting\">\n<h3><code class=\"docutils literal notranslate\">TemplatesSetting</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\">class</span> </em><span class=\"sig-name descname\">TemplatesSetting</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/3.1/topics/templates/#django.template.loader.get_template\" title=\"django.template.loader.get_template\"><code class=\"xref py py-func docutils literal notranslate\">get_template()</code></a> 根据 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/settings/#std-setting-TEMPLATES\"><code class=\"xref std std-setting docutils literal notranslate\">TEMPLATES</code></a> 配置中设置的内容来查找部件模板。</p>\n<p>使用这个渲染器和内置的部件模板有以下两种方式：</p>\n<ul>\n<li><p><code class=\"docutils literal notranslate\">'django.forms'</code> 在 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/settings/#std-setting-INSTALLED_APPS\"><code class=\"xref std std-setting docutils literal notranslate\">INSTALLED_APPS</code></a> 和至少一个引擎有 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/settings/#std-setting-TEMPLATES-APP_DIRS\"><code class=\"xref std std-setting docutils literal notranslate\">APP_DIRS=True</code></a>。</p></li>\n<li><p>在你的一个模板引擎的 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/settings/#std-setting-TEMPLATES-DIRS\"><code class=\"xref std std-setting docutils literal notranslate\">DIRS</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=\"nn\">django</span>\ndjango<span class=\"o\">.</span>__path__<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-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/3.1/ref/forms/widgets/#django.forms.Widget.get_context\" title=\"django.forms.Widget.get_context\"><code class=\"xref py py-meth docutils literal notranslate\">Widget.get_context()</code></a> 中接收一个上下文。默认情况下，部件在上下文中只接收一个值，<code class=\"docutils literal notranslate\">widget</code>。这是一个字典，其中包含的值如：</p>\n<ul class=\"simple\">\n<li><p><code class=\"docutils literal notranslate\">name</code></p></li>\n<li><p><code class=\"docutils literal notranslate\">value</code></p></li>\n<li><p><code class=\"docutils literal notranslate\">attrs</code></p></li>\n<li><p><code class=\"docutils literal notranslate\">is_hidden</code></p></li>\n<li><p><code class=\"docutils literal notranslate\">template_name</code></p></li>\n</ul>\n<p>有些部件会给上下文添加更多信息。例如，所有子类 <code class=\"docutils literal notranslate\">Input</code> 定义了 <code class=\"docutils literal notranslate\">widget['type']</code> 和 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/forms/widgets/#django.forms.MultiWidget\" title=\"django.forms.MultiWidget\"><code class=\"xref py py-class docutils literal notranslate\">MultiWidget</code></a> 定义了 <code class=\"docutils literal notranslate\">widget['subwidgets']</code> 用于循环。</p>\n</section>\n<section id=\"overriding-built-in-widget-templates\">\n<span id=\"id2\"></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\">template_name</code> 属性，其值如 <code class=\"docutils literal notranslate\">input.html</code>。内建的部件模板存储在 <code class=\"docutils literal notranslate\">django/forms/widgets</code> 路径中，你可以为 <code class=\"docutils literal notranslate\">input.html</code> 提供一个自定义模板。你可以通过定义 <code class=\"docutils literal notranslate\">django/forms/widgets/input.html</code> 来为 <code class=\"docutils literal notranslate\">input.html</code> 提供一个自定义模板，例如。参见 <a class=\"reference internal\" href=\"/zh-hans/3.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\">TemplatesSetting</code></a> 渲染器。然后覆盖部件模板的工作原理 <a class=\"reference internal\" href=\"/zh-hans/3.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-widget-templates","children":[]},{"title":"覆盖内置部件模板","anchor":"overriding-built-in-widget-templates","children":[]}],"breadcrumbs":[{"docname":"ref/index","title":"API 参考","url":"/zh-hans/3.1/ref/"},{"docname":"ref/forms/index","title":"表单","url":"/zh-hans/3.1/ref/forms/"}],"prev":{"docname":"ref/forms/formsets","title":"表单集函数","url":"/zh-hans/3.1/ref/forms/formsets/"},"next":{"docname":"ref/forms/widgets","title":"部件","url":"/zh-hans/3.1/ref/forms/widgets/"},"formats":{"html":"/zh-hans/3.1/ref/forms/renderers/","markdown":"/zh-hans/3.1/ref/forms/renderers.md","json":"/zh-hans/3.1/ref/forms/renderers.json"},"source":"https://github.com/django/django/blob/stable/3.1.x/docs/ref/forms/renderers.txt","official":"https://docs.djangoproject.com/zh-hans/3.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","pt-br","ko","es","el","pl"]}