模板¶

组态¶

模板引擎使用 TEMPLATES 设置进行配置。这是一个配置列表，每个引擎一个。默认值为空。 startproject 命令生成的 settings.py 定义了一个更有用的值:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
            # ... some options here ...
        },
    },
]

BACKEND 是实现Django的模板后端API的模板引擎类的点分Python路径。内置后端是 django.template.backends.django.DjangoTemplates 和 django.template.backends.jinja2.Jinja2。

由于大多数引擎从文件加载模板，每个引擎的顶级配置包含两个常见设置：

• DIRS 定义了一个目录列表，引擎应该按照搜索顺序查找模板源文件。

• APP_DIRS 告诉引擎是否应该在已安装的应用程序中查找模板。每个后端定义应用程序中应存储模板的子目录的常规名称。

虽然不常见，但可以使用不同的选项配置同一后端的多个实例。在这种情况下，您应该为每个引擎定义唯一的 NAME。

OPTIONS 包含后端特定的设置。

用法¶

django.template.loader 模块定义了两个加载模板的函数。

get_template(template_name, using=None)[源代码]¶

此函数加载具有给定名称的模板，并返回 Template 对象。

返回值的确切类型取决于加载模板的后端。每个后端都有自己的 Template 类。

get_template() 按顺序尝试每个模板引擎，直到成功。如果找不到模板，它会引发 TemplateDoesNotExist。如果找到模板但包含无效的语法，则会引发 TemplateSyntaxError。

如何搜索和加载模板取决于每个引擎的后端和配置。

如果要限制搜索到特定模板引擎，请在 using 参数中传递引擎的 NAME。

select_template(template_name_list, using=None)[源代码]¶

select_template() 就像 get_template()，除了它需要一个模板名称列表。它按顺序尝试每个名称并返回存在的第一个模板。

如果加载模板失败，可能会引发 django.template 中定义的以下两个异常：

exception TemplateDoesNotExist(msg, tried=None, backend=None, chain=None)[源代码]¶

当无法找到模板时引发此异常。它接受以下可选参数，用于在调试页面上填充 模板postmortem：

backend

引发异常的模板后端实例。

tried

找到模板时尝试的源的列表。这被格式化为包含 (origin, status) 的元组的列表，其中 origin 是 原产地 对象，status 是具有未找到模板的原因的字符串。

chain

尝试加载模板时引发的中间 TemplateDoesNotExist 异常的列表。这由尝试从多个引擎加载给定模板的函数（例如 get_template()）使用。

New in Django 1.9:

添加了 backend，tried 和 chain 参数。

exception TemplateSyntaxError(msg)[源代码]¶

发现模板但包含错误时引发此异常。

由 get_template() 和 select_template() 返回的 Template 对象必须提供具有以下签名的 render() 方法：

Template.render(context=None, request=None)¶

使用给定的上下文呈现此模板。

如果提供 context，它必须是 dict。如果未提供，引擎将使用空上下文呈现模板。

如果提供 request，它必须是 HttpRequest。然后引擎必须在模板中提供它以及CSRF令牌。如何实现是由每个后端。

这里是一个搜索算法的例子。对于此示例，TEMPLATES 设置为:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [
            '/home/html/example.com',
            '/home/html/default',
        ],
    },
    {
        'BACKEND': 'django.template.backends.jinja2.Jinja2',
        'DIRS': [
            '/home/html/jinja2',
        ],
    },
]

如果你调用 get_template('story_detail.html')，这里是Django将寻找的文件，按顺序：

• /home/html/example.com/story_detail.html （'django' 发动机）

• /home/html/default/story_detail.html （'django' 发动机）

• /home/html/jinja2/story_detail.html （'jinja2' 发动机）

如果你调用 select_template(['story_253_detail.html', 'story_detail.html'])，这里是Django将寻找：

• /home/html/example.com/story_253_detail.html （'django' 发动机）

