变量和查找¶

变量名必须由任何字母（A-Z）、任何数字（0-9）、下划线（但不能以下划线开头）或点组成。

点在模板渲染中具有特殊含义。变量名中的点表示**查找**。具体来说，当模板系统在变量名中遇到点时，它会按以下顺序尝试以下查找：

• 字典查找。示例：foo["bar"]

• 属性查找。示例：foo.bar

• 列表索引查找。示例：foo[bar]

请注意，如果模板表达式（如{{ foo.bar }}）中存在“bar”，它将被解释为文字字符串，而不是使用变量“bar”的值（如果模板上下文中存在该变量）。

模板系统使用第一个有效的查找类型。它是短路逻辑。以下是一些示例。

>>> from django.template import Context, Template
>>> t = Template("My name is {{ person.first_name }}.")
>>> d = {"person": {"first_name": "Joe", "last_name": "Johnson"}}
>>> t.render(Context(d))
"My name is Joe."

>>> class PersonClass:
...     pass
...
>>> p = PersonClass()
>>> p.first_name = "Ron"
>>> p.last_name = "Nasty"
>>> t.render(Context({"person": p}))
"My name is Ron."

>>> t = Template("The first stooge in the list is {{ stooges.0 }}.")
>>> c = Context({"stooges": ["Larry", "Curly", "Moe"]})
>>> t.render(c)
"The first stooge in the list is Larry."

如果变量的任何部分是可调用的，模板系统将尝试调用它。示例：

>>> class PersonClass2:
...     def name(self):
...         return "Samantha"
...
>>> t = Template("My name is {{ person.name }}.")
>>> t.render(Context({"person": PersonClass2}))
"My name is Samantha."

可调用变量比只需要直接查找的变量略微复杂一些。以下是一些需要记住的事项：

• 如果调用的变量引发异常，则将传播该异常，除非该异常具有一个名为silent_variable_failure的属性，其值为True。如果异常确实具有一个名为silent_variable_failure的属性，其值为True，则变量将呈现为引擎的string_if_invalid配置选项的值（默认为空字符串）。示例：

  >>> t = Template("My name is {{ person.first_name }}.")
  >>> class PersonClass3:
  ...     def first_name(self):
  ...         raise AssertionError("foo")
  ...
  >>> p = PersonClass3()
  >>> t.render(Context({"person": p}))
  Traceback (most recent call last):
  ...
  AssertionError: foo
  
  >>> class SilentAssertionError(Exception):
  ...     silent_variable_failure = True
  ...
  >>> class PersonClass4:
  ...     def first_name(self):
  ...         raise SilentAssertionError
  ...
  >>> p = PersonClass4()
  >>> t.render(Context({"person": p}))
  "My name is ."
  

  请注意，django.core.exceptions.ObjectDoesNotExist（这是所有 Django 数据库 API DoesNotExist异常的基类）具有silent_variable_failure = True。因此，如果您将 Django 模板与 Django 模型对象一起使用，任何DoesNotExist异常都将静默失败。

• 只有当变量没有必需参数时，才能调用它。否则，系统将返回引擎的string_if_invalid选项的值。

• 调用某些变量时可能会产生副作用，允许模板系统访问它们要么是愚蠢的，要么是一个安全漏洞。

  一个很好的例子是每个 Django 模型对象上的 delete() 方法。不应该允许模板系统执行类似的操作

  I will now delete this valuable data. {{ data.delete }}
  

  为了防止这种情况，请在可调用变量上设置 alters_data 属性。如果可调用变量设置了 alters_data=True，模板系统将不会调用该变量，而是将该变量无条件地替换为 string_if_invalid。Django 模型对象上动态生成的 delete() 和 save() 方法会自动获得 alters_data=True。示例

  def sensitive_function(self):
      self.database_record.delete()
  
  
  sensitive_function.alters_data = True
  

• 有时，您可能出于其他原因想要关闭此功能，并告诉模板系统无论如何都不要调用变量。为此，请在可调用对象上设置一个值为 True 的 do_not_call_in_templates 属性。然后，模板系统将表现得好像您的变量不可调用一样（例如，允许您访问可调用对象的属性）。

无效变量的处理方式¶

通常，如果变量不存在，模板系统将插入引擎的 string_if_invalid 配置选项的值，默认情况下该值为 ''（空字符串）。

仅当 string_if_invalid 设置为 ''（空字符串）时，应用于无效变量的过滤器才会被应用。如果 string_if_invalid 设置为任何其他值，则变量过滤器将被忽略。

对于 if、for 和 regroup 模板标签，此行为略有不同。如果为这些模板标签之一提供了无效变量，则该变量将被解释为 None。过滤器始终应用于这些模板标签中的无效变量。

如果 string_if_invalid 包含 '%s'，则格式标记将被无效变量的名称替换。

内置变量¶

