Django 1.8 引入全新的 `TEMPLATES` 設定架構,取代舊版分散的 `TEMPLATE_*` 設定,支援多模板引擎、細粒度配置與更清晰的擴展機制。本文詳細解析新架構各選項、遷移對照表與進階用法。
`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',
],
},
},
]
模板引擎實現類別的完整導入路徑:
引擎別名,用於 `render(request, 'template.html', using='name')` 指定引擎。預設為 BACKEND 最後一段 (如 `DjangoTemplates`)。多引擎時**必須唯一**。
模板檔案搜尋目錄列表,按順序優先級遞減。建議使用 `BASE_DIR / 'templates'` (Path 物件)。
是否在各 `INSTALLED_APPS` 的 `templates/` 子目錄尋找模板。啟用後專案結構:
myapp/
templates/
myapp/
detail.html # 建議加上 app 名稱命名空間避免衝突
傳遞給引擎的額外參數,不同引擎支援不同選項。DjangoTemplates 主要選項:
| 選項 | 說明 | 預設 |
|---|---|---|
context_processors | RequestContext 自動注入的處理器列表 | 見下方 |
debug | 模板除錯模式 (錯誤頁面顯示程式碼片段) | `DEBUG` 設定值 |
loaders | 模板載入器類別列表 | 見下方 |
string_if_invalid | 無效變數顯示字串 | `''` |
libraries | 自訂模板標籤庫註冊 `{name: 'path.to.module'}` | `{}` |
builtins | 預設載入的標籤庫列表 | `[]` |
'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.*` 已棄用,遷移時需更新路徑。
'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',
]),
],
| 舊設定 | 新設定位置 | 備註 |
|---|---|---|
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 %}
}