變數和查詢¶

變數名稱必須包含任何字母 (A-Z)、任何數字 (0-9)、底線（但它們不得以底線開頭）或點號。

點號在樣板呈現中具有特殊含義。變數名稱中的點號表示查詢。具體而言，當樣板系統在變數名稱中遇到點號時，它會依此順序嘗試以下查詢：

• 字典查詢。範例：foo["bar"]

• 屬性查詢。範例：foo.bar

• 清單索引查詢。範例：foo[bar]

請注意，如果樣板 Context 中存在變數 “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
  

• 有時，您可能因為其他原因想要關閉此功能，並告知範本系統無論如何都不要呼叫變數。若要這麼做，請在可呼叫變數上設定一個 do_not_call_in_templates 屬性，值為 True。這樣範本系統就會像對待不可呼叫的變數一樣（例如，讓您可以存取該可呼叫變數的屬性）。

如何處理無效變數¶

一般而言，如果變數不存在，範本系統會插入引擎的 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)[原始碼]¶

Django 提供了一個特殊的 Context 類別，django.template.RequestContext，其行為與一般的 django.template.Context 略有不同。第一個不同之處在於它將 HttpRequest 作為其第一個參數。例如：

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

第二個不同之處在於，它會根據引擎的 context_processors 設定選項自動填充 context 一些變數。

context_processors 選項是一個可呼叫物件的列表（稱為 **context processors**），這些物件會將請求物件作為其參數，並傳回一個字典，其中的項目會合併到 context 中。在預設產生的設定檔中，預設的 template engine 包含以下 context processors：

[
    "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'。這是一個與安全性相關的 context processor，admin 和其他 contrib 應用程式需要用到它，並且為了避免意外的錯誤設定，它被刻意地硬編碼在其中，無法在 context_processors 選項中關閉。

每個 processor 都會依序套用。這表示如果一個 processor 將變數新增到 context 中，而第二個 processor 新增了具有相同名稱的變數，則第二個 processor 會覆寫第一個。預設的 processors 解釋如下。

from django.template import RequestContext

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

此外，您可以使用可選的第三個位置參數 processors，為 RequestContext 提供額外的 processor 列表。在這個範例中，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))

內建的 template context processors¶

以下是每個內建 processors 的功能：

撰寫您自己的內容處理器¶

內容處理器有一個簡單的介面：它是一個 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",
        ],
    },
]

您的模板可以放在您想要的任何位置，只要目錄和模板可由網頁伺服器讀取即可。它們可以有任何您想要的擴充名稱，例如 .html 或 .txt，或者它們可以完全沒有擴充名稱。

請注意，即使在 Windows 上，這些路徑也應使用 Unix 風格的正斜線。

載入器類型¶

預設情況下，Django 使用基於檔案系統的模板載入器，但 Django 也隨附了一些其他模板載入器，這些載入器知道如何從其他來源載入模板。

其中一些其他載入器預設為停用，但您可以透過將 'loaders' 選項新增至 TEMPLATES 設定中的 DjangoTemplates 後端，或將 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 管理介面，您可能會選擇使用您自己的 myproject.polls 中的 admin/base_site.html 覆寫來自 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[原始碼]¶

從給定的來源（例如檔案系統或資料庫）載入樣板。

get_template_sources(template_name)[原始碼]¶

一個方法，它接受一個 template_name 並為每個可能的來源產生 Origin 實例。

例如，檔案系統載入器可能會收到 'index.html' 作為 template_name 引數。此方法會為載入器所檢視的每個樣板目錄中出現的 index.html 的完整路徑產生來源。

此方法不需要驗證樣板是否存在於給定的路徑，但應確保路徑有效。例如，檔案系統載入器會確保路徑位於有效的樣板目錄下。

get_contents(origin)¶

返回給定 Origin 實例的樣板內容。

這是檔案系統載入器從檔案系統讀取內容，或資料庫載入器從資料庫讀取內容的地方。如果不存在相符的樣板，則應引發 TemplateDoesNotExist 錯誤。

get_template(template_name, skip=None)[原始碼]¶

透過迴圈執行 get_template_sources() 的結果並呼叫 get_contents()，返回給定 template_name 的 Template 物件。這會返回第一個相符的樣板。如果找不到樣板，則會引發 TemplateDoesNotExist。

選用的 skip 引數是在擴充樣板時要忽略的來源清單。這允許樣板擴充相同名稱的其他樣板。它也用於避免遞迴錯誤。

一般來說，為自訂樣板載入器定義 get_template_sources() 和 get_contents() 就足夠了。get_template() 通常不需要覆寫。