• /home/html/default/story_253_detail.html （'django' 发动机）

• /home/html/jinja2/story_253_detail.html （'jinja2' 发动机）

• /home/html/example.com/story_detail.html （'django' 发动机）

• /home/html/default/story_detail.html （'django' 发动机）

• /home/html/jinja2/story_detail.html （'jinja2' 发动机）

当Django找到一个存在的模板时，它停止查找。

在每个包含模板的目录内的子目录中组织模板是可能的，并且更好。约定是为每个Django应用程序创建一个子目录，根据需要在这些子目录中创建子目录。

这是为你自己的理智。将所有模板存储在单个目录的根级别中会产生混乱。

要加载子目录中的模板，只需使用斜杠即可:

get_template('news/story_detail.html')

使用与上述相同的 TEMPLATES 选项，将尝试加载以下模板：

• /home/html/example.com/news/story_detail.html （'django' 发动机）

• /home/html/default/news/story_detail.html （'django' 发动机）

• /home/html/jinja2/news/story_detail.html （'jinja2' 发动机）

此外，为了减少加载和呈现模板的重复性，Django提供了一个自动化过程的快捷函数。

render_to_string(template_name, context=None, request=None, using=None)[源代码]¶

render_to_string() 加载像 get_template() 的模板并立即调用其 render() 方法。它接受以下参数。

template_name

要加载和呈现的模板的名称。如果它是模板名称的列表，Django使用 select_template() 而不是 get_template() 来查找模板。

context

dict 用作模板的上下文进行渲染。

request

在模板的渲染过程中可用的可选 HttpRequest。

using

可选的模板引擎 NAME。模板的搜索将仅限于该引擎。

用法示例:

from django.template.loader import render_to_string
rendered = render_to_string('my_template.html', {'foo': 'bar'})

另请参阅调用 render_to_string() 的 render() 快捷方式，并将结果馈送到适合从视图返回的 HttpResponse 中。

最后，您可以直接使用配置的引擎：

engines¶

模板引擎在 django.template.engines 中可用:

from django.template import engines

django_engine = engines['django']
template = django_engine.from_string("Hello {{ name }}!")

查找键（在本例中是 'django'）是引擎的 NAME。

内置后端¶

class DjangoTemplates[源代码]¶

将 BACKEND 设置为 'django.template.backends.django.DjangoTemplates' 以配置Django模板引擎。

当 APP_DIRS 是 True 时，DjangoTemplates 引擎在已安装应用程序的 templates 子目录中查找模板。此通用名称保留用于向后兼容性。

DjangoTemplates 引擎接受以下 OPTIONS：

• 'autoescape'：一个布尔值，控制是否启用HTML自动转义。

  它默认为 True。

  警告

  如果您正在呈现非HTML模板，请将其设置为 False！

  New in Django 1.10:

  添加了 autoescape 选项。

• 'context_processors'：用于在使用请求呈现模板时用于填充上下文的可调用对象的点状Python路径列表。这些可调用包含一个请求对象作为它们的参数，并返回一个要合并到上下文中的项目的 dict。

  它默认为空列表。

  有关详细信息，请参阅 RequestContext。

• 'debug'：打开/关闭模板调试模式的布尔值。如果是 True，花哨错误页面将显示模板渲染期间引发的任何异常的详细报告。此报告包含模板的相关代码段，并突出显示相应的行。

  它默认为 DEBUG 设置的值。

• 'loaders'：模板加载器类的虚拟Python路径列表。每个 Loader 类都知道如何从特定源导入模板。可选地，可以使用元组而不是字符串。元组中的第一个项应该是 Loader 类名，并且在初始化期间将后续项传递给 Loader。

  默认值取决于 DIRS 和 APP_DIRS 的值。

  有关详细信息，请参阅 装载机类型。

• 'string_if_invalid'：模板系统应用于无效（例如拼写错误）变量的输出，作为字符串。

  它默认为空字符串。

  有关详细信息，请参阅 如何处理无效变量。

