萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> 程式語言綜合

Django TEMPLATES 設定完整指南:Django 1.8+ 新架構與遷移說明

Django 1.8 引入全新的 `TEMPLATES` 設定架構,取代舊版分散的 `TEMPLATE_*` 設定,支援多模板引擎、細粒度配置與更清晰的擴展機制。本文詳細解析新架構各選項、遷移對照表與進階用法。

TEMPLATES 設定結構

`TEMPLATES` 是一個列表,每個元素為字典,配置一個模板引擎實例:


TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [BASE_DIR / 'templates'],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
            'debug': True,
            'loaders': [
                'django.template.loaders.filesystem.Loader',
                'django.template.loaders.app_directories.Loader',
            ],
        },
    },
]

核心選項詳細說明

BACKEND (必要)

模板引擎實現類別的完整導入路徑:

  • `'django.template.backends.django.DjangoTemplates'` — Django 內建引擎 (DTL)
  • `'django.template.backends.jinja2.Jinja2'` — Jinja2 引擎
  • 自訂引擎:`'myproject.template_backends.CustomBackend'`

NAME (可選)

引擎別名,用於 `render(request, 'template.html', using='name')` 指定引擎。預設為 BACKEND 最後一段 (如 `DjangoTemplates`)。多引擎時**必須唯一**。

DIRS (列表,預設 `[]`)

模板檔案搜尋目錄列表,按順序優先級遞減。建議使用 `BASE_DIR / 'templates'` (Path 物件)。

APP_DIRS (布林,預設 `False`)

是否在各 `INSTALLED_APPS` 的 `templates/` 子目錄尋找模板。啟用後專案結構:


myapp/
  templates/
    myapp/
      detail.html  # 建議加上 app 名稱命名空間避免衝突

OPTIONS (字典,預設 `{}`)

傳遞給引擎的額外參數,不同引擎支援不同選項。DjangoTemplates 主要選項:

選項說明預設
context_processorsRequestContext 自動注入的處理器列表見下方
debug模板除錯模式 (錯誤頁面顯示程式碼片段)`DEBUG` 設定值
loaders模板載入器類別列表見下方
string_if_invalid無效變數顯示字串`''`
libraries自訂模板標籤庫註冊 `{name: 'path.to.module'}``{}`
builtins預設載入的標籤庫列表`[]`

內建 Context Processors (Django 1.8+ 路徑)


'django.template.context_processors.debug',
'django.template.context_processors.request',
'django.template.context_processors.i18n',
'django.template.context_processors.media',
'django.template.context_processors.static',
'django.template.context_processors.tz',
'django.contrib.auth.context_processors.auth',
'django.contrib.messages.context_processors.messages',

※ 舊版 `django.core.context_processors.*` 已棄用,遷移時需更新路徑。

內建 Loaders


'django.template.loaders.filesystem.Loader',      # 從 DIRS 載入
'django.template.loaders.app_directories.Loader', # 從 APP_DIRS 載入
# 'django.template.loaders.eggs.Loader',          # 已移除 (Django 1.9+)
# 'django.template.loaders.cached.Loader',        # 生產環境建議最外層包裹

生產環境建議:


'loaders': [
    ('django.template.loaders.cached.Loader', [
        'django.template.loaders.filesystem.Loader',
        'django.template.loaders.app_directories.Loader',
    ]),
],

舊版設定遷移對照表 (Django 1.8+ 棄用)

舊設定新設定位置備註
TEMPLATE_DEBUG`TEMPLATES[0]['OPTIONS']['debug']`
TEMPLATE_DIRS`TEMPLATES[0]['DIRS']`
TEMPLATE_LOADERS`TEMPLATES[0]['OPTIONS']['loaders']`
TEMPLATE_CONTEXT_PROCESSORS`TEMPLATES[0]['OPTIONS']['context_processors']`路徑已變更
TEMPLATE_STRING_IF_INVALID`TEMPLATES[0]['OPTIONS']['string_if_invalid']`

多引擎配置範例


TEMPLATES = [
    # Django DTL (主要)
    {
        'NAME': 'django',
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [BASE_DIR / 'templates'],
        'APP_DIRS': True,
        'OPTIONS': { ... },
    },
    # Jinja2 (特定頁面高效能渲染)
    {
        'NAME': 'jinja2',
        'BACKEND': 'django.template.backends.jinja2.Jinja2',
        'DIRS': [BASE_DIR / 'jinja2_templates'],
        'APP_DIRS': True,
        'OPTIONS': {
            'environment': 'myproject.jinja2.environment',
        },
    },
]

# 使用指定引擎渲染
from django.template.loader import render_to_string
html = render_to_string('email.html', context, using='jinja2')

自訂模板標籤與過濾器


# myapp/templatetags/my_tags.py
from django import template
register = template.Library()

@register.filter
def multiply(value, arg):
    return value * arg

@register.simple_tag
def current_time(format_string):
    from django.utils.timezone import now
    return now().strftime(format_string)

# OPTIONS 中註冊
'OPTIONS': {
    'libraries': {
        'my_tags': 'myapp.templatetags.my_tags',
    },
    'builtins': ['myapp.templatetags.my_tags'],  # 全域可用無需 {% load %}
}

最佳實踐

  • **專案層級 `templates/`** 放置基礎模板 (base.html, layout.html)。
  • **App 層級 `templates/app_name/`** 放置該 app 專用模板,避免命名衝突。
  • 生產環境**啟用 `cached.Loader`**,大幅減少模板編譯開銷。
  • 避免在模板中進行複雜邏輯,移至 View 或自訂 Template Tag。
  • 使用 `{% load %}` 明確載入標籤庫,提高可讀性 (除非在 `builtins` 註冊)。
copyright © 萬盛學電腦網 all rights reserved