每个上下文都包含 True、False 和 None。正如您所预期的那样，这些变量解析为相应的 Python 对象。

字符串文字的限制¶

Django 的模板语言无法转义其自身语法使用的字符。例如，如果您需要输出 {% 和 %} 等字符序列，则需要 templatetag 标签。

如果您想在模板过滤器或标签参数中包含这些序列，也会出现类似的问题。例如，在解析块标签时，Django 的模板解析器查找 {% 之后 %} 的第一次出现。这阻止了使用 "%}" 作为字符串文字。例如，以下表达式将引发 TemplateSyntaxError

{% include "template.html" tvar="Some string literal with %} in it." %}

{% with tvar="Some string literal with %} in it." %}{% endwith %}

在过滤器参数中使用保留序列也会触发相同的问题

{{ some.variable|default:"}}" }}

如果您需要使用包含这些序列的字符串，请将它们存储在模板变量中，或使用自定义模板标签或过滤器来解决此限制。

使用 RequestContext¶

class RequestContext(request, dict_=None, processors=None, use_l10n=None, use_tz=None, autoescape=True)[source]¶

Django 自带一个特殊的 Context 类，django.template.RequestContext，它的行为与普通的 django.template.Context 略有不同。第一个区别在于它接受一个 HttpRequest 对象作为它的第一个参数。例如：

c = RequestContext(
    request,
    {
        "foo": "bar",
    },
)

第二个区别在于它会根据引擎的 context_processors 配置选项自动填充上下文变量。

context_processors 选项是一个可调用对象的列表——称为**上下文处理器**——它们以请求对象作为参数，并返回一个字典，字典中的项目将被合并到上下文中。在默认生成的 settings 文件中，默认模板引擎包含以下上下文处理器：

[
    "django.template.context_processors.debug",
    "django.template.context_processors.request",
    "django.contrib.auth.context_processors.auth",
    "django.contrib.messages.context_processors.messages",
]

除此之外，RequestContext 始终启用 'django.template.context_processors.csrf'。这是一个与安全相关的上下文处理器，管理员和其他 contrib 应用都需要它；为避免意外的错误配置，它被故意硬编码，无法在 context_processors 选项中关闭。

每个处理器按顺序应用。这意味着，如果一个处理器向上下文中添加了一个变量，而第二个处理器又添加了一个同名变量，则第二个处理器将覆盖第一个处理器。

from django.template import RequestContext

request_context = RequestContext(request)
request_context.push({"my_name": "Adrian"})

此外，您可以使用可选的第三个位置参数 processors 为 RequestContext 提供附加处理器列表。在此示例中，RequestContext 实例获得一个 ip_address 变量：

from django.http import HttpResponse
from django.template import RequestContext, Template


def ip_address_processor(request):
    return {"ip_address": request.META["REMOTE_ADDR"]}


def client_ip_view(request):
    template = Template("{{ title }}: {{ ip_address }}")
    context = RequestContext(
        request,
        {
            "title": "Your IP Address",
        },
        [ip_address_processor],
    )
    return HttpResponse(template.render(context))

内置模板上下文处理器¶

以下是每个内置处理器的功能：

编写自己的上下文处理器¶

上下文处理器具有简单的接口：它是一个 Python 函数，它接受一个参数，一个HttpRequest对象，并返回一个将添加到模板上下文的字典。

例如，要将DEFAULT_FROM_EMAIL设置添加到每个上下文：

from django.conf import settings


def from_email(request):
    return {
        "DEFAULT_FROM_EMAIL": settings.DEFAULT_FROM_EMAIL,
    }

自定义上下文处理器可以位于代码库中的任何位置。Django 只关心您的自定义上下文处理器是否由TEMPLATES设置中的'context_processors'选项（或者如果您直接使用它，则使用Engine的context_processors参数）指向。

DIRS选项¶

通过在设置文件中的TEMPLATES设置中使用DIRS选项（或Engine的dirs参数）来告诉 Django 您的模板目录是什么。这应该设置为包含模板目录完整路径的字符串列表。

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [
            "/home/html/templates/lawrence.com",
            "/home/html/templates/default",
        ],
    },
]

您的模板可以放在任何您想要的地方，只要 Web 服务器可以读取这些目录和模板即可。它们可以使用任何您想要的扩展名，例如.html或.txt，或者根本没有扩展名。

请注意，即使在 Windows 上，这些路径也应使用 Unix 风格的正斜杠。

加载器类型¶

默认情况下，Django 使用基于文件系统的模板加载器，但 Django 还附带了一些其他模板加载器，它们知道如何从其他来源加载模板。

其中一些其他加载器默认情况下是禁用的，但是您可以通过在TEMPLATES设置中的DjangoTemplates后端添加'loaders'选项或将loaders参数传递给Engine来激活它们。loaders应该是一个字符串或元组列表，其中每个都代表一个模板加载器类。以下是 Django 附带的模板加载器：