• 'file_charset'：用于读取磁盘上的模板文件的字符集。

  它默认为 FILE_CHARSET 的值。

• 'libraries'：用于向模板引擎注册的模板标记模块的标签字典和点状Python路径。这可以用于添加新库或为现有库提供备用标签。例如:

  OPTIONS={
      'libraries': {
          'myapp_tags': 'path.to.myapp.tags',
          'admin.urls': 'django.contrib.admin.templatetags.admin_urls',
      },
  }
  

  可以通过将相应的字典键传递到 {% load %} 标记来加载库。

• 'builtins'：要添加到 内置 的模板标记模块的虚拟Python路径列表。例如:

  OPTIONS={
      'builtins': ['myapp.builtins'],
  }
  

  可以在不首先调用 {% load %} 标记的情况下使用来自内置库的标记和过滤器。

class Jinja2¶

需要安装 Jinja2：

$ pip install Jinja2

将 BACKEND 设置为 'django.template.backends.jinja2.Jinja2' 以配置 Jinja2 引擎。

当 APP_DIRS 是 True 时，Jinja2 引擎在已安装应用程序的 jinja2 子目录中查找模板。

OPTIONS 中最重要的条目是 'environment'。这是一个虚线的Python路径到一个callable返回一个Jinja2环境。它默认为 'jinja2.Environment'。 Django调用该可调用项并传递其他选项作为关键字参数。此外，Django添加了不同于Jinja2的默认值几个选项：

• 'autoescape'：True

• 'loader'：为 DIRS 和 APP_DIRS 配置的加载程序

• 'auto_reload'：settings.DEBUG

• 'undefined'：DebugUndefined if settings.DEBUG else Undefined

有意将默认配置保持为最小。如果使用请求（例如，当使用 render() 时）呈现模板时，Jinja2 后端将全局变量 request，csrf_input 和 csrf_token 添加到上下文。除此之外，这个后端不创建一个Django风味的环境。它不知道Django上下文处理器，过滤器和标签。为了使用Django特定的API，您必须将它们配置到环境中。

例如，您可以使用此内容创建 myproject/jinja2.py:

from __future__ import absolute_import  # Python 2 only

from django.contrib.staticfiles.storage import staticfiles_storage
from django.urls import reverse

from jinja2 import Environment


def environment(**options):
    env = Environment(**options)
    env.globals.update({
        'static': staticfiles_storage.url,
        'url': reverse,
    })
    return env

并将 'environment' 选项设置为 'myproject.jinja2.environment'。

然后您可以在Jinja2模板中使用以下结构：

<img src="{{ static('path/to/company-logo.png') }}" alt="Company Logo">

<a href="{{ url('admin:index') }}">Administration</a>

标签和过滤器的概念存在于Django模板语言和Jinja2中，但它们的使用方式不同。由于Jinja2支持将模板中的参数传递给可调用对象，因此许多需要Django模板中的模板标签或过滤器的功能都可以通过调用Jinja2模板中的函数来实现，如上例所示。 Jinja2的全局命名空间不再需要模板上下文处理器。 Django模板语言没有Jinja2测试的等价物。

自定义后端¶

以下是如何实现自定义模板后端，以便使用其他模板系统。模板后端是继承 django.template.backends.base.BaseEngine 的类。它必须实现 get_template() 和可选的 from_string()。这里有一个虚构的 foobar 模板库的例子:

from django.template import TemplateDoesNotExist, TemplateSyntaxError
from django.template.backends.base import BaseEngine
from django.template.backends.utils import csrf_input_lazy, csrf_token_lazy

import foobar