django.template.loaders.filesystem.Loader

class filesystem.Loader¶

根据DIRS从文件系统加载模板。

此加载器默认启用。但是，在您将DIRS设置为非空列表之前，它不会找到任何模板。

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
    }
]

您还可以覆盖'DIRS'并为特定的文件系统加载器指定特定目录。

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "OPTIONS": {
            "loaders": [
                (
                    "django.template.loaders.filesystem.Loader",
                    [BASE_DIR / "templates"],
                ),
            ],
        },
    }
]

django.template.loaders.app_directories.Loader

class app_directories.Loader¶

从文件系统上的 Django 应用加载模板。对于INSTALLED_APPS中的每个应用，加载器都会查找templates子目录。如果目录存在，Django 会在其中查找模板。

这意味着您可以将模板与您的各个应用一起存储。这也有助于分发带有默认模板的 Django 应用。

例如，对于此设置：

INSTALLED_APPS = ["myproject.polls", "myproject.music"]

…那么get_template('foo.html')将按此顺序在这些目录中查找foo.html：

• /path/to/myproject/polls/templates/

• /path/to/myproject/music/templates/

…并将使用它首先找到的那个。

INSTALLED_APPS的顺序很重要！例如，如果您想自定义 Django 管理界面，您可以选择使用您自己的admin/base_site.html（位于myproject.polls中）来覆盖来自django.contrib.admin的标准admin/base_site.html模板。然后，您必须确保您的myproject.polls位于INSTALLED_APPS中django.contrib.admin的前面，否则将首先加载django.contrib.admin的模板，而您的模板将被忽略。

请注意，加载器在第一次运行时会执行优化：它会缓存哪些INSTALLED_APPS包具有templates子目录的列表。

您可以通过将APP_DIRS设置为True来启用此加载器。

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "APP_DIRS": True,
    }
]

django.template.loaders.cached.Loader

class cached.Loader¶

虽然 Django 模板系统非常快，但如果它需要在每次呈现模板时读取和编译模板，则此开销可能会累积。

您可以使用它应该包装的其他加载器列表来配置缓存的模板加载器。当第一次遇到未知模板时，将使用包装的加载器来定位它们。然后，缓存的加载器将编译后的Template存储在内存中。对于后续加载相同模板的请求，将返回缓存的Template实例。

如果未指定OPTIONS['loaders']，则会自动启用此加载器。

您可以使用类似这样的设置手动指定自定义模板加载器的模板缓存：

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "OPTIONS": {
            "loaders": [
                (
                    "django.template.loaders.cached.Loader",
                    [
                        "django.template.loaders.filesystem.Loader",
                        "django.template.loaders.app_directories.Loader",
                        "path.to.custom.Loader",
                    ],
                ),
            ],
        },
    }
]

注意

所有内置的 Django 模板标签都可以安全地与缓存加载器一起使用，但是如果您使用来自第三方包或自己编写的自定义模板标签，则应确保每个标签的Node实现是线程安全的。有关更多信息，请参见模板标签线程安全注意事项。

django.template.loaders.locmem.Loader

class locmem.Loader¶

从 Python 字典加载模板。这对于测试很有用。

此加载器将模板字典作为其第一个参数。

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "OPTIONS": {
            "loaders": [
                (
                    "django.template.loaders.locmem.Loader",
                    {
                        "index.html": "content here",
                    },
                ),
            ],
        },
    }
]

此加载器默认禁用。

Django 会按照'loaders'选项的顺序使用模板加载器。它会使用每个加载器，直到加载器找到匹配项。

加载器方法¶

class Loader[source]¶

从给定的源加载模板，例如文件系统或数据库。

get_template_sources(template_name)[source]¶

此方法接受一个template_name并为每个可能的源生成Origin实例。

例如，文件系统加载器可能会收到'index.html'作为template_name参数。此方法将为index.html在加载器查看的每个模板目录中出现的完整路径生成源。

此方法不需要验证模板是否存在于给定路径，但应确保路径有效。例如，文件系统加载器确保路径位于有效的模板目录下。

get_contents(origin)¶

给定一个Origin实例，返回模板的内容。

这就是文件系统加载器从文件系统读取内容的地方，或者数据库加载器从数据库读取内容的地方。如果找不到匹配的模板，则应引发TemplateDoesNotExist错误。

get_template(template_name, skip=None)[source]¶

通过循环遍历get_template_sources()的结果并调用get_contents()，为给定的template_name返回一个Template对象。这将返回第一个匹配的模板。如果找不到模板，则会引发TemplateDoesNotExist。

可选的skip参数是一个要忽略的源列表，用于扩展模板。这允许模板扩展相同名称的其他模板。它还用于避免递归错误。

通常，为自定义模板加载器定义get_template_sources()和get_contents()就足够了。get_template()通常不需要重写。