class FooBar(BaseEngine):

    # Name of the subdirectory containing the templates for this engine
    # inside an installed application.
    app_dirname = 'foobar'

    def __init__(self, params):
        params = params.copy()
        options = params.pop('OPTIONS').copy()
        super(FooBar, self).__init__(params)

        self.engine = foobar.Engine(**options)

    def from_string(self, template_code):
        try:
          return Template(self.engine.from_string(template_code))
        except foobar.TemplateCompilationFailed as exc:
            raise TemplateSyntaxError(exc.args)

    def get_template(self, template_name):
        try:
            return Template(self.engine.get_template(template_name))
        except foobar.TemplateNotFound as exc:
            raise TemplateDoesNotExist(exc.args, backend=self)
        except foobar.TemplateCompilationFailed as exc:
            raise TemplateSyntaxError(exc.args)


class Template(object):

    def __init__(self, template):
        self.template = template

    def render(self, context=None, request=None):
        if context is None:
            context = {}
        if request is not None:
            context['request'] = request
            context['csrf_input'] = csrf_input_lazy(request)
            context['csrf_token'] = csrf_token_lazy(request)
        return self.template.render(context)

有关详细信息，请参阅 DEP 182。

定制引擎的调试集成¶

Django调试页面具有钩子，以在模板错误出现时提供详细信息。自定义模板引擎可以使用这些钩子来增强向用户显示的回溯信息。以下钩子可用：

模板postmortem¶

当 TemplateDoesNotExist 升起时，死后出现。它列出了在尝试查找给定模板时使用的模板引擎和加载器。例如，如果配置了两个Django引擎，则事后停止将显示为：

自定义引擎可以通过在提高 TemplateDoesNotExist 时传递 backend 和 tried 参数来填充事后死亡。在模板对象上使用事后预测 应指定原点 的后端。

上下文行信息¶

如果在模板解析或渲染期间发生错误，Django可以显示发生错误的行。例如：

自定义引擎可以通过在解析和呈现期间引发的异常上设置 template_debug 属性来填充此信息。此属性是具有以下值的 dict：

• 'name'：发生异常的模板的名称。

• 'message'：异常消息。

• 'source_lines'：发生异常的行前，后和行的行。这是为了上下文，所以它不应该包含超过20行左右。

• 'line'：发生异常的行号。

• 'before'：引发错误的令牌之前的错误行上的内容。

• 'during'：引发错误的令牌。

• 'after'：引发错误的令牌之后的错误行上的内容。

• 'total'：source_lines 中的行数。

• 'top'：source_lines 开始的行号。

• 'bottom'：source_lines 结束的行号。

给定上述模板错误，template_debug 将看起来像:

{
    'name': '/path/to/template.html',
    'message': "Invalid block tag: 'syntax'",
    'source_lines': [
        (1, 'some\n'),
        (2, 'lines\n'),
        (3, 'before\n'),
        (4, 'Hello {% syntax error %} {{ world }}\n'),
        (5, 'some\n'),
        (6, 'lines\n'),
        (7, 'after\n'),
        (8, ''),
    ],
    'line': 4,
    'before': 'Hello ',
    'during': '{% syntax error %}',
    'after': ' {{ world }}\n',
    'total': 9,
    'bottom': 9,
    'top': 1,
}

句法¶

Django模板只是一个文本文档或使用Django模板语言标记的Python字符串。一些构造由模板引擎识别和解释。主要的是变量和标签。

使用上下文呈现模板。 Rendering将变量替换为在上下文中查找的变量，并执行标签。一切都是按原样输出。

Django模板语言的语法涉及四个构造。

My first name is {{ first_name }}. My last name is {{ last_name }}.

My first name is John. My last name is Doe.

{{ my_dict.key }}
{{ my_object.attribute }}
{{ my_list.0 }}

{% csrf_token %}

{% cycle 'odd' 'even' %}

{% if user.is_authenticated %}Hello, {{ user.username }}.{% endif %}

{{ django|title }}

The Web Framework For Perfectionists With Deadlines

{{ my_date|date:"Y-m-d" }}

{# this won't be rendered #}

组件¶