【Python】Django模板语言 (DTL)

第四章：Django模板语言 (DTL) —— 框架驱动的设计典范

Django Template Language (DTL) 是 Django Web 框架内置的一套强大的模板系统。与 Jinja2 或 Mako 等通用模板引擎相比，DTL 的一个显著特点是它与 Django 框架的深度集成，并且其设计哲学中带有一种“有意限制模板逻辑”的倾向。这种设计旨在鼓励开发者将大部分业务逻辑保留在 Python视图 (Views) 和模型 (Models) 中，让模板专注于表现层。

4.1 DTL 概览：为表现而生，与框架共舞

Django 的创造者们认为，模板系统应该主要负责数据如何呈现，而不是如何产生或处理数据。因此，DTL 被设计为一种功能强大但又相对简单的语言，它刻意避免了在模板中执行任意 Python 代码的能力。

DTL 的核心设计原则与特性：

已关注表现 (Focus on Presentation)：

DTL 的主要目标是格式化和展示从视图传递过来的数据。它提供了丰富的工具来迭代数据、有条件地显示内容以及格式化输出，但避免了复杂的计算或数据操作。

与 Django 深度集成 (Tight Integration with Django)：

自动上下文处理器 (Context Processors)：Django 允许定义上下文处理器，这些处理器会自动向所有模板的上下文中添加特定的变量（例如，用户信息 request.user、站点设置等），无需在每个视图中手动添加。
视图与模板的清晰分离: Django 的 MTV (Model-Template-View) 架构鼓励将数据处理逻辑放在视图中，然后视图选择一个模板并传递上下文给它进行渲染。
表单处理: Django 的表单系统与 DTL 配合良好，可以轻松在模板中渲染表单字段、错误信息等。
国际化与本地化: DTL 内置了对国际化 (i18n) 和本地化 (l10n) 的强大支持，包括翻译标签和本地化过滤器。
静态文件管理: DTL 提供了 {% static %} 标签来方便地引用静态文件（CSS, JavaScript, 图片），并能与 Django 的静态文件处理器（如 ManifestStaticFilesStorage）协同工作，实现缓存清除等高级功能。
URL 反向解析: {% url %} 标签允许在模板中通过 URL 名称动态生成 URL，避免了硬编码 URL，使得 URL 结构变更时更易于维护。

有意限制的逻辑能力 (Intentionally Limited Logic)：

禁止执行任意 Python 代码: 与 Mako 不同，你不能在 DTL 中直接嵌入任意的 Python 代码块。所有逻辑都必须通过预定义的标签和过滤器来实现。
有限的表达式: DTL 中的变量访问和表达式能力比纯 Python 或 Jinja2 更受限制。例如，不能直接在模板中进行复杂的算术运算或调用带任意参数的方法（除非通过自定义标签或过滤器）。
鼓励自定义扩展: 如果需要更复杂的逻辑，Django 鼓励开发者创建自定义模板标签 (template tags) 和过滤器 (template filters) 来封装这些逻辑，而不是在模板中直接编写。

安全性 (Security)：

默认自动 HTML 转义: DTL 默认会对所有通过 {
{ ... }} 输出的变量进行 HTML 转义，以防止 XSS 攻击。可以通过 |safe 过滤器或 {% autoescape off %} 块来覆盖此行为，但需要非常谨慎。
由于不能执行任意 Python，也从源头上减少了模板层面引入安全漏洞的风险。

可读性与易用性 (Readability and Ease of Use)：

DTL 的语法设计得相对简单直观，即使对于非 Python 背景的前端开发者或设计师也比较容易上手。
标签和过滤器的名称通常具有描述性。

可扩展性 (Extensibility)：

开发者可以创建自定义的简单标签、赋值标签、包含标签以及过滤器，以满足特定项目的需求。

4.2 DTL 的基本配置与使用流程 (在 Django 项目中)

在标准的 Django 项目中，DTL 的配置和使用是框架自动处理的。开发者主要关心的是如何组织模板文件、如何在视图中加载和渲染模板，以及如何编写模板本身。

4.2.1 模板加载器 (Template Loaders) 与 TEMPLATES 设置

Django 通过 settings.py 文件中的 TEMPLATES 配置项来管理模板引擎和加载。一个典型的 TEMPLATES 设置如下：

# settings.py

TEMPLATES = [
    {
            
        'BACKEND': 'django.template.backends.django.DjangoTemplates', # 指定使用DTL后端
        'DIRS': [
            os.path.join(BASE_DIR, 'templates'), # 项目级模板目录 (项目根目录下的 'templates' 文件夹)
            # '/path/to/another/templates/directory', # 可以添加其他项目外的模板目录
        ],
        'APP_DIRS': True, # 允许Django在每个已安装应用的 'templates' 子目录中查找模板
        'OPTIONS': {
            
            'context_processors': [ # 上下文处理器列表
                'django.template.context_processors.debug', # 提供 DEBUG 和 sql_queries 变量
                'django.template.context_processors.request', # 提供 request 对象 (HttpRequest)
                'django.contrib.auth.context_processors.auth', # 提供 user 对象 (当前登录用户) 和 perms 对象 (权限)
                'django.contrib.messages.context_processors.messages', # 提供 messages (来自 Django messages 框架)
                # 自定义上下文处理器可以加在这里
                # 'myapp.context_processors.my_custom_processor',
            ],
            'builtins': [ # 可以添加自定义的内建标签和过滤器模块
                # 'myapp.templatetags.custom_tags_and_filters',
            ],
            'debug': True, # 开发时设为True，提供更详细的错误信息。生产环境应为False。
            # 'loaders': [ ... ], # 可以自定义模板加载器的顺序或类型，默认顺序通常够用
            # 'string_if_invalid': 'INVALID {
            { %s }}', # 当变量无效时显示的字符串 (生产环境用)
        },
    },
    # 如果需要，可以配置其他模板引擎，例如 Jinja2
    # {
            
    #     'BACKEND': 'django.template.backends.jinja2.Jinja2',
    #     'DIRS': [os.path.join(BASE_DIR, 'jinja2_templates')],
    #     'APP_DIRS': True,
    #     'OPTIONS': {
            
    #         'environment': 'myproject.jinja2.environment', # 指向一个返回Jinja2 Environment实例的函数
    #     }
    # },
]

代码解释 (TEMPLATES 设置):

'BACKEND': 'django.template.backends.django.DjangoTemplates': 明确指定使用 Django 内置的模板引擎 (DTL)。
'DIRS': [os.path.join(BASE_DIR, 'templates')]:

这是一个列表，定义了 Django 在查找模板文件时会搜索的项目级目录。
BASE_DIR 通常是 Django 项目的根目录。
这意味着 Django 会在你的项目根目录下的 templates 文件夹中寻找模板。例如，如果你尝试加载 index.html，Django 会查找 your_project_root/templates/index.html。
你可以添加多个路径到这个列表中。

'APP_DIRS': True:

如果设置为 True，Django 还会自动在每个已安装的应用程序（在 INSTALLED_APPS 中列出的应用）的目录内查找名为 templates 的子目录。
例如，如果你的项目有一个名为 blog 的应用，并且 APP_DIRS 为 True，那么 Django 会在 your_project_root/blog/templates/ 目录中查找模板。
命名空间化模板: 为了避免不同应用间的模板文件名冲突，最佳实践是在应用的 templates 目录下再创建一个以应用名命名的子目录，例如 blog/templates/blog/post_list.html。在模板中引用时，使用 blog/post_list.html。

'OPTIONS': 一个包含特定于该模板后端选项的字典。

'context_processors':

一个非常重要的列表，定义了上下文处理器。
上下文处理器是一些 Python 函数，它们接收当前的 HttpRequest 对象作为参数，并返回一个字典。这个字典中的键值对会被自动添加到传递给所有模板的渲染上下文中。
django.template.context_processors.debug: 如果 settings.DEBUG 为 True，它会添加 debug=True 和 sql_queries (一个包含执行过的SQL查询列表，用于调试) 到上下文中。
django.template.context_processors.request: 将当前的 HttpRequest 对象作为 request 变量添加到上下文中。这使得你可以在模板中访问请求的属性，例如 {
{ request.user }}、{
{ request.path }}、{
{ request.GET.query }} 等。
django.contrib.auth.context_processors.auth: 如果 django.contrib.auth 应用已安装，它会添加当前登录的用户对象（通常是 User 模型的实例）作为 user 变量，以及一个 PermWrapper 对象作为 perms 变量（用于权限检查 {% if perms.app_label.can_do_something %}）。
django.contrib.messages.context_processors.messages: 如果 django.contrib.messages 应用已安装，它会添加一个包含待显示消息的列表（通过 django.contrib.messages 框架添加的消息）作为 messages 变量。

'builtins':

一个 Python 模块路径的列表，这些模块中定义的自定义模板标签和过滤器会自动注册为内建的，无需在每个模板中使用 {% load ... %} 标签来加载它们。
通常用于加载项目级别或广泛使用的自定义标签/过滤器。

'debug':

布尔值。如果为 True (通常与 settings.DEBUG 同步)，当模板渲染发生错误时，Django 会显示一个详细的调试页面，包含错误信息、模板源代码片段和上下文数据。
生产环境中必须设置为 False，以避免泄露敏感信息。

'loaders': (可选)

允许你显式定义模板加载器的列表和顺序。默认情况下，Django 使用一组标准的加载器，包括文件系统加载器 (django.template.loaders.filesystem.Loader) 和应用目录加载器 (django.template.loaders.app_directories.Loader)。
只有在需要非常特殊的加载行为时（例如，从数据库加载模板，或者有自定义的加载器优先级）才需要修改此项。
默认顺序是先查找 filesystem.Loader (DIRS 中指定的路径)，然后查找 app_directories.Loader (APP_DIRS=True 时)。

'string_if_invalid': (可选)

一个字符串，用于在模板中遇到无效（未定义或访问出错）的变量时显示。例如，'INVALID {
{ %s }}'，其中 %s 会被替换为无效的变量名。
这主要用于生产环境，以避免因小的数据问题导致页面部分内容不显示，而是显示一个明确的标记。在开发环境中，通常希望看到详细的错误或让 debug=True 来处理。
默认情况下，无效变量在模板中通常不会输出任何内容 (类似于空字符串)。

4.2.2 在 Django 视图中渲染模板

Django 视图函数 (或基于类的视图的方法) 负责处理用户请求、准备数据，并选择一个模板来渲染这些数据，最终返回一个 HttpResponse。

有几种常见的方式来渲染模板：

使用 django.shortcuts.render() (最常用)：

这是一个便捷函数，它封装了加载模板、创建 Context、渲染模板和返回 HttpResponse 的整个过程。
语法: render(request, template_name, context=None, content_type=None, status=None, using=None)

request: 当前的 HttpRequest 对象。
template_name: 字符串，要加载的模板文件的路径（相对于模板目录）。
context: (可选) 一个字典，包含要传递给模板的上下文数据。
content_type, status, using: 其他 HttpResponse 的可选参数。

示例 (在 views.py 中):

# myapp/views.py
from django.shortcuts import render # 导入render快捷函数
from django.http import HttpRequest, HttpResponse # 导入HttpRequest和HttpResponse
import datetime # 导入datetime模块

# 假设有一个简单的模型
# class Article(models.Model):
#     title = models.CharField(max_length=200)
#     content = models.TextField()
#     pub_date = models.DateTimeField(auto_now_add=True)

def article_list_view(request: HttpRequest) -> HttpResponse: # 定义文章列表视图函数
    """视图函数，用于显示文章列表。"""
    # 模拟从数据库获取文章数据
    articles_data = [ # 文章数据列表
        {
                'id': 1, 'title': 'Django for Beginners', 'author': 'Alice', 'pub_date': datetime.date(2023, 1, 15)}, # 文章1
        {
                'id': 2, 'title': 'Advanced Django Patterns', 'author': 'Bob', 'pub_date': datetime.date(2023, 3, 22)}, # 文章2
        {
                'id': 3, 'title': 'Understanding DTL', 'author': 'Charlie', 'pub_date': datetime.date(2023, 5, 10)} # 文章3
    ] # 文章数据列表定义结束

    current_time = datetime.datetime.now() # 获取当前时间

    context = {
                 # 定义传递给模板的上下文
        'page_heading': 'Our Latest Articles', # 页面标题
        'articles': articles_data, # 文章列表数据
        'current_server_time': current_time, # 当前服务器时间
        'display_ad': True # 是否显示广告的标志
    } # 上下文定义结束

    # 渲染 'myapp/article_list.html' 模板，并传入上下文
    # Django 会根据 TEMPLATES 设置自动查找这个模板文件
    # (例如，在 myapp/templates/myapp/article_list.html 或 project/templates/myapp/article_list.html)
    return render(request, 'myapp/article_list.html', context) # 使用render函数渲染模板并返回HttpResponse

def simple_greeting_view(request: HttpRequest) -> HttpResponse: # 定义简单的问候视图函数
    """一个非常简单的视图，只传递少量数据。"""
    username = request.user.username if request.user.is_authenticated else "Guest" # 获取用户名，如果未登录则为Guest
    context = {
                 # 定义模板上下文
        'greet_name': username, # 问候名称
        'time_of_day': "afternoon" if 12 <= datetime.datetime.now().hour < 18 else "morning/evening" # 根据时间判断时段
    } # 上下文定义结束
    return render(request, 'myapp/greeting.html', context) # 渲染greeting.html模板

对应的模板文件示例 (myapp/templates/myapp/article_list.html):

{# myapp/templates/myapp/article_list.html #}
{% extends "base_generic.html" %} {# 假设有一个基础模板 #}

{% load static %} {# 加载static标签库，用于引用静态文件 #}

{% block title %}Article List{% endblock %} {# 覆盖基础模板的title块 #}

{% block head_extra %} {# 假设基础模板有这个块用于添加额外的head内容 #}
    <link rel="stylesheet" href="{% static 'myapp/css/article_styles.css' %}"> {# 引用应用的CSS文件 #}
{% endblock %}

{% block content %} {# 覆盖基础模板的content块 #}
    <h1>{
               { page_heading }}</h1>

    {% if articles %} {# 检查文章列表是否存在且不为空 #}
        <ul>
            {% for article in articles %} {# 遍历文章列表 #}
                <li>
                    <h2>
                        <a href="{% url 'myapp:article_detail' article.id %}"> {# 使用url标签反向解析文章详情页URL #}
                            {
               { article.title|capfirst }} {# 显示文章标题，首字母大写 #}
                        </a>
                    </h2>
                    <p>By: {
               { article.author }} on {
               { article.pub_date|date:"F j, Y" }}</p> {# 显示作者和格式化的发布日期 #}
                </li>
            {% endfor %}
        </ul>
    {% else %}
        <p>No articles are available at the moment. Please check back later.</p> {# 如果没有文章则显示此消息 #}
    {% endif %}

    <p><em>Report generated at: {
               { current_server_time|time:"H:i:s" }}</em></p> {# 显示格式化的当前时间 #}

    {% if display_ad %} {# 条件判断，是否显示广告 #}
        <div class="advertisement">
            <p>Special offer! Visit our sponsors!</p> {# 广告内容 #}
        </div>
    {% endif %}
{% endblock %}

代码解释 (article_list.html):

{% extends "base_generic.html" %}: 表明此模板继承自 base_generic.html。
{% load static %}: 加载 static 标签库，使得 {% static ... %} 标签可用。
{% block title %}...{% endblock %} 和 {% block content %}...{% endblock %}: 定义或覆盖父模板中的同名块。
{
{ page_heading }}: 输出从上下文中传递的 page_heading 变量。
{% if articles %} ... {% else %} ... {% endif %}: 条件判断。
{% for article in articles %} ... {% endfor %}: 循环遍历 articles 列表。
{% url 'myapp:article_detail' article.id %}: DTL 的 url 标签，用于反向解析 URL。它会查找名为 article_detail 的 URL模式 (在 myapp 命名空间下)，并传入 article.id 作为参数来构建 URL。
{
{ article.title|capfirst }}: capfirst 是一个过滤器，将变量的第一个字母大写。
{
{ article.pub_date|date:"F j, Y" }}: date 过滤器，用于格式化日期对象。"F j, Y" 是一个日期格式化字符串 (例如 “January 15, 2023”)。
{
{ current_server_time|time:"H:i:s" }}: time 过滤器，用于格式化时间对象。

手动加载和渲染 (更底层，较少直接使用)：

你可以手动加载模板、创建上下文并调用模板的 render() 方法。
这在你需要对渲染过程进行更精细控制，或者在 Django 视图之外使用 DTL 时可能会用到。
步骤:

从 django.template 导入 loader 和 Context。
使用 loader.get_template(template_name) 获取 Template 对象。
创建一个 Context 对象 (或简单的字典，Django 会自动转换)。
调用 template.render(context)。
将渲染后的字符串包装在 HttpResponse 中。

示例:

# myapp/views.py (alternative way)
from django.template import loader, Context # 导入loader和Context
from django.http import HttpResponse, HttpRequest # 导入HttpResponse和HttpRequest
import datetime # 导入datetime模块

def manual_render_view(request: HttpRequest) -> HttpResponse: # 定义手动渲染视图函数
    """演示手动加载和渲染模板。"""
    try:
        template = loader.get_template('myapp/manual_example.html') # 手动加载模板文件
    except loader.TemplateDoesNotExist: # 捕获模板未找到异常
        return HttpResponse("Error: Template 'myapp/manual_example.html' not found.", status=404) # 返回404错误响应

    context_data = {
                 # 定义模板上下文数据
        'message': 'This template was rendered manually!', # 消息内容
        'current_time': datetime.datetime.now(), # 当前时间
        'items': ['One', 'Two', 'Three'] # 项目列表
    } # 上下文数据定义结束

    # Django 的 render() 快捷函数会自动处理 request 上下文处理器。
    # 手动创建 Context 时，如果需要 request 对象或其上下文处理器添加的变量，
    # 需要将 request 对象传递给 Context 构造函数。
    # context_obj = Context(context_data, request=request) # 创建Context对象，并传入request
    # 或者，更常见的是，Django 1.8+ 允许直接传递字典，它会自动创建Context
    # 并且 loader.render_to_string 或 Template.render() 会处理request
    
    # 如果仅使用 Template.render(dict_context), 它不会自动运行上下文处理器。
    # Template.render(context_obj) 如果 context_obj 是 Context 实例且创建时传入了 request, 则会处理。
    # 最简单且确保上下文处理器运行的方式是使用 render_to_string:
    
    from django.template.loader import render_to_string # 导入render_to_string

    # render_to_string 会加载模板、应用上下文处理器 (如果request提供了)，并渲染为字符串
    rendered_string = render_to_string('myapp/manual_example.html', context_data, request=request) # 使用render_to_string渲染为字符串

    # 或者，如果坚持完全手动：
    # 1. 获取模板
    # template = loader.get_template('myapp/manual_example.html')
    # 2. 创建一个完整的Context，包含处理器添加的内容 (较复杂)
    #    full_context_dict = {}
    #    for processor in loader.get_engine().template_context_processors:
    #        full_context_dict.update(processor(request))
    #    full_context_dict.update(context_data)
    #    context_obj_full = Context(full_context_dict)
    #    rendered_string = template.render(context_obj_full)

    return HttpResponse(rendered_string) # 将渲染后的字符串包装在HttpResponse中返回

对应的模板文件 (myapp/templates/myapp/manual_example.html):

{# myapp/templates/myapp/manual_example.html #}
<h1>Manual Render Example</h1>
<p>{
               { message }}</p>
<p>Rendered at: {
               { current_time|date:"Y-m-d H:i:s" }}</p>
<p>Request path (if available): {
               { request.path|default:"N/A" }}</p> {# 依赖于 request 上下文处理器 #}
<p>User (if available): {
               { user.username|default:"Anonymous" }}</p> {# 依赖于 auth 上下文处理器 #}
<ul>
    {% for item in items %}
        <li>{
               { item }}</li>
    {% endfor %}
</ul>

代码解释 (manual_render_view):

loader.get_template(...): 获取 Template 对象。
render_to_string('myapp/manual_example.html', context_data, request=request): 这是一个更推荐的手动渲染方式（如果只是想得到渲染后的字符串）。它会负责加载模板、创建包含上下文处理器结果的完整上下文（因为传入了 request），并渲染模板。
直接使用 template.render(context_dictionary) 不会自动运行上下文处理器。如果你需要它们（例如为了 {
{ request }} 或 {
{ user }}），你需要手动构建一个包含这些处理器结果的 Context 对象，或者确保你的 context_dictionary 已经包含了所有需要的值，或者使用像 render_to_string 这样更高级的辅助函数。
render() 快捷函数之所以方便，就是因为它在内部为你处理了所有这些细节。

使用 django.template.loader.render_to_string():

这个函数与 render() 类似，但不返回 HttpResponse。它只加载模板、应用上下文（包括上下文处理器，如果提供了 request 参数）并返回渲染后的字符串。
这在需要将模板渲染结果用于其他目的（例如，生成邮件内容、AJAX响应的HTML片段）时非常有用。
语法: render_to_string(template_name, context=None, request=None, using=None)
示例:

# myapp/views.py
from django.template.loader import render_to_string # 导入render_to_string
from django.http import JsonResponse, HttpRequest # 导入JsonResponse和HttpRequest
# from django.core.mail import send_mail # 假设用于发送邮件

def get_item_details_ajax(request: HttpRequest) -> JsonResponse: # 定义获取项目详情的AJAX视图
    item_id = request.GET.get('item_id') # 从GET请求中获取item_id
    # 模拟获取项目数据
    item_data = None # 初始化项目数据为None
    if item_id == '1': # 如果item_id为'1'
        item_data = {
                'name': 'Super Gadget', 'price': 49.99, 'description': 'An amazing gadget for all your needs.'} # 项目数据1
    elif item_id == '2': # 如果item_id为'2'
        item_data = {
                'name': ' सहायक उपकरण', 'price': 19.50, 'description': 'एक उपयोगी सहायक उपकरण।'} # 项目数据2 (包含Unicode字符)
    
    if item_data: # 如果找到了项目数据
        # 渲染一个HTML片段模板
        html_fragment = render_to_string( # 使用render_to_string渲染HTML片段
            'myapp/ajax_item_detail_fragment.html', # 片段模板路径
            {
                'item': item_data}, # 传递给片段模板的上下文
            request=request # 传递request以确保上下文处理器运行 (如果片段需要的话)
        ) # HTML片段渲染结束
        return JsonResponse({
                'success': True, 'html': html_fragment}) # 返回JSON响应，包含成功状态和HTML片段
    else: # 如果未找到项目数据
        return JsonResponse({
                'success': False, 'error': 'Item not found.'}, status=404) # 返回JSON响应，包含失败状态和错误信息

# def send_welcome_email(user_email, username):
#     email_subject = "Welcome to Our Platform!"
#     email_context = {'username': username, 'login_url': '/login/'}
#     email_body_html = render_to_string('emails/welcome_email.html', email_context)
#     email_body_text = render_to_string('emails/welcome_email.txt', email_context)
#
#     send_mail(
#         email_subject,
#         email_body_text, # 纯文本内容
#         'noreply@example.com',
#         [user_email],
#         html_message=email_body_html # HTML内容
#     )
#     print(f"Welcome email sent to {user_email}")

对应的HTML片段模板 (myapp/templates/myapp/ajax_item_detail_fragment.html):

{# myapp/templates/myapp/ajax_item_detail_fragment.html #}
{% if item %} {# 检查item是否存在 #}
    <h3>{
               { item.name|escape }}</h3> {# 显示转义后的项目名称 #}
    <p><strong>Price:</strong> ${
               { item.price|floatformat:2 }}</p> {# 显示格式化为两位小数的价格 #}
    <p><strong>Description:</strong> {
               { item.description|linebreaksbr }}</p> {# 显示描述，并将换行符转为<br> #}
{% else %}
    <p class="error">Item details could not be loaded.</p> {# 如果item不存在则显示错误 #}
{% endif %}

4.2.3 模板组织与命名空间

项目级模板: 存放在 TEMPLATES 设置中 DIRS 指定的目录（例如 project_root/templates/）。通常用于存放整个项目的通用模板，如基础布局 (base.html)、错误页面 (404.html, 500.html) 等。
应用级模板: 存放在各个 Django 应用内部的 templates 子目录中（例如 myapp/templates/）。当 APP_DIRS 为 True 时，Django 会自动查找这些目录。

命名空间化: 为了避免不同应用之间模板文件的名称冲突，强烈建议在应用的 templates 目录下再创建一个与应用同名的子目录，并将该应用的模板放在这个子目录中。

例如，对于名为 blog 的应用，其文章列表模板应存放在 blog/templates/blog/post_list.html。
在视图中加载时，使用 'blog/post_list.html'。
Django 的模板加载器在查找 blog/post_list.html 时，会检查 DIRS 中的每个目录以及每个启用了 APP_DIRS 的应用的 templates 目录，直到找到匹配的路径。
加载顺序: Django 会按照 TEMPLATES 设置中加载器的顺序（以及 DIRS 中路径的顺序）来查找模板。第一个找到的匹配模板将被使用。这意味着项目级的 templates 目录中的模板（如果与应用级模板同名且路径也相同）通常会优先于应用级的模板。这可以用来覆盖特定应用的默认模板。

示例目录结构:

my_django_project/
├── manage.py
├── my_django_project/  # 项目配置目录 (settings.py, urls.py, ...)
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── templates/          # 项目级模板目录 (在 settings.py 的 DIRS 中指定)
│   ├── base.html
│   ├── 404.html
│   └── 500.html
├── blog/               # 'blog' 应用
│   ├── __init__.py
│   ├── admin.py
│   ├── apps.py
│   ├── migrations/
│   ├── models.py
│   ├── templates/      # 'blog' 应用的模板根目录
│   │   └── blog/       # 命名空间子目录，与应用名相同
│   │       ├── post_list.html
│   │       ├── post_detail.html
│   │       └── includes/
│   │           └── _post_summary_card.html
│   ├── tests.py
│   ├── urls.py         # blog 应用的 URL 配置
│   └── views.py
├── users/              # 'users' 应用
│   ├── __init__.py
│   ├── ...
│   └── templates/
│       └── users/      # 命名空间子目录
│           ├── login.html
│           └── profile.html
└── static/             # 项目级静态文件目录 (通常用于存放共用静态资源)
    └── css/
        └── global_styles.css

这种结构清晰地分离了项目级模板和应用级模板，并通过命名空间避免了冲突，是 Django 项目开发的标准实践。

4.3 DTL 核心语法元素详解

Django 模板语言 (DTL) 的语法主要由三部分构成：变量 (Variables)、标签 (Tags) 和 过滤器 (Filters)。这些元素共同协作，使得开发者能够将动态数据有效地呈现在模板中。

4.3.1 变量 (Variables) 在 DTL 中的深度解析

在 DTL 中，变量被双花括号包围：{
{ variable_name }}。当模板引擎遇到一个变量时，它会从当前的上下文 (context) 中查找该变量，并将其值替换到模板的相应位置。

4.3.1.1 变量的查找与解析 (Dot Lookup)

DTL 使用“点号查找 (dot lookup)”机制来访问变量的属性或字典的键。当模板引擎遇到类似 {
{ person.name }} 的变量时，它会按以下顺序尝试解析：

字典键查找 (Dictionary Key Lookup):

首先，引擎会检查 person 是否是一个字典，并且是否有键 'name'。
例如，如果上下文中 person = {'name': 'Alice', 'age': 30}，则 {
{ person.name }} 会输出 “Alice”。

属性查找 (Attribute Lookup):

如果字典键查找失败（或者 person 不是字典），引擎会检查 person 是否有一个名为 name 的属性。
例如，如果 person 是一个对象实例 class Person: def __init__(self, name): self.name = name，且 person_obj = Person("Bob")，则 {
{ person_obj.name }} 会输出 “Bob”。
这包括通过 @property 装饰器定义的属性。

方法调用 (Method Call – 无参数):

如果属性查找也失败，引擎会检查 person 是否有一个名为 name 的无参数可调用方法。如果存在，引擎会调用该方法并使用其返回值。
重要限制: DTL 不允许在模板中直接向方法传递参数，例如 {
{ person.get_name('formal') }} 是无效的。如果你需要调用带参数的方法，或者方法有副作用，你应该在视图 (Python 代码) 中调用它，并将结果传递给模板上下文。或者，可以创建自定义模板标签或过滤器来实现此功能。
例如，如果 class Person: def name(self): return "Charlie"，则 {
{ person_obj.name }} 会调用 name() 方法并输出 “Charlie”。

列表索引查找 (List-Index Lookup):

如果前面的查找都失败，并且变量名 name 是一个有效的整数，引擎会尝试将 person 视为一个列表，并使用 name 作为索引进行访问。
例如，如果 items = ['apple', 'banana', 'cherry']，则 {
{ items.0 }} 会输出 “apple”，{
{ items.1 }} 会输出 “banana”。
注意：是 items.0 而不是 items[0]。方括号在 DTL 变量访问中通常不直接使用，而是通过点号加数字索引。

查找顺序的意义: 这个查找顺序是固定的。例如，如果一个对象同时有一个名为 foo 的属性和一个名为 foo 的无参数方法，属性会优先被访问。

示例：DTL 变量解析顺序

Python 代码 (例如 myapp/views.py):

# myapp/views.py
from django.shortcuts import render # 导入render快捷函数
from django.http import HttpRequest # 导入HttpRequest

class DemoClass: # 定义一个演示类
    def __init__(self): # 初始化方法
        self.attr_name = "Attribute Value" # 类属性
        self.dict_attr = {
            'key_in_dict_attr': "Value from dict_attr's key"} # 类属性，其值为一个字典

    def method_name(self): # 类方法 (无参数)
        return "Method Call Result" # 返回方法调用的结果

    def method_with_collision(self): # 与属性同名的方法
        return "Result from method_with_collision" # 返回方法调用的结果

# 模拟一个与属性和方法都冲突的键名
demo_object_with_key_collision = DemoClass() # 创建DemoClass实例
# 添加一个与方法同名的属性，这个属性会覆盖方法（在DTL点号查找的属性阶段）
# 但如果属性不存在，方法会被调用。
# demo_object_with_key_collision.method_name = "This is now an attribute, not the method's result"

# 模拟一个与属性同名的方法，但属性优先
demo_object_attr_method_collision = DemoClass() # 创建DemoClass实例
demo_object_attr_method_collision.method_with_collision_attr = "Attribute value for method_with_collision_attr" # 定义一个属性
# 假设DemoClass也有一个名为 method_with_collision_attr 的方法，但属性查找优先

def dtl_variable_lookup_view(request: HttpRequest): # 定义DTL变量查找视图函数
    """演示DTL变量查找顺序的视图。"""
    demo_obj = DemoClass() # 创建DemoClass实例

    context = {
             # 定义模板上下文
        'my_string': "Hello DTL!", # 简单字符串
        'my_number': 123, # 数字
        'my_list': ['first_item', 'second_item', 'third_item'], # 列表
        'my_dict': {
             # 字典
            'name': 'Dictionary Name', # 字典键'name'
            'value': 'Dictionary Value', # 字典键'value'
            'nested_dict': {
            'inner_key': 'Inner Value'}, # 嵌套字典
            'clash_key': 'Value from dict.clash_key' # 与对象属性/方法可能冲突的键
        },
        'demo_instance': demo_obj, # DemoClass的实例
        'another_instance_for_method_test': DemoClass(), # 另一个DemoClass实例用于测试方法调用
        'data_for_method_attr_clash': {
             # 用于测试字典键与对象属性/方法冲突的数据
            'method_name': "Value from data_for_method_attr_clash.method_name (dict key)", # 字典键与方法名冲突
            'attr_name': "Value from data_for_method_attr_clash.attr_name (dict key)" # 字典键与属性名冲突
        },
        # 演示属性优先于方法
        'obj_attr_over_method': type('AttrMethodClash', (object,), {
             # 动态创建一个类
            'my_prop': 'This is an attribute', # 类属性
            'my_prop': lambda self: 'This is a method result' # 同名方法 (但属性会优先)
            # DTL 属性查找优先，所以上面的 lambda 不会被作为方法调用
            # 为了清晰，我们让属性和方法名不同，或者用更明确的方式
        })(),
        'obj_method_if_no_attr': type('MethodNoAttrClash', (object,), {
             # 动态创建另一个类
            # no 'my_callable_prop' attribute
            'my_callable_prop': lambda self: 'Method result (no attr clash)' # 只有方法
        })(),
        'complex_object': {
             # 复杂对象，包含多种类型
            'name': 'Complex Object Top Level', # 顶层名称
            'details': demo_obj, # 嵌套DemoClass实例
            'tags': ['tag1', 'tag2'], # 标签列表
            'config': {
             # 配置字典
                'enabled': True, # 布尔值
                'retry_count': 3 # 数字
            }
        },
        'none_value': None, # None值
        'empty_string': "", # 空字符串
        'zero_value': 0, # 零值
        'false_value': False # False值
    } # 上下文定义结束
    return render(request, 'myapp/variable_lookup_example.html', context) # 渲染模板

对应的模板文件 (myapp/templates/myapp/variable_lookup_example.html):

{# myapp/templates/myapp/variable_lookup_example.html #}
{% extends "base_generic.html" %} {# 继承基础模板 #}

{% block title %}DTL Variable Lookup Test{% endblock %} {# 定义标题块 #}

{% block content %} {# 定义内容块 #}
    <h1>DTL Variable Lookup Mechanisms</h1>

    <h2>Basic Types:</h2>
    <p>String: <strong>{
           { my_string }}</strong></p> {# 输出字符串变量 #}
    <p>Number: <strong>{
           { my_number }}</strong></p> {# 输出数字变量 #}
    <p>None Value (outputs nothing by default): [{
           { none_value }}]</p> {# 输出None值，默认为空 #}
    <p>Empty String: [{
           { empty_string }}]</p> {# 输出空字符串 #}
    <p>Zero Value: [{
           { zero_value }}]</p> {# 输出零值 #}
    <p>False Value: [{
           { false_value }}]</p> {# 输出False值 #}


    <h2>List Access:</h2>
    <p>First item in list: <strong>{
           { my_list.0 }}</strong></p> {# 访问列表的第一个元素 #}
    <p>Second item in list: <strong>{
           { my_list.1 }}</strong></p> {# 访问列表的第二个元素 #}
    <p>Accessing non-existent high index (e.g., my_list.5) - (outputs nothing or configured invalid string): [{
           { my_list.5 }}]</p> {# 访问不存在的列表索引 #}
    <p>Accessing non-integer index (e.g., my_list.foo) - (outputs nothing or configured invalid string): [{
           { my_list.foo }}]</p> {# 使用非整数访问列表索引 #}

    <h2>Dictionary Access:</h2>
    <p>Dict 'name' (key lookup): <strong>{
           { my_dict.name }}</strong></p> {# 通过键名访问字典值 #}
    <p>Dict 'value' (key lookup): <strong>{
           { my_dict.value }}</strong></p> {# 通过键名访问字典值 #}
    <p>Dict 'nested_dict.inner_key': <strong>{
           { my_dict.nested_dict.inner_key }}</strong></p> {# 访问嵌套字典的值 #}
    <p>Dict missing key 'city' (outputs nothing or configured invalid string): [{
           { my_dict.city }}]</p> {# 访问字典中不存在的键 #}

    <h2>Object Attribute and Method Access (demo_instance):</h2>
    <p>Object 'attr_name' (attribute lookup): <strong>{
           { demo_instance.attr_name }}</strong></p> {# 访问对象属性 #}
    <p>Object 'method_name' (no-arg method call): <strong>{
           { demo_instance.method_name }}</strong></p> {# 调用对象的无参数方法 #}
    <p>Object 'dict_attr.key_in_dict_attr' (attr is dict, then key lookup): <strong>{
           { demo_instance.dict_attr.key_in_dict_attr }}</strong></p> {# 先访问对象属性(该属性是字典)，再访问字典的键 #}
    <p>Object non-existent attribute 'foo' (outputs nothing or configured invalid string): [{
           { demo_instance.foo }}]</p> {# 访问对象不存在的属性 #}

    <h2>Demonstrating Lookup Order (Dictionary Key vs. Object Attr/Method):</h2>
    <p>Context has <code>data_for_method_attr_clash.method_name</code> AND <code>another_instance_for_method_test.method_name()</code>.</p>
    <p>Accessing <code>another_instance_for_method_test.method_name</code>: <strong>{
           { another_instance_for_method_test.method_name }}</strong> (Should be method result from the object)</p> {# 调用另一个实例的方法 #}
    <p>Accessing <code>data_for_method_attr_clash.method_name</code>: <strong>{
           { data_for_method_attr_clash.method_name }}</strong> (Should be value from the dictionary key)</p> {# 访问字典的键 #}
    <p>Accessing <code>data_for_method_attr_clash.attr_name</code>: <strong>{
           { data_for_method_attr_clash.attr_name }}</strong> (Should be value from the dictionary key)</p> {# 访问字典的键 #}

    <hr>
    <p>Scenario: <code>my_dict</code> (a dict) vs <code>demo_instance</code> (an object). Both might have a 'clash_key' or 'clash_key()'.</p>
    <p>If <code>my_dict</code> is primary: <code>my_dict.clash_key</code> gives <strong>{
           { my_dict.clash_key }}</strong> (dict key lookup)</p> {# 访问字典的clash_key #}
    <p>If <code>demo_instance</code> is primary: <code>demo_instance.clash_key</code> (assuming it has such attr/method): [{
           { demo_instance.clash_key }}] (Will try attr, then method on demo_instance)</p> {# 尝试访问demo_instance的clash_key #}

    <h2>Attribute vs. Method (Same Name on Object):</h2>
    {# For this to work as intended, obj_attr_over_method needs 'my_prop' as attr and 'my_prop' as method #}
    {# Python attributes shadow methods of the same name. DTL's attr lookup comes before method lookup. #}
    {# Let's assume obj_attr_over_method.my_prop is an attribute #}
    <p>Object with attr 'my_prop' and method 'my_prop()': <code>obj_attr_over_method.my_prop</code> gives <strong>{
           { obj_attr_over_method.my_prop }}</strong> (Attribute should win)</p> {# 属性优先于同名方法 #}
    <p>Object with only method 'my_callable_prop()': <code>obj_method_if_no_attr.my_callable_prop</code> gives <strong>{
           { obj_method_if_no_attr.my_callable_prop }}</strong> (Method should be called)</p> {# 调用只有方法没有同名属性的对象的方法 #}

    <h2>Complex Object Traversal:</h2>
    <p>Complex Object Name: <strong>{
           { complex_object.name }}</strong></p> {# 访问复杂对象的顶层名称 #}
    <p>Complex Object's Details (DemoInstance) attr_name: <strong>{
           { complex_object.details.attr_name }}</strong></p> {# 访问嵌套对象的属性 #}
    <p>Complex Object's Details (DemoInstance) method_name: <strong>{
           { complex_object.details.method_name }}</strong></p> {# 调用嵌套对象的方法 #}
    <p>Complex Object's First Tag: <strong>{
           { complex_object.tags.0 }}</strong></p> {# 访问嵌套列表的第一个元素 #}
    <p>Complex Object's Config Enabled: <strong>{
           { complex_object.config.enabled }}</strong></p> {# 访问嵌套字典的值 #}
    <p>Complex Object's Config Retry Count: <strong>{
           { complex_object.config.retry_count }}</strong></p> {# 访问嵌套字典的值 #}

    <h2>Handling of Invalid Variables:</h2>
    {% if settings.DEBUG %} {# 检查settings.DEBUG，通常由debug上下文处理器提供 #}
        <p>In DEBUG mode, invalid variables might show more info or raise errors if not handled.</p>
    {% else %}
        <p>In non-DEBUG mode, invalid variables usually result in empty output or <code>string_if_invalid</code>.</p>
        <p><code>string_if_invalid</code> is '{
           { settings.TEMPLATES.0.OPTIONS.string_if_invalid|default:"(Not Set in settings for this demo)" }}'</p> {# 显示settings中string_if_invalid的配置 #}
    {% endif %}
    <p>Trying to access <code>non_existent_top_level_var</code>: [{
           { non_existent_top_level_var }}]</p> {# 访问顶层不存在的变量 #}
    <p>Trying to access <code>my_dict.non_existent_key</code>: [{
           { my_dict.non_existent_key }}]</p> {# 访问字典中不存在的键 #}
    <p>Trying to access <code>demo_instance.non_existent_attribute</code>: [{
           { demo_instance.non_existent_attribute }}]</p> {# 访问对象不存在的属性 #}

{% endblock %}

代码解释 (DTL 模板部分):

{
{ my_list.0 }}: 演示了列表索引访问。
{
{ my_dict.name }}: 演示了字典键访问。
{
{ demo_instance.attr_name }}: 演示了对象属性访问。
{
{ demo_instance.method_name }}: 演示了对象无参数方法的调用。
冲突和顺序:

当一个变量名（例如 method_name）同时存在于一个字典的键中（如 data_for_method_attr_clash.method_name）和另一个对象的无参数方法中（如 another_instance_for_method_test.method_name()），DTL 会根据你访问的“根”对象来决定使用哪个。如果你写 {
{ data_for_method_attr_clash.method_name }}，它会执行字典查找。如果你写 {
{ another_instance_for_method_test.method_name }}，它会先尝试属性查找，然后尝试方法调用。
如果一个对象 obj 同时有一个属性 x 和一个方法 x()，那么 {
{ obj.x }} 总是优先解析为属性 x 的值。只有当属性 x 不存在时，DTL 才会尝试调用方法 x()。

{
{ complex_object.details.attr_name }}: 演示了链式点号查找，可以深入嵌套的对象和字典。
处理无效/未定义变量:

当 DTL 尝试访问一个不存在的键、属性、索引，或者方法调用失败时，默认情况下，它不会抛出模板渲染错误（除非在非常特殊的情况下，如调用一个不存在的方法且该名称也不是属性）。相反，它通常会输出一个空字符串。
这种行为可以通过 settings.py 中 TEMPLATES 配置的 OPTIONS.string_if_invalid 来修改。例如，设置 string_if_invalid = 'DEBUG: undefined variable %s'，那么当变量 %s 未定义时，模板会输出这个字符串。
在开发模式下 (settings.DEBUG = True)，如果 string_if_invalid 未设置或设置为空字符串，对于某些类型的查找失败（尤其是属性/方法查找），Django 可能会在调试信息中提示，但页面通常仍会渲染。如果 string_if_invalid 被设置为非空字符串，则会显示该字符串。
StrictUndefined (像 Jinja2 中的) 在 DTL 中没有直接的等价物作为标准配置。DTL 的哲学更倾向于“静默失败”或通过 string_if_invalid 提供占位符，以避免因小数据问题导致整个页面崩溃。

4.3.1.2 变量的显示与自动转义

默认情况下，DTL 对所有通过 {
{ ... }} 输出的变量进行 HTML 转义。这意味着以下字符会被替换：

< 替换为 <
> 替换为 >
' (单引号) 替换为 '
" (双引号) 替换为 "
& 替换为 &

这是防止跨站脚本 (XSS) 攻击的一项重要安全措施。

示例：自动转义

# myapp/views.py
from django.shortcuts import render # 导入render快捷函数
from django.http import HttpRequest # 导入HttpRequest

def autoescape_demo_view(request: HttpRequest): # 定义自动转义演示视图函数
    context = {
             # 定义模板上下文
        'html_string': "<script>alert('This is an XSS attempt!');</script>", # 包含HTML脚本的字符串
        'normal_string': "This string has < and > symbols.", # 包含HTML特殊字符的普通字符串
        'user_input_title': "User's Title: "Special Chars & More"" # 用户输入的标题，包含引号和&符号
    } # 上下文定义结束
    return render(request, 'myapp/autoescape_example.html', context) # 渲染模板

对应的模板文件 (myapp/templates/myapp/autoescape_example.html):

{# myapp/templates/myapp/autoescape_example.html #}
<h1>DTL Autoescape Demonstration</h1>

<h2>Case 1: Potentially Harmful HTML</h2>
<p>Raw variable value (conceptual, not directly outputtable without turning off autoescape): <code>{
           { html_string_raw_placeholder }}</code></p> {# 这是一个占位符，实际不应这样输出 #}
<p>Rendered with default autoescape:</p>
<div>{
           { html_string }}</div> {# html_string 将被自动转义 #}

<h2>Case 2: String with HTML Special Characters</h2>
<p>Rendered with default autoescape:</p>
<div>{
           { normal_string }}</div> {# normal_string 将被自动转义 #}

<h2>Case 3: User Input with Quotes and Ampersand</h2>
<p>Rendered as title attribute (autoescape helps here too):</p>
<h3 title="{
           { user_input_title }}">Hover over this heading</h3> {# user_input_title 在HTML属性中，也应被转义 #}
<p>Rendered as content:</p>
<div>{
           { user_input_title }}</div> {# user_input_title 作为内容输出，也会被转义 #}

预期输出 (浏览器查看源代码会更清晰):

对于 {
{ html_string }}:
浏览器显示: <script>alert('This is an XSS attempt!');</script>
(脚本不会执行)
对于 {
{ normal_string }}:
浏览器显示: This string has < and > symbols.
对于 h3 标签的 title 属性和 {
{ user_input_title }} 内容:
title 属性会是 User's Title: "Special Chars & More"
内容会是 User's Title: "Special Chars & More"

关闭自动转义:
在某些情况下，你可能确实需要输出一个已知是安全的 HTML 字符串，而不希望 DTL 对其进行转义。有几种方法：

|safe 过滤器:

将 |safe 过滤器应用于变量，可以将其标记为“安全”，从而阻止自动转义。
务必确保你传递给 |safe 的内容来源可靠且确实是安全的，否则会引入 XSS 漏洞。
{
{ trusted_html_variable|safe }}

{% autoescape off %} … {% endautoescape %} 块:

可以将一段模板代码包裹在 {% autoescape off %} 和 {% endautoescape %} 标签之间，这会暂时关闭该代码块内的自动转义。
同样需要极度谨慎使用。

{% autoescape off %}
    {
               { variable_containing_raw_html }} {# 在这个块内，此变量不会被转义 #}
{% endautoescape %}

{
               { variable_containing_raw_html }} {# 在块外，此变量仍会被默认转义 #}

使用 mark_safe() 在 Python 端:

在 Python 代码中，你可以使用 django.utils.safestring.mark_safe() 函数将一个字符串标记为安全。当这个被标记的字符串传递到模板中并被渲染时，DTL 不会对其进行自动转义。
这通常用于自定义模板标签或视图逻辑中，当你能从程序上保证某段 HTML 是安全的。

# myapp/views.py
from django.utils.safestring import mark_safe # 导入mark_safe
from django.shortcuts import render # 导入render
from django.http import HttpRequest # 导入HttpRequest

def safe_content_view(request: HttpRequest): # 定义安全内容视图函数
    # 假设这是从一个受信任的Markdown转换器或富文本编辑器得到的HTML
    generated_safe_html = "<p>This is <strong>bold</strong> and <em>italic</em> text, generated programmatically and marked safe.</p>" # 已知的安全HTML
    
    # 标记为安全
    safe_html_object = mark_safe(generated_safe_html) # 使用mark_safe标记字符串为安全
    
    unsafe_html_for_comparison = "<button onclick='alert("unsafe!")'>Click Me (Unsafe)</button>" # 不安全的HTML，用于对比

    context = {
                 # 定义模板上下文
        'trusted_html': safe_html_object, # 已标记为安全的HTML对象
        'untrusted_html': unsafe_html_for_comparison # 未标记的HTML字符串
    } # 上下文定义结束
    return render(request, 'myapp/safe_example.html', context) # 渲染模板

对应的模板 (myapp/templates/myapp/safe_example.html):

{# myapp/templates/myapp/safe_example.html #}
<h2>Safe Content Demonstration</h2>

<h3>Using <code>mark_safe()</code> in Python:</h3>
<div>{
               { trusted_html }}</div> {# trusted_html 是 SafeString 对象，不会被转义 #}

<h3>Using <code>|safe</code> filter:</h3>
<div>{
               { untrusted_html|safe }}</div> {# untrusted_html 被显式标记为安全 (!!! 仅当你知道它是安全的才这样做 !!!) #}

<h3>Default autoescape for comparison:</h3>
<div>{
               { untrusted_html }}</div> {# untrusted_html 会被默认转义 #}

<h3>Using <code>{% autoescape off %}</code> block:</h3>
{% autoescape off %} {# 关闭自动转义块开始 #}
    <div>{
               { untrusted_html }}</div> {# 在此块内，untrusted_html 不会被转义 #}
{% endautoescape %} {# 关闭自动转义块结束 #}

何时使用 mark_safe vs |safe:

如果 HTML 是在 Python 代码中生成并能确保其安全性（例如，来自一个可靠的HTML生成库的输出，或者你仔细构造了它），则在 Python 端使用 mark_safe() 更好，因为它明确了数据在进入模板之前就是安全的。
如果一个变量通常应该被转义，但你知道在特定模板的特定位置，它的当前值是安全的，可以在模板中使用 |safe。这通常用于处理来自数据库的、已知是经过清理和审查的富文本内容。

安全是首要考虑: 在处理用户生成的内容或任何可能包含不可信数据的变量时，应始终依赖 DTL 的默认自动转义。只有在你绝对确定一段 HTML 是安全的，并且需要将其作为原始 HTML 输出时，才应考虑使用 |safe 或 {% autoescape off %}。错误地关闭转义是导致 XSS 漏洞的常见原因。

4.3.1.3 变量中无效字符的处理

如果变量名包含无效字符（例如空格、特殊符号，或者以数字开头且不是有效的列表索引），DTL 通常无法正确解析它。

{
{ my variable }} (带空格) – 无效
{
{ data-value }} (带连字符) – 无效 (DTL 会尝试查找 data 对象，然后查找名为 value 的属性/键，但不会将 data-value 视为一个整体变量名)。
{
{ 1st_item }} (以数字开头) – 无效

在这种情况下，你需要确保传递给模板的上下文中的键/属性名是有效的 Python 标识符（或有效的字典键字符串，对于字典访问）。如果你的数据源的键名不符合要求，应在视图中进行预处理，将其转换为 DTL 可接受的格式。

4.3.1.4 变量作用域

DTL 中的变量作用域相对简单：

顶层上下文: 视图传递给 render() 函数的 context 字典中的所有键都成为模板的顶层可用变量。
{% for %} 循环: 循环变量（例如 {% for item in my_list %} 中的 item）只在 for 循环内部可用。
{% with %} 标签: {% with new_var=old_var.some_attr %} 会创建一个名为 new_var 的局部变量，它只在 {% with %} 和 {% endwith %} 之间可用。这对于给复杂的表达式起一个简短的别名，或者避免重复访问深层嵌套的属性很有用。

{% with author_name=article.author.profile.get_full_name author_email=article.author.email %} {# 使用with标签定义局部变量 #}
    <p>Article by: {
             { author_name }}</p> {# 使用局部变量author_name #}
    <p>Contact: <a href="mailto:{
             { author_email }}">{
             { author_email }}</a></p> {# 使用局部变量author_email #}
{% endwith %} {# with标签结束 #}
{# author_name 和 author_email 在这里不再可用 #}

{% include %} 标签:

默认情况下，被包含的模板 ({% include "snippet.html" %}) 会继承调用它的模板的完整上下文。
你可以使用 with 子句来传递特定的、隔离的上下文给被包含的模板：
{% include "snippet.html" with person=user1 only %}

with person=user1: snippet.html 内部只能访问到 person 变量（其值为 user1），以及通过上下文处理器添加的全局变量。
only: 关键字 only 进一步限制了上下文，使得 snippet.html 只能访问 with 子句中明确传递的变量，而不会继承父模板的其他上下文变量（但上下文处理器添加的变量通常仍然可用，除非模板引擎配置非常特殊）。

模板继承 ({% extends %}): 子模板可以访问父模板在渲染时所拥有的所有上下文变量。块 ({% block %}) 内部可以像模板的其他部分一样访问这些变量。

DTL 的变量系统设计得既能满足常见的表现层需求，又通过点号查找提供了对复杂数据结构的合理访问。其默认的自动转义机制是保障Web安全的重要一环。理解其查找规则、作用域以及如何安全地处理 HTML 是有效使用 DTL 的基础。

4.3.2 标签 (Tags) 在 DTL 中的深度探索

Django 模板标签是被 {% 和 %} 包围的指令，它们控制模板的渲染逻辑、执行特定操作或引入外部内容。与主要用于输出值的变量不同，标签可以执行更复杂的操作，如创建循环、执行条件判断、加载其他模板、设置变量、加载外部资源等。

DTL 拥有一个丰富的内置标签集，并且允许开发者创建自定义标签来扩展其功能。

4.3.2.1 常用内置标签详解与高级应用

我们将逐一深入探讨 DTL 中最常用和最重要的内置标签，分析其参数、行为、内部机制以及在真实企业级场景中的应用和最佳实践。

A. {% for ... in ... %} 和 {% empty %}

核心功能: 迭代一个序列（列表、元组、查询集等），并在每次迭代中渲染其间的代码块。

语法:

{% for variable in iterable [reversed] %} {# for标签开始，可以迭代iterable，reversed是可选的，用于反向迭代 #}
    ... (循环体，可以使用 'variable') ...
{% empty %} {# 可选的empty标签，当iterable为空或不存在时执行 #}
    ... (当 'iterable' 为空或不存在时显示的内容) ...
{% endfor %} {# for标签结束 #}

reversed: 可选关键字，如果提供，则会反向迭代 iterable。

{% empty %}: 可选的子标签。如果 iterable 为空、不存在，或者解析为一个布尔值为 False 的对象 (例如 None 或一个空的自定义集合对象)，则 {% empty %} 和 {% endfor %} 之间的内容会被渲染。

forloop 特殊变量 (DTL 的 loop 等价物):
在 {% for %} 循环内部，DTL 自动提供一个名为 forloop 的特殊模板变量，它包含了当前循环状态的信息：

forloop.counter: 当前迭代的次数（从 1 开始）。
forloop.counter0: 当前迭代的次数（从 0 开始）。
forloop.revcounter: 从循环末尾开始的剩余迭代次数（从 1 开始）。当是最后一次迭代时为 1。
forloop.revcounter0: 从循环末尾开始的剩余迭代次数（从 0 开始）。当是最后一次迭代时为 0。
forloop.first: 布尔值，如果当前是第一次迭代，则为 True。
forloop.last: 布尔值，如果当前是最后一次迭代，则为 True。
forloop.parentloop: 在嵌套循环中，这个变量指向外层循环的 forloop 对象。这允许你访问外层循环的状态。

内部机制:

当 DTL 引擎遇到 {% for %} 标签时，它会尝试迭代传递给它的 iterable 对象。
对于 Django 的查询集 (QuerySets)，DTL 的 for 标签非常高效。它不会立即将整个查询集加载到内存中，而是按需从数据库中获取数据。这意味着即使处理包含数千条记录的查询集，内存开销也相对较低。然而，如果在循环内部对每个对象执行了额外的数据库查询（例如，访问未通过 select_related 或 prefetch_related 优化的关联对象），则可能导致 “N+1 查询问题”，严重影响性能。
reversed 关键字在应用于查询集时，会尝试使用数据库的反向排序（如果可能），或者在获取结果后在 Python 层面反转。

企业级应用场景与最佳实践:

渲染列表数据 (如文章、产品、用户):

# views.py
from django.shortcuts import render # 导入render快捷函数
from django.http import HttpRequest # 导入HttpRequest
# from .models import Product # 假设有一个Product模型

def product_list_view(request: HttpRequest): # 定义产品列表视图函数
    # products = Product.objects.filter(is_active=True).order_by('-popularity')[:20] # 获取激活且按流行度排序的前20个产品
    # 模拟产品数据
    products = [ # 产品数据列表
        {
                'name': 'Awesome Gadget', 'price': 99.99, 'stock': 15, 'category': 'Electronics'}, # 产品1
        {
                'name': 'Comfortable Chair', 'price': 149.00, 'stock': 5, 'category': 'Furniture'}, # 产品2
        {
                'name': 'Python Programming Book', 'price': 29.95, 'stock': 0, 'category': 'Books'}, # 产品3
        {
                'name': 'Coffee Maker', 'price': 75.50, 'stock': 30, 'category': 'Appliances'} # 产品4
    ] # 产品数据列表定义结束
    context = {
                'product_list': products} # 定义模板上下文
    return render(request, 'store/product_catalog.html', context) # 渲染模板

{# store/templates/store/product_catalog.html #}
{% if product_list %} {# 检查产品列表是否存在 #}
    <div class="product-grid">
        {% for product in product_list %} {# 遍历产品列表 #}
            <div class="product-card {% if forloop.counter0|divisibleby:2 %}even-row{% else %}odd-row{% endif %} {% if product.stock == 0 %}out-of-stock{% endif %}"> {# 根据循环索引和库存状态添加CSS类 #}
                <h3>{
               { product.name|truncatewords:5 }} ({
               { product.category }})</h3> {# 显示产品名称（截断到5个词）和类别 #}
                <p>Price: ${
               { product.price|floatformat:2 }}</p> {# 显示格式化后的价格 #}
                
                {% if product.stock > 0 and product.stock < 10 %} {# 如果库存在0和10之间 #}
                    <p class="low-stock-warning">Low stock! Only {
               { product.stock }} left.</p> {# 显示低库存警告 #}
                {% elif product.stock == 0 %} {# 如果库存为0 #}
                    <p class="unavailable">Currently unavailable.</p> {# 显示不可用信息 #}
                {% else %} {# 其他库存情况 #}
                    <p>In stock: {
               { product.stock }} units.</p> {# 显示库存数量 #}
                {% endif %}

                {% if forloop.first %} {# 如果是列表中的第一个产品 #}
                    <span class="badge new-arrival-badge">New Arrival!</span> {# 显示新到货标记 #}
                {% endif %}
                <a href="{% url 'store:product_detail' product.id %}">View Details</a> {# 产品详情链接 #}
            </div>
            {% if not forloop.last %} {# 如果不是最后一个产品 #}
                {# <hr class="product-separator"> #} {# 可以添加分隔线，但通常用CSS控制间距 #}
            {% endif %}
        {% endfor %}
    </div>
{% else %} {# 如果产品列表为空 #}
    <p>No products found matching your criteria. Please try a different search or category.</p> {# 显示无产品提示 #}
{% endif %}

代码解释与实践:

{% if forloop.counter0|divisibleby:2 %}even-row{% else %}odd-row{% endif %}: 使用 forloop.counter0 (0-based index) 和 divisibleby 过滤器来为表格行或列表项交替应用 CSS 类，实现斑马条纹效果。
{% if product.stock == 0 %}out-of-stock{% endif %}: 根据产品库存动态添加 CSS 类，用于视觉提示。
{
{ product.name|truncatewords:5 }}: 使用 truncatewords 过滤器确保产品名称不会过长而破坏布局。
{% if forloop.first %}: 为第一个项目添加特殊标记。
性能: 如果 product_list 是一个 QuerySet，确保在视图中通过 select_related (对于一对一或外键) 和 prefetch_related (对于多对多或反向外键) 预先加载相关的对象数据，以避免在循环中为每个 product 触发额外的数据库查询。例如，如果 Product 有一个 category 外键，并且模板中显示 product.category.name，那么在视图中应该用 Product.objects.select_related('category')...。

处理嵌套数据结构 (使用 forloop.parentloop):
假设我们需要显示一个按类别分组的产品列表。

# views.py
from django.shortcuts import render # 导入render快捷函数
from django.http import HttpRequest # 导入HttpRequest

def categorized_products_view(request: HttpRequest): # 定义按类别分组的产品视图函数
    # 模拟数据，实际中这可能来自数据库查询和Python端的预处理
    categorized_data = [ # 按类别分组的数据列表
        {
                
            'category_name': 'Electronics', # 类别1名称
            'products': [ # 类别1下的产品列表
                {
                'id': 101, 'name': 'Laptop Pro X', 'price': 1200.00}, # 产品1
                {
                'id': 102, 'name': 'Wireless Mouse', 'price': 25.00}, # 产品2
            ],
            'category_promo': '10% off all electronics this week!' # 类别1的促销信息
        },
        {
                
            'category_name': 'Books', # 类别2名称
            'products': [ # 类别2下的产品列表
                {
                'id': 201, 'name': 'The Art of DTL', 'price': 35.50}, # 产品1
                {
                'id': 202, 'name': 'Python Cookbook', 'price': 42.75}, # 产品2
            ],
            'category_promo': None # 类别2无促销信息
        },
        {
                
            'category_name': 'Apparel', # 类别3名称
            'products': [], # 类别3下无产品 (用于测试 empty)
            'category_promo': 'Free shipping on apparel orders over $50' # 类别3的促销信息
        }
    ] # 分组数据定义结束
    context = {
                'data_by_category': categorized_data} # 定义模板上下文
    return render(request, 'store/products_by_category.html', context) # 渲染模板

{# store/templates/store/products_by_category.html #}
<h1>Products by Category</h1>
{% for category_group in data_by_category %} {# 外层循环：遍历每个类别分组 #}
    <section class="category-section">
        <h2>
            Category {
               { forloop.counter }}: {
               { category_group.category_name }}
            (Outer loop index: {
               { forloop.counter0 }})
        </h2>
        {% if category_group.category_promo %} {# 如果类别有促销信息 #}
            <p class="promo">{
               { category_group.category_promo }}</p> {# 显示促销信息 #}
        {% endif %}

        {% if category_group.products %} {# 检查当前类别是否有产品 #}
            <ul>
                {% for product in category_group.products %} {# 内层循环：遍历当前类别下的产品 #}
                    <li>
                        {
               { product.name }} - ${
               { product.price|floatformat:2 }}
                        (Overall item #{
               { forloop.parentloop.counter0 }}.{
               { forloop.counter0 }}) {# 使用parentloop访问外层循环的索引 #}
                        {% if forloop.first %} (First in this category){% endif %} {# 标记类别中的第一个产品 #}
                    </li>
                {% empty %} {# 内层循环的empty块，如果category_group.products为空 #}
                    <li>No products currently in the {
               { category_group.category_name }} category.</li> {# 显示无产品提示 #}
                {% endfor %} {# 内层循环结束 #}
            </ul>
        {% else %} {# 如果category_group.products本身就是空的或不存在 (对应外层循环的当前项) #}
            <p>No products listed for the {
               { category_group.category_name }} category.</p> {# 另一种无产品提示方式 #}
        {% endif %}
    </section>
    {% if not forloop.last %}<hr>{% endif %} {# 在类别之间添加分隔线，除了最后一个 #}
{% empty %} {# 外层循环的empty块 #}
    <p>No categories to display.</p> {# 如果没有任何类别数据显示 #}
{% endfor %} {# 外层循环结束 #}

代码解释与实践:

{% for category_group in data_by_category %}: 外层循环遍历类别。
{% for product in category_group.products %}: 内层循环遍历该类别下的产品。
{
{ forloop.parentloop.counter0 }}: 在内层循环中，forloop 指向内层循环的状态。通过 forloop.parentloop 可以访问到外层循环的 forloop 对象，从而获取外层循环的计数器等信息。这对于生成嵌套列表的编号或理解层次结构非常有用。
内层循环也使用了 {% empty %} 来处理某个类别下可能没有产品的情况。
外层循环的 {% empty %} 处理整个 data_by_category 为空的情况。

结合 {% cycle %} 标签 (稍后详述 cycle):
forloop.cycle 也可以实现类似 {% cycle %} 标签的功能，但 {% cycle %} 标签更通用，可以在循环外使用。

{# 假设 item_list 存在 #}
<ul>
{% for item in item_list %}
    <li class="{
               { forloop.cycle 'list-item-odd' 'list-item-even' 'list-item-highlight' }}"> {# 使用forloop.cycle交替CSS类 #}
        {
               { item }}
    </li>
{% endfor %}
</ul>

reversed 关键字的应用:
当需要按相反顺序显示项目时，例如最新的评论在最前面，而数据源是按时间升序排列的。

{# 假设 comments 是一个按时间升序排列的列表或查询集 #}
<div class="comments-section">
    <h3>Recent Comments (Newest First):</h3>
    {% for comment in comments reversed %} {# 反向迭代评论列表 #}
        <div class="comment">
            <p><strong>{
               { comment.user.username }}</strong> ({
               { comment.timestamp|timesince }} ago):</p> {# 显示用户名和评论时间 #}
            <p>{
               { comment.text|linebreaksbr }}</p> {# 显示评论内容，自动转换换行为<br> #}
        </div>
    {% empty %}
        <p>No comments yet. Be the first to comment!</p> {# 无评论提示 #}
    {% endfor %}
</div>

注意: 对于大型查询集，在数据库层面使用 order_by('-timestamp') 通常比在模板中使用 reversed 更高效。reversed 在模板层面执行，可能意味着先获取所有数据到内存再反转（取决于对象类型）。

避免在循环中执行复杂计算或数据库查询:
这是 DTL (以及所有模板引擎) 的通用性能准则。如果循环体内部需要复杂的数据处理或多次访问数据库，应将这些逻辑移到视图中，预先准备好所有需要展示的数据，然后将扁平化或结构化的数据传递给模板。模板中的 for 循环应尽可能只做简单的迭代和数据显示。

B. {% if ... %}, {% elif ... %}, {% else %}

核心功能: 执行条件判断，根据表达式的真假来渲染不同的代码块。

语法:

{% if condition1 %} {# if标签开始，判断condition1 #}
    ... (当 condition1 为真时渲染) ...
{% elif condition2 %} {# 可选的elif标签，当前面的if/elif为假时，判断condition2 #}
    ... (当 condition1 为假且 condition2 为真时渲染) ...
{% else %} {# 可选的else标签，当前面所有if/elif都为假时执行 #}
    ... (当所有条件都为假时渲染) ...
{% endif %} {# if标签结束 #}

条件表达式 (condition):

可以是单个变量 (DTL 会判断其“真实性”，类似于 Python 的 bool(variable))。

False 的值包括：None、空字符串 ""、空列表 []、空字典 {}、空元组 ()、数字零 0。
所有其他值通常被认为是 True。

可以使用比较操作符：== (等于), != (不等于), < (小于), > (大于), <= (小于等于), >= (大于等于)。
可以使用逻辑操作符：and, or, not (注意是小写)。
可以使用 in 和 not in 操作符来检查成员关系。
重要: DTL 的 if 标签中的表达式求值能力远不如 Python 的 if 语句。

不能直接进行算术运算: {% if user.age + 5 > 20 %} 是无效的。算术运算应在视图中完成。
不能直接调用带参数的方法: {% if user.has_permission('edit_post') %} 是无效的。应在视图中调用并将布尔结果传递给模板，或者创建一个自定义模板标签。
变量属性/字典键访问: {% if user.profile.is_active %} 或 {% if settings_dict.FEATURE_ENABLED %} 是允许的。
过滤器可以用在 if 条件中的变量上吗？ 通常不行。DTL 的 if 标签直接对变量或其属性/键的“真实性”或比较结果进行判断。如果你需要基于过滤后的值做判断，通常也应在视图中处理或通过自定义标签。

例如，{% if items|length > 0 %} 是无效的。你应该用 {% if items %} (判断列表是否为空) 或 {% if items|length_is:"0"|not %} (使用 length_is 过滤器和 not，但这比较迂回)。更好的方式是直接判断 items 是否为空: {% if items %} (列表非空为真) 或 {% if not items %} (列表为空为真)。
对于长度，DTL 提供了一个 length 过滤器，但它通常用于输出，而不是直接在 if 逻辑中使用。{% if forloop.length > 5 %} 是可以的，因为 forloop.length 是一个可以直接比较的数字。

操作符优先级: DTL 遵循一定的操作符优先级 (not > and > or)。可以使用括号 () 来明确分组和改变运算顺序，但这在 DTL 的 if 中并不常见，因为表达式本身就应该保持简单。

内部机制:

DTL 引擎在遇到 if 标签时，会解析其后的条件表达式。
它会从上下文中获取变量的值，并按照 DTL 的“真实性”规则或比较操作符进行求值。
如果条件为真，则渲染该 if (或 elif) 块内部的内容，并跳过后续的 elif 和 else 块。
如果所有 if 和 elif 条件都为假，则渲染 else 块的内容（如果存在）。

企业级应用场景与最佳实践:

根据用户权限显示/隐藏内容:

# views.py
# request.user 对象由 django.contrib.auth.context_processors.auth 添加到上下文
# 假设 User 模型有一个 is_moderator 布尔字段或一个 has_perm 方法
# def some_view(request):
#     user_can_delete = request.user.has_perm('myapp.delete_comment')
#     return render(request, 'myapp/comment_display.html', {'user_can_delete_comment': user_can_delete, ...})

{# myapp/templates/myapp/comment_display.html #}
<div class="comment">
    <p>{
               { comment.text }}</p>
    <span class="author">By: {
               { comment.author.username }}</span>
    {% if request.user.is_authenticated %} {# 检查用户是否已认证 #}
        {% if request.user == comment.author or request.user.is_staff or user_can_delete_comment %} {# 用户是评论作者，或者是员工，或者有删除权限 #}
            <button class="delete-comment-btn" data-comment-id="{
               { comment.id }}">Delete</button> {# 显示删除按钮 #}
        {% endif %}
        {% if request.user.is_staff %} {# 如果用户是员工 #}
            <button class="edit-comment-btn" data-comment-id="{
               { comment.id }}">Edit (Staff)</button> {# 显示编辑按钮 #}
        {% endif %}
    {% endif %}
</div>

实践:

request.user (由上下文处理器提供) 在模板中非常常用。
复杂的权限逻辑 (如 user_can_delete_comment) 应该在视图中计算出来，并将一个简单的布尔标志传递给模板。模板中的 if 条件应保持简洁。

处理可选数据显示:

{# 假设 'product' 对象在上下文中 #}
<div class="product-details">
    <h2>{
               { product.name }}</h2>
    {% if product.description %} {# 如果产品描述存在且不为空 #}
        <div class="description">
            <h3>Product Description:</h3>
            <p>{
               { product.description|linebreaks }}</p> {# 显示描述，并将文本换行转为HTML换行 #}
        </div>
    {% endif %}

    {% if product.sku %} {# 如果SKU存在 #}
        <p>SKU: {
               { product.sku }}</p> {# 显示SKU #}
    {% else %}
        <p>SKU: Not Available</p> {# 如果SKU不存在，显示提示 #}
    {% endif %}

    {% if product.image_url %} {# 如果图片URL存在 #}
        <img src="{
               { product.image_url }}">{ product.name }}"> {# 显示产品图片 #}
    {% else %}
        <img src="{% static 'images/placeholder.png' %}">

{# 假设 'user' 和 'subscription' 对象在上下文中 #}
{% if user.is_authenticated and user.subscription.is_active and not user.is_banned %} {# 组合多个条件 #}
    <p>Welcome, valued subscriber!</p> {# 用户已认证、订阅激活且未被封禁 #}
    <a href="{% url 'premium_content' %}">Access Premium Content</a> {# 提供高级内容链接 #}
{% elif user.is_authenticated and not user.subscription.is_active %} {# 用户已认证但订阅未激活 #}
    <p>Your subscription is not active. Please renew to access premium features.</p> {# 提示续订 #}
    <a href="{% url 'renew_subscription' %}">Renew Now</a> {# 续订链接 #}
{% else %} {# 其他情况 (未登录或被封禁等) #}
    <p>Please log in or sign up to see more.</p> {# 提示登录或注册 #}
{% endif %}

# views.py
# def my_view(request):
#     user_groups = [group.name for group in request.user.groups.all()] # 获取用户所属组的名称列表
#     special_item_ids = [10, 25, 42]
#     context = {
                
#         'user_groups': user_groups,
#         'item': {'id': 25, 'name': 'Special Item'},
#         'special_item_ids': special_item_ids
#     }
#     return render(request, 'myapp/in_operator_example.html', context)

{# myapp/templates/myapp/in_operator_example.html #}
{% if "editors" in user_groups and "beta_testers" in user_groups %} {# 检查用户是否同时属于 'editors' 和 'beta_testers' 组 #}
    <p>You are an editor and a beta tester! Special access granted.</p> {# 显示特殊权限信息 #}
{% endif %}

{% if item.id in special_item_ids %} {# 检查 item.id 是否在 special_item_ids 列表中 #}
    <p>"{
               { item.name }}" is a specially featured item!</p> {# 如果是特殊项目则显示提示 #}
{% endif %}

{% if "admin" not in user_groups %} {# 检查用户是否不属于 'admin' 组 #}
    <p>You do not have administrator privileges.</p> {# 显示无管理员权限提示 #}
{% endif %}

{# 假设 'score' 和 'max_score' 在上下文中 #}
{% if score == max_score %} {# 检查分数是否等于最高分 #}
    <p>Perfect score! Congratulations!</p> {# 满分祝贺 #}
{% elif score >= max_score * 0.8 %} {# 检查分数是否大于等于最高分的80% (注意：这种乘法应在视图中完成) #}
    {# DTL修正: 假设 high_threshold = max_score * 0.8 在视图中计算好并传入 #}
    {# {% if score >= high_threshold %} #}
    <p>Excellent score! You did very well.</p> {# 高分评价 #}
{% elif score < low_threshold %} {# 假设 low_threshold 在视图中计算好并传入 #}
    <p>Keep practicing! You can improve.</p> {# 低分鼓励 #}
{% endif %}

{% if product.quantity_available > 0 %} {# 检查产品可用数量是否大于0 #}
    <button>Add to Cart</button> {# 显示添加到购物车按钮 #}
{% else %}
    <button disabled>Out of Stock</button> {# 禁用按钮并显示缺货 #}
{% endif %}

{# 场景：显示用户订单列表，如果用户没有订单，则显示提示信息 #}
{% if user_orders %} {# 首先检查 user_orders 是否存在且不为空，这是一种防御性编程 #}
    <h2>您的订单历史：</h2>
    <ul>
        {% for order in user_orders %} {# 遍历用户的订单列表 #}
            <li>
                订单号: {
           { order.id }} - 金额: ¥{
           { order.amount }} - 状态: {
           { order.get_status_display }} {# 显示订单的ID、金额和状态描述 #}
                <ul>
                    {% for item in order.items.all %} {# 嵌套循环，遍历订单中的商品项 #}
                        <li>{
           { item.product.name }} ({
           { item.quantity }}件) - ¥{
           { item.subtotal }}</li> {# 显示商品名称、数量和小计 #}
                    {% empty %} {# 如果订单中没有任何商品项（理论上不常见，但作为示例） #}
                        <li>此订单中没有商品。</li> {# 显示订单为空的提示 #}
                    {% endfor %} {# 结束商品项的循环 #}
                </ul>
            </li>
        {% empty %} {# 如果 user_orders 列表为空 #}
            <p>您还没有任何订单。快去挑选您喜欢的商品吧！</p> {# 显示用户没有订单的提示信息 #}
        {% endfor %} {# 结束订单列表的循环 #}
    </ul>
{% else %} {# 如果 user_orders 不存在或为空 #}
    <p>您还没有任何订单。快去挑选您喜欢的商品吧！</p> {# 同样显示用户没有订单的提示信息 #}
{% endif %}

{# 场景：展示一个新闻列表，并对第一条和最后一条新闻进行特殊标记，同时显示序号 #}
{# 假设 news_list 是从视图传递过来的新闻对象列表 #}
{% if news_list %}
    <div class="news-container">
        {% for news_item in news_list %} {# 开始遍历新闻列表 #}
            <div class="news-article {% if forloop.first %}first-news{% endif %} {% if forloop.last %}last-news{% endif %}"> {# 根据是否为首尾项添加CSS类 #}
                <h4>
                    <span class="news-index">{
           { forloop.counter }}.</span> {# 显示新闻的序号，从1开始 #}
                    {
           { news_item.title }} {# 显示新闻标题 #}
                </h4>
                <p class="publish-date">发布于: {
           { news_item.publish_date|date:"Y-m-d H:i" }}</p> {# 显示发布日期，并使用date过滤器格式化 #}
                <p class="short-content">{
           { news_item.short_description|truncatewords:30 }}</p> {# 显示新闻摘要，并使用truncatewords过滤器截断 #}

                {% if forloop.first %} {# 如果是第一条新闻 #}
                    <p class="highlight"><strong>最新！</strong> 这是我们列表中的第一条新闻。</p> {# 对第一条新闻添加高亮提示 #}
                {% endif %}

                {% if forloop.last and not forloop.first %} {# 如果是最后一条新闻，且列表不只有一项 #}
                    <hr> {# 在最后一条新闻后添加分割线 #}
                    <p class="note">已是列表末尾。</p> {# 提示已到列表末尾 #}
                {% endif %}

                {# 示例：嵌套循环中的 parentloop (假设 news_item 有 related_tags 属性) #}
                {% if news_item.related_tags.all %} {# 检查是否有相关标签 #}
                    <div class="tags">
                        <strong>相关标签 (外层循环次数 {
           { forloop.counter0 }}):</strong>
                        {% for tag in news_item.related_tags.all %} {# 遍历相关标签 #}
                            <span class="tag-item">{
           { tag.name }}</span> {# 显示标签名称 #}
                            {# 访问父循环的计数器 #}
                            (父循环计数: {
           { forloop.parentloop.counter }}, 当前子循环计数: {
           { forloop.counter }})
                        {% endfor %} {# 结束标签循环 #}
                    </div>
                {% endif %}
            </div>
        {% empty %} {# 如果 news_list 为空 #}
            <p>暂时没有新闻发布。</p> {# 显示没有新闻的提示 #}
        {% endfor %} {# 结束新闻列表循环 #}
    </div>
{% else %}
    <p>无法加载新闻列表。</p> {# news_list 本身不存在或为 None 时的提示 #}
{% endif %}

{% for item in items %}
    <tr class="{% if forloop.counter0|divisibleby:2 %}even-row{% else %}odd-row{% endif %}"> {# 使用 forloop.counter0 和 divisibleby 过滤器实现隔行变色 #}
        <td>{
             { item.name }}</td>
        <td>{
             { item.value }}</td>
    </tr>
{% endfor %}

<div class="product-grid">
    {% for product in product_list %}
        {% if forloop.counter0|divisibleby:4 and not forloop.first %} {# 每4个产品（从第0个开始计数）且不是第一个时，结束上一行 #}
            </div><div class="product-row"> {# 结束旧的 product-row 并开始新的 #}
        {% elif forloop.first %} {# 如果是第一个产品 #}
            <div class="product-row"> {# 开始第一行 #}
        {% endif %}
        <div class="product-item">{
             { product.name }}</div> {# 显示产品项 #}
        {% if forloop.last %} {# 如果是最后一个产品 #}
            </div> {# 结束最后一行 #}
        {% endif %}
    {% endfor %}
</div>

{% if condition1 %}
    {# 当 condition1 为真时渲染此部分 #}
{% elif condition2 %}
    {# 当 condition1 为假，且 condition2 为真时渲染此部分 #}
{% else %}
    {# 当所有前面的条件都为假时渲染此部分 #}
{% endif %}

{# 场景：根据用户角色、文章状态和权限来决定是否显示编辑按钮 #}
{# 假设从视图传递了以下上下文：
   user_is_authenticated (布尔值)
   user_is_staff (布尔值)
   user_is_superuser (布尔值)
   article (文章对象)
   user_can_edit_article (视图中预计算的布尔值，表示当前用户是否有编辑此文章的权限)
#}

{% if user_is_authenticated %} {# 首先检查用户是否已登录 #}
    <p>欢迎回来, {
           { request.user.username }}!</p> {# 显示欢迎信息，request.user 在已登录时可用 #}

    {% if article %} {# 确保文章对象存在 #}
        <h3>{
           { article.title }}</h3> {# 显示文章标题 #}
        <p>{
           { article.content|safe }}</p> {# 显示文章内容，使用 safe 过滤器允许 HTML（假设内容是安全的） #}

        {# 条件1: 超级用户总是可以编辑 #}
        {# 条件2: 或者，员工用户且文章是草稿状态 (假设 article.status == 'draft') #}
        {# 条件3: 或者，视图明确告知用户可以编辑此特定文章 (user_can_edit_article) #}
        {% if user_is_superuser or (user_is_staff and article.status == 'draft') or user_can_edit_article %} {# 组合多个条件判断 #}
            <a href="{% url 'edit_article' article_id=article.id %}">编辑文章</a> {# 显示编辑链接，使用 url 标签生成URL #}
        {% elif article.author == request.user and article.status != 'published' %} {# 条件4: 或者，当前用户是作者且文章未发布 #}
            <p>您可以编辑您的未发布文章。</p>
            <a href="{% url 'edit_article' article_id=article.id %}">编辑文章</a>
        {% else %} {# 如果以上条件都不满足 #}
            <p>您没有编辑此文章的权限。</p> {# 显示没有编辑权限的提示 #}
        {% endif %}

        {# 另一个例子：使用 'in' 和 'not' #}
        {% if 'feature_flag_x' in active_feature_flags and not user_is_beta_tester %} {# 检查特性标志是否激活，且用户不是beta测试者 #}
            <p>特性X对您不可用 (仅限 Beta 测试者)。</p>
        {% elif 'feature_flag_x' in active_feature_flags and user_is_beta_tester %}
             <p>您可以使用特性X！</p>
        {% endif %}

    {% else %} {# 如果 article 对象不存在 #}
        <p>请求的文章未找到。</p> {# 显示文章未找到的提示 #}
    {% endif %}

{% else %} {# 如果用户未登录 #}
    <p>请 <a href="{% url 'login' %}?next={
           { request.path }}">登录</a> 查看内容并进行操作。</p> {# 提示用户登录，并提供 next 参数以便登录后重定向 #}
{% endif %}

from django.shortcuts import render
from .models import Article

def article_detail(request, article_id):
    article = Article.objects.get(pk=article_id)
    can_edit = False
    can_publish = False

    if request.user.is_authenticated:
        if request.user.is_superuser:
            can_edit = True
            can_publish = True
        elif request.user.is_staff and article.status == 'draft':
            can_edit = True
            can_publish = True # 假设员工也可以发布草稿
        elif article.author == request.user:
            can_edit = True
            if article.status != 'published': # 作者只能发布未发布的
                can_publish = True
        # 更复杂的权限检查，例如基于组或特定权限模型
        # if request.user.has_perm('myapp.change_article'):
        #     can_edit = True

    context = {
                
        'article': article,
        'user_can_edit_article': can_edit,       # 视图中计算好的布尔值
        'user_can_publish_article': can_publish, # 视图中计算好的布尔值
    }
    return render(request, 'myapp/article_detail.html', context)

{% if user_can_edit_article %}
    <a href="...">编辑</a>
{% endif %}
{% if user_can_publish_article %}
    <form method="post" action="{% url 'publish_article' article.id %}">
        {% csrf_token %}
        <button type="submit">发布文章</button>
    </form>
{% endif %}

{% with alias=complex_variable_expression %}
    {# 在这个块内部，可以使用 'alias' 来代替 'complex_variable_expression' #}
    <p>值为: {
           { alias }}</p>
    {% if alias.some_property %}
        <p>属性存在: {
           { alias.some_property }}</p>
    {% endif %}
{% endwith %}

{% with alpha=object.very_long_attribute_name beta=another_object.get_value.sub_value %}
    <p>Alpha: {
           { alpha }}</p>
    <p>Beta: {
           { beta }}</p>
{% endwith %}

# views.py (示例)
context = {
            
    'site_config': {
            
        'theme': {
            
            'colors': {
            
                'primary': '#007bff',
                'secondary': '#6c757d',
                'background': '#f8f9fa'
            },
            'font': {
            
                'family': 'Arial, sans-serif',
                'size': '16px'
            }
        },
        'seo': {
            
            'default_title': 'My Awesome Site',
            'default_description': 'A great site built with Django.'
        }
    }
}

<body>
    <header>
        <h1>{
           { site_config.seo.default_title }}</h1>
    </header>
    <p>Welcome! The secondary color is {
           { site_config.theme.colors.secondary }}.</p>
</body>

{% with theme_colors=site_config.theme.colors theme_font=site_config.theme.font site_seo=site_config.seo %}
    <body>
        <header>
            <h1>{
           { site_seo.default_title }}</h1>
        </header>
        <p>Welcome! The secondary color is {
           { theme_colors.secondary }}.</p>
        <p>Font size: {
           { theme_font.size }}</p>
        <meta name="description" content="{
           { site_seo.default_description }}">
    </body>
{% endwith %}

# models.py
class Product(models.Model):
    name = models.CharField(max_length=100)
    base_price = models.DecimalField(max_digits=10, decimal_places=2)
    # ... other fields ...

    @property
    def discounted_price(self):
        # 模拟一个可能涉及数据库查询或复杂计算的属性
        # In a real scenario, this might involve checking active promotions, user group, etc.
        from decimal import Decimal
        # print(f"Calculating discounted_price for {self.name}") # 用于调试，观察调用次数
        discount_percentage = self.get_current_discount_for_user() # 这是一个假设的方法
        if discount_percentage > 0:
            return self.base_price * (Decimal('1') - discount_percentage / Decimal('100'))
        return self.base_price

    def get_current_discount_for_user(self):
        # 假设这个方法会查询数据库或执行一些逻辑
        # For this example, let's return a fixed discount
        return Decimal('10') # 10% discount

{# 假设 product 是单个 Product 实例 #}
<p>产品名称: {
           { product.name }}</p>
<p>原价: {
           { product.base_price }}</p>
{% if product.discounted_price < product.base_price %}
    <p>折扣价: <strong>{
           { product.discounted_price }}</strong> (省了 {
           { product.base_price|subtract:product.discounted_price }})</p>
    <p>您享受了折扣！最终价格为: {
           { product.discounted_price }}</p>
{% else %}
    <p>价格: {
           { product.discounted_price }} (当前无折扣)</p>
{% endif %}

{# 假设 product 是单个 Product 实例 #}
<p>产品名称: {
           { product.name }}</p>
<p>原价: {
           { product.base_price }}</p>
{% with final_price=product.discounted_price original_price=product.base_price %} {# 将计算结果赋给别名 #}
    {% if final_price < original_price %} {# 使用别名进行比较和显示 #}
        <p>折扣价: <strong>{
           { final_price }}</strong> (省了 {
           { original_price|subtract:final_price }})</p> {# subtract 是一个需要自定义的过滤器或在视图中计算差额 #}
        <p>您享受了折扣！最终价格为: {
           { final_price }}</p>
    {% else %}
        <p>价格: {
           { final_price }} (当前无折扣)</p>
    {% endif %}
{% endwith %}

{# api_response 是一个复杂的字典 #}
{% with user_profile=api_response.data.user.profile shipping_address=api_response.data.user.addresses.shipping %}
    <p>用户名: {
             { user_profile.username }}</p>
    <p>邮箱: {
             { user_profile.email }}</p>
    <p>收货城市: {
             { shipping_address.city }}</p>
{% endwith %}

{# parent_template.html #}
{% with card_title=object.name|truncatechars:20 card_image=object.get_primary_image_url card_link=object.get_absolute_url %}
    {% include "myapp/components/info_card.html" with title=card_title image_url=card_image link_url=card_link only %}
{% endwith %}

{# myapp/components/info_card.html #}
<div class="card">
    {% if image_url %}<img src="{
             { image_url }}">{ title }}">{% endif %}
    <h3><a href="{
             { link_url }}">{
             { title }}</a></h3>
</div>

{% for item in complex_item_list %}
    {% with primary_data=item.get_primary_data secondary_info=item.related_object.fetch_secondary_details %}
        <div class="item-display">
            <h4>{
             { primary_data.name }}</h4>
            <p>Info: {
             { secondary_info.description }}</p>
            {% if primary_data.is_active %}
                <span class="status-active">Active</span>
            {% endif %}
        </div>
    {% endwith %}
{% endfor %}

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-F-8">
    <title>{% block title %}默认标题{% endblock title %}</title> {# 定义一个名为 title 的块，并提供默认内容 #}
    {% block extra_head %}{% endblock extra_head %} {# 定义一个名为 extra_head 的空块，子模板可以填充额外的头部内容 #}
</head>
<body>
    <header>
        <h1>{% block page_header %}我的网站{% endblock page_header %}</h1>
    </header>
    <nav>
        {% block navigation %}
            <ul>
                <li><a href="/">首页</a></li>
                <li><a href="/about/">关于</a></li>
            </ul>
        {% endblock navigation %}
    </nav>
    <main>
        {% block content %}
            <p>这是默认的主要内容区域。</p>
        {% endblock content %}
    </main>
    <footer>
        <p>&copy; {% now "Y" %} 我的公司. {% block footer_extra %}{% endblock %}</p> {# now 标签获取当前年份，footer_extra 是一个可扩展的块 #}
    </footer>
    {% block scripts %}{% endblock scripts %} {# 用于子模板添加页面特定的 JavaScript 文件 #}
</body>
</html>

{% extends "base.html" %} {# 声明继承自 base.html #}

{% block title %}产品详情页{% endblock title %} {# 覆盖 title 块的内容 #}

{% block extra_head %} {# 添加额外的头部内容 #}
    <link rel="stylesheet" href="/static/css/product_detail.css">
    <meta name="description" content="查看我们的最新产品详情。">
{% endblock extra_head %}

{% block page_header %}产品：{
             { product.name }}{% endblock page_header %} {# 覆盖页面主标题 #}

{% block content %} {# 覆盖主要内容区域 #}
    <h2>{
             { product.name }}</h2>
    <img src="{
             { product.image.url }}">{ product.name }}">
    <p>价格: ¥{
             { product.price }}</p>
    <p>描述: {
             { product.description|linebreaksbr }}</p> {# linebreaksbr 过滤器将换行符转为 <br> #}

    {# 如果想在子模板中追加内容到父块，而不是完全覆盖，可以使用 {
             { block.super }} #}
{% endblock content %}

{% block scripts %} {# 添加此页面特定的 JavaScript #}
    {
             { block.super }} {# 如果父模板的 scripts 块有内容，先渲染它 #}
    <script src="/static/js/product_interaction.js"></script>
{% endblock scripts %}

<!DOCTYPE html>
<html>
<head>
    <title>{% block page_title %}通用网站标题{% endblock %}</title>
    {% block head_css %}
        <link rel="stylesheet" href="/static/css/base_styles.css"> {# 通用基础样式 #}
    {% endblock head_css %}
</head>
<body>
    <div>
        {% block sidebar_content %}
            <h4>导航</h4>
            <ul>
                <li><a href="/">主页</a></li>
            </ul>
        {% endblock sidebar_content %}
    </div>
    <div>
        {% block main_content_area %}
            <p>欢迎来到我们的网站！</p>
        {% endblock main_content_area %}
    </div>
    {% block body_scripts %}
        <script src="/static/js/global_analytics.js"></script> {# 全局统计脚本 #}
    {% endblock body_scripts %}
</body>
</html>

{% extends "base_layout.html" %} {# 继承 base_layout.html #}

{% block page_title %}{
           { article.title }} - 文章详情{% endblock page_title %} {# 覆盖页面标题 #}

{% block head_css %} {# 扩展 head_css 块 #}
    {
           { block.super }} {# 首先引入父模板 base_styles.css #}
    <link rel="stylesheet" href="/static/css/article_specific.css"> {# 然后添加文章页特定的样式 #}
    <link rel="canonical" href="{
           { article.get_absolute_url }}"> {# 添加规范链接 #}
{% endblock head_css %}

{% block sidebar_content %} {# 完全覆盖侧边栏内容 #}
    <h4>相关文章</h4>
    <ul>
        {% for related_article in article.related_articles.all %} {# 假设 article 有 related_articles 关联 #}
            <li><a href="{
           { related_article.get_absolute_url }}">{
           { related_article.title }}</a></li>
        {% endfor %}
    </ul>
    <hr>
    <p><a href="{% url 'article_archive' %}">返回文章列表</a></p> {# 使用 url 标签生成归档页链接 #}
{% endblock sidebar_content %}

{% block main_content_area %} {# 覆盖主要内容区域 #}
    <h1>{
           { article.title }}</h1>
    <div class="meta">作者: {
           { article.author.get_full_name }} | 发布于: {
           { article.publish_date|date:"Y-m-d" }}</div>
    <div class="article-body">
        {
           { article.body|safe }} {# 假设文章内容是安全的 HTML #}
    </div>
{% endblock main_content_area %}

{% block body_scripts %} {# 扩展 body_scripts 块 #}
    {
           { block.super }} {# 首先加载父模板的 global_analytics.js #}
    <script src="/static/js/article_comments.js"></script> {# 然后加载文章评论相关的脚本 #}
    <script>
        // 页面特定的内联脚本
        console.log("正在查看文章: {
           { article.id }}");
    </script>
{% endblock body_scripts %}

<!DOCTYPE html>
<html lang="{% get_current_language as LANGUAGE_CODE %}{
           { LANGUAGE_CODE }}"> {# 获取当前语言代码 #}
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{% block site_title %}我的全球网站{% endblock %}</title>
    {% block site_global_styles %}
        <link rel="stylesheet" href="/static/css/normalize.css">
        <link rel="stylesheet" href="/static/css/global_theme.css">
    {% endblock %}
    {% block site_extra_head %}{% endblock %}
</head>
<body>
    <div>
        <header>
            {% block site_branding %}
                <a href="/">公司Logo</a>
            {% endblock %}
            {% block site_global_nav %}
                {# 全站通用导航，可能包含语言切换等 #}
            {% endblock %}
        </header>
        <div>
            {% block site_content_wrapper %}
                <p>这是最外层的内容包装。</p>
            {% endblock %}
        </div>
        <footer>
            {% block site_footer_content %}
                <p>&copy; {% now "Y" %} Acme Corp. All rights reserved.</p>
            {% endblock %}
        </footer>
    </div>
    {% block site_global_scripts %}
        <script src="/static/js/third_party_library.js"></script>
    {% endblock %}
    {% block site_page_specific_scripts %}{% endblock %}
</body>
</html>

{% extends "site_base.html" %} {# 继承站点基础模板 #}

{% block site_title %}{% block blog_title %}博客{% endblock %} - {
           { block.super }}{% endblock %} {# 修改站点标题，并允许博客子页面进一步定义 blog_title #}

{% block site_global_styles %}
    {
           { block.super }} {# 引入 normalize.css 和 global_theme.css #}
    <link rel="stylesheet" href="/static/css/blog_theme.css"> {# 添加博客模块专属样式 #}
{% endblock %}

{% block site_global_nav %}
    {
           { block.super }} {# 保留可能的全局导航 #}
    <nav>
        <ul>
            <li><a href="{% url 'blog:post_list' %}">所有文章</a></li>
            <li><a href="{% url 'blog:category_list' %}">分类</a></li>
            {% if user.is_staff %}
                <li><a href="{% url 'admin:index' %}">管理后台</a></li> {# 假设 admin 应用的 URL #}
            {% endif %}
        </ul>
    </nav>
{% endblock %}

{% block site_content_wrapper %} {# 替换站点内容包装区域 #}
    <div class="blog-container">
        <aside>
            {% block blog_sidebar %}
                <h3>最新动态</h3>
                {# ... 最新文章、热门标签等 ... #}
            {% endblock blog_sidebar %}
        </aside>
        <main>
            {% block blog_content %}
                <p>欢迎来到博客区。</p>
            {% endblock blog_content %}
        </main>
    </div>
{% endblock %}

{% block site_page_specific_scripts %}
    {
           { block.super }} {# 保留父模板可能有的脚本 #}
    <script src="/static/js/blog_common.js"></script> {# 博客模块通用脚本 #}
{% endblock %}

{% extends "blog_base.html" %} {# 继承博客基础模板 #}
{% load humanize %} {# 加载 humanize 过滤器，例如 intcomma #}

{% block blog_title %}{
           { post.title|truncatechars:50 }}{% endblock %} {# 定义博客标题部分 #}

{% block blog_sidebar %}
    {
           { block.super }} {# 显示 blog_base.html 中定义的最新动态等 #}
    <hr>
    <h4>关于作者</h4>
    <p>{
           { post.author.username }} (共发表 {
           { post.author.posts.count }} 篇文章)</p>
{% endblock %}

{% block blog_content %} {# 填充博客主内容区域 #}
    <article class="blog-post">
        <h1>{
           { post.title }}</h1>
        <p class="meta">
            发布于 {
           { post.publish_date|naturaltime }} {# naturaltime 过滤器显示 "3小时前", "2天前" 等 #}
            {% if post.category %} | 分类: <a href="{
           { post.category.get_absolute_url }}">{
           { post.category.name }}</a>{% endif %}
        </p>
        <div class="post-body">
            {
           { post.content|safe }}
        </div>
        <div class="post-tags">
            {% for tag in post.tags.all %} {# 假设 post 有 tags 多对多字段 #}
                <a href="{% url 'blog:posts_by_tag' tag.slug %}" class="tag">{
           { tag.name }}</a>
            {% endfor %}
        </div>
    </article>
    {% include "blog/includes/comments_section.html" with post=post %} {# 引入评论区子模板 #}
{% endblock blog_content %}

{% block site_page_specific_scripts %} {# 继承自 site_base，但 blog_base 也调用了 block.super #}
    {
           { block.super }} {# 这会先加载 blog_common.js，而 blog_common.js 会先加载 third_party_library.js #}
    <script src="/static/js/blog_post_interactions.js"></script>
    <script>
        // 文章详情页特定脚本
        console.log("当前文章ID: {
           { post.id }}");
    </script>
{% endblock %}

# views.py
def my_view(request):
    if request.user.is_premium_member:
        base_template_name = 'premium_base.html'
    else:
        base_template_name = 'standard_base.html'
    return render(request, 'my_page_content.html', {
                'base_template_to_extend': base_template_name})

{# my_page_content.html #}
{% extends base_template_to_extend %} {# 动态继承父模板 #}

{% block content %}
    <p>这是特定页面的内容...</p>
{% endblock %}

{# base.html for a SPA #}
<!DOCTYPE html>
<html>
<head>
    <title>{% block title %}My SPA{% endblock %}</title>
    {% block styles %}
        <link rel="stylesheet" href="/static/dist/main.css"> {# Webpack/Vite 等打包的CSS #}
    {% endblock %}
</head>
<body>
    <div>
        {% block app_ssr_content %}{% endblock %} {# 可选：用于服务器端渲染的初始内容 #}
    </div>

    {% block initial_data_script %}
        <script type="application/json">
            {
             { initial_data_json|safe }} {# 从视图传递 JSON 数据 #}
        </script>
    {% endblock %}

    {% block scripts %}
        <script src="/static/dist/main.js"></script> {# Webpack/Vite 等打包的JS #}
    {% endblock %}
</body>
</html>

{% include "myapp/includes/header_navigation.html" %}

{# main_template.html - 假设上下文中已有 user 和 site_name #}
{% with current_section="profile" %} {# 定义一个局部变量 #}
    <p>User: {
             { user.name }}, Site: {
             { site_name }}, Section: {
             { current_section }}</p>
    {% include "myapp/includes/user_greeting.html" %} {# user_greeting.html 可以访问 user, site_name, current_section #}
{% endwith %}

{# myapp/includes/user_greeting.html #}
<p>Hello, {
             { user.name }}! Welcome to {
             { site_name }}. You are in {
             { current_section }}.</p>

{# main_template.html #}
{% include "myapp/includes/product_card.html" with product=featured_product card_theme="dark" show_rating=True %} {# 传递 product, card_theme, show_rating #}

{# myapp/includes/product_card.html #}
<div class="product-card theme-{
             { card_theme|default:'light' }}"> {# 使用传递的 card_theme，默认为 'light' #}
    <h3>{
             { product.name }}</h3>
    <p>Price: {
             { product.price }}</p>
    {% if show_rating and product.rating %} {# 使用传递的 show_rating #}
        <p>Rating: {
             { product.rating }} stars</p>
    {% endif %}
</div>

{# main_template.html - 上下文包含 site_name, user #}
{% with product_to_display=special_offer_product %}
    {% include "myapp/includes/isolated_product_display.html" with item=product_to_display display_mode="compact" only %}
    {# isolated_product_display.html 只能访问 item 和 display_mode。它不能访问 site_name 或 user。 #}
{% endwith %}

{# myapp/includes/isolated_product_display.html #}
<div class="isolated-product mode-{
             { display_mode }}">
    <h4>{
             { item.name }}</h4>
    {# <p>Welcome, {
             { user.name }}</p>  <-- 这行会出错，因为 user 没有被传递且 only 生效了 #}
</div>

{# views.py #}
# context['notification_template'] = 'notifications/email_notification.html'
# or context['notification_template'] = 'notifications/sms_notification.html'

{# main_template.html #}
{% include notification_template with notification=user_notification only %} {# notification_template 是一个变量 #}

{# myapp/includes/_form_snippet.html #}
<form method="{
               { form_method|default:'post' }}" action="{
               { form_action|default:'' }}" {% if form.is_multipart %}enctype="multipart/form-data"{% endif %}>
    {% csrf_token %} {# 确保 CSRF 令牌被包含 #}
    {
               { form.management_form }} {# 用于 formsets #}
    {% for hidden_field in form.hidden_fields %} {# 渲染隐藏字段 #}
        {
               { hidden_field }}
    {% endfor %}

    {% for field in form.visible_fields %} {# 遍历可见字段 #}
        <div class="form-group {% if field.errors %}has-error{% endif %}">
            {
               { field.label_tag }} {# 渲染字段标签 #}
            {
               { field }} {# 渲染字段本身 (input, select, textarea) #}
            {% if field.help_text %}
                <small class="form-text text-muted">{
               { field.help_text|safe }}</small> {# 显示帮助文本 #}
            {% endif %}
            {% for error in field.errors %} {# 显示字段级错误 #}
                <div class="invalid-feedback">{
               { error }}</div>
            {% endfor %}
        </div>
    {% endfor %}

    {% if form.non_field_errors %} {# 显示表单级错误 #}
        <div class="alert alert-danger">
            {% for error in form.non_field_errors %}
                <p>{
               { error }}</p>
            {% endfor %}
        </div>
    {% endif %}

    <button type="submit" class="btn btn-primary">{
               { submit_button_text|default:'提交' }}</button>
</form>

{# 在其他模板中使用 #}
{# {% include "myapp/includes/_form_snippet.html" with form=my_user_profile_form submit_button_text="更新资料" only %} #}

{% if messages %} {# 检查是否有任何消息 #}
    <div class="messages-container" aria-live="polite" aria-atomic="true"> {# ARIA属性增强可访问性 #}
        {% for message in messages %} {# 遍历所有消息 #}
            {# message.tags 通常包含消息级别，如 "debug", "info", "success", "warning", "error" #}
            {# 这些可以用来映射到 Bootstrap 或其他 CSS 框架的警告框类名 #}
            <div class="alert alert-{
           { message.level_tag }} alert-dismissible fade show" role="alert"> {# 使用消息级别作为CSS类 #}
                {
           { message|safe }} {# 显示消息内容，通常消息内容是安全的 #}
                <button type="button" class="close" data-dismiss="alert" aria-label="Close">
                    <span aria-hidden="true">&times;</span>
                </button>
            </div>
        {% endfor %}
    </div>
    {# 清除已显示的消息，防止它们在后续的 include 中再次出现（通常 Django 自动处理，但显式操作无害） #}
    {# {% get_messages as messages %}  <-- This is not standard DTL, message consumption happens automatically. #}
{% endif %}

{# base.html #}
<body>
    <header>...</header>
    {% include "myapp/includes/_messages.html" %} {# 在页面顶部（或合适位置）包含消息显示模板 #}
    <main>
        {% block content %}{% endblock %}
    </main>
    <footer>...</footer>
</body>

from django.contrib import messages
from django.shortcuts import render, redirect

def my_form_view(request):
    if request.method == 'POST':
        form = MyForm(request.POST)
        if form.is_valid():
            form.save()
            messages.success(request, '您的信息已成功保存！') # 添加成功消息
            return redirect('some_success_url')
        else:
            messages.error(request, '表单提交失败，请检查错误。') # 添加错误消息
    else:
        form = MyForm()
    return render(request, 'my_form_template.html', {
            'form': form})

def another_view(request):
    # ...
    messages.info(request, '这是一条提示信息。') # 添加提示消息
    return render(request, 'another_template.html')

{% load library_name1 library_name2 ... %}

{% load specific_tag_or_filter from library_name %}

{% load static %} {# 加载 static 标签库 #}
<link rel="stylesheet" href="{% static 'myapp/css/style.css' %}"> {# 生成指向 style.css 的URL #}
<img src="{% static 'myapp/images/logo.png' %}">

{% load i18n %} {# 加载 i18n 标签库 #}

<p>{% trans "Welcome to our website!" %}</p> {# 翻译字符串 #}

{% blocktrans count counter=item_count %} {# 处理单复数形式的翻译 #}
There is one item.
{% plural %}
There are {
               { counter }} items.
{% endblocktrans %}

<p>Date: {
               { some_date_variable|date:"SHORT_DATE_FORMAT" }}</p> {# 本地化日期格式 #}

{% localize on %} {# 开启区域感知格式化 #}
    <p>Value: {
               { some_number_variable }}</p> {# 数字会根据当前区域设置格式化，例如使用逗号或点作为千位分隔符 #}
{% endlocalize %}

{% load humanize %} {# 加载 humanize 过滤器库 #}

<p>Total users: {
               { user_count|intcomma }}</p> {# 例如：1,234,567 #}
<p>Large number: {
               { very_large_number|intword }}</p> {# 例如：1.2 million #}
<p>Article published: {
               { article.publish_date|naturaltime }}</p> {# 例如：2 hours ago #}
<p>Event date: {
               { event.date|naturalday }}</p> {# 例如：tomorrow #}

{% load tz %} {# 加载 tz 标签库 #}

<p>Current time (UTC): {
               { utc_now_variable }}</p> {# 假设 utc_now_variable 是一个UTC的datetime对象 #}

{% timezone "America/New_York" %} {# 切换到纽约时区 #}
    <p>Event starts at (New York Time): {
               { event_datetime_utc|date:"Y-m-d H:i:s T" }}</p> {# event_datetime_utc 会被转换为纽约时间显示 #}
{% endtimezone %} {# 恢复到之前的时区 #}

{% localtime on %} {# 开启本地时间转换（基于 TIME_ZONE 设置或当前激活的时区） #}
    <p>Server time in local: {
               { server_datetime_aware|date:"H:i" }}</p>
{% endlocaltime %}

<p>Back to default timezone: {
               { utc_now_variable|date:"Y-m-d H:i:s T" }}</p>

# myapp/templatetags/myapp_extras.py
from django import template
from django.utils.html import format_html
from django.utils.safestring import mark_safe
import datetime

register = template.Library() # 必须将实例命名为 register

# myapp/templatetags/myapp_extras.py
# ... (register = template.Library()) ...

@register.filter(name='cut_string') # 注册名为 cut_string 的过滤器
def cut_string_filter(value, arg):
    """Removes all values of arg from the given string"""
    return value.replace(str(arg), '')

@register.filter
def to_lowercase(value): # 过滤器名将是 to_lowercase
    """Converts a string to all lowercase."""
    return str(value).lower()

@register.filter(is_safe=True) # is_safe=True 表示过滤器不会引入不安全的HTML
def highlight_text(value, query):
    """Highlights occurrences of query in value, marked as safe."""
    # 注意：这个实现非常基础，实际中可能需要更复杂的HTML转义和处理
    # 确保 query 本身是安全的，或者在使用前进行清理
    highlighted_value = str(value).replace(
        str(query),
        f'<strong class="highlight">{
                str(query)}</strong>'
    )
    return mark_safe(highlighted_value) # 使用 mark_safe 告诉 Django 这是安全的 HTML

# myapp/templatetags/myapp_extras.py
# ... (register = template.Library()) ...

@register.simple_tag # 标签名将是 current_time_formatted
def current_time_formatted(format_string="%b %d %Y, %I:%M %p"):
    """Returns the current time formatted according to the given format string."""
    return datetime.datetime.now().strftime(format_string)

@register.simple_tag(takes_context=True) # takes_context=True 使标签可以访问当前模板上下文
def user_greeting_banner(context, greeting_message="Welcome"):
    """Displays a greeting banner with the username from context."""
    user = context.get('user') # 从上下文中获取 user 对象
    username = user.username if user and user.is_authenticated else "Guest"
    banner_html = f'<div class="banner">{
                greeting_message}, {
                username}!</div>'
    return mark_safe(banner_html) # 返回安全的 HTML

# myapp/templatetags/myapp_extras.py
# ... (register = template.Library()) ...

@register.inclusion_tag('myapp/includes/_user_profile_card.html', takes_context=True) # 指定要渲染的模板
def show_user_profile_card(context, user_object=None):
    """Renders a user profile card using the provided user_object or user from context."""
    target_user = user_object if user_object else context.get('user')
    if not target_user or not target_user.is_authenticated:
        return {
              'display_card': False} # 如果没有有效用户，可以不显示卡片

    # 准备传递给 _user_profile_card.html 的上下文
    profile_data = {
              
        'display_card': True,
        'username': target_user.username,
        'email': target_user.email,
        'full_name': target_user.get_full_name(),
        'join_date': target_user.date_joined,
        'profile_picture_url': getattr(target_user, 'profile_picture_url', '/static/images/default_avatar.png')
    }
    return profile_data

{% if display_card %}
    <div class="user-profile-card">
        <img src="{
             { profile_picture_url }}">{ username }}'s profile picture">
        <h4>{
             { full_name|default:username }}</h4>
        <p>Email: {
             { email }}</p>
        <p>Joined: {
             { join_date|date:"M d, Y" }}</p>
    </div>
{% else %}
    {# <p>User profile card cannot be displayed.</p> #}
{% endif %}

{% load myapp_extras %} {# 加载 myapp_extras.py 中定义的所有标签和过滤器 #}
{% load static %} {# 也可以同时加载其他库 #}

<p>Original: Some sample text with removable parts.</p>
<p>Cut: {
             { "Some sample text with removable parts."|cut_string:"removable" }}</p> {# 使用 cut_string 过滤器 #}
<p>Lowercase: {
             { "This Should Be Lowercase"|to_lowercase }}</p> {# 使用 to_lowercase 过滤器 #}
<p>Highlighted: {
             { "Search for the word 'Python' in this Python text."|highlight_text:"Python" }}</p>

<p>Current server time: {% current_time_formatted "%Y-%m-%d %H:%M:%S" %}</p> {# 使用 simple_tag，并传递参数 #}
<p>Default time format: {% current_time_formatted %}</p> {# 使用 simple_tag 的默认参数 #}

{% user_greeting_banner "Hello there" %} {# 使用带上下文的 simple_tag #}

{# 使用 inclusion_tag 来显示当前登录用户的卡片 #}
{% show_user_profile_card %}

{# 假设有一个 specific_user 对象，为该用户显示卡片 #}
{% if specific_user_profile %}
    <h4>Profile for {
             { specific_user_profile.username }}:</h4>
    {% show_user_profile_card user_object=specific_user_profile %}
{% endif %}

# myapp/urls.py
from django.urls import path
from . import views

app_name = 'myapp' # 应用命名空间 (推荐)

urlpatterns = [
    path('home/', views.home_view, name='home'), # 名为 'home'
    path('articles/<int:year>/<int:month>/', views.article_archive, name='article_archive_monthly'), # 名为 'article_archive_monthly'
    path('product/<slug:product_slug>/', views.product_detail, name='product_detail'), # 名为 'product_detail'
    path('profile/<str:username>/', views.user_profile, name='user_profile'),
]

{% url 'url_name_string' [arg1 arg2 ...] [kwarg1=value1 kwarg2=value2 ...] %}

# myapp/urls.py
from django.urls import path
from . import views

app_name = 'myapp' # 应用命名空间

urlpatterns = [
    path('', views.index_view, name='index'), # 首页，无参数
    path('contact-us/', views.contact_view, name='contact'), # 联系页面，无参数
    path('item/<int:item_id>/details/', views.item_detail_view, name='item_detail'), # 带一个整数参数 item_id
    path('category/<slug:category_slug>/product/<uuid:product_uuid>/', views.category_product_view, name='category_product'), # 带 slug 和 uuid 参数
    path('search/', views.search_view, name='search_results'), # 用于处理带查询参数的URL，但URL本身无路径参数
]

# project/urls.py
from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('app/', include('myapp.urls', namespace='main_app')), # 包含 myapp.urls 并指定实例命名空间 'main_app'
    # 假设还有一个没有命名空间的 include
    # path('legacy/', include('legacy_app.urls')),
]

{# 假设在 myapp 应用的模板中 #}

{# 1. 无参数的URL #}
<a href="{% url 'myapp:index' %}">返回首页 (myapp)</a> {# 正确引用 myapp:index #}
<a href="{% url 'main_app:contact' %}">联系我们 (main_app:contact)</a> {# 通过实例和应用命名空间引用 #}

{# 2. 带位置参数的URL #}
{% with item_object_id=123 %} {# 假设 item_object_id 是一个变量 #}
    <a href="{% url 'myapp:item_detail' item_object_id %}">查看商品 {
           { item_object_id }} 详情 (位置参数)</a>
    {# Django 会生成类似 /app/item/123/details/ 的URL (取决于 project/urls.py 中的 'app/' 前缀) #}
{% endwith %}

{# 3. 带关键字参数的URL #}
{% with current_item_id=456 %}
    <a href="{% url 'myapp:item_detail' item_id=current_item_id %}">查看商品 {
           { current_item_id }} 详情 (关键字参数)</a>
    {# 效果同上，推荐使用关键字参数，更清晰 #}
{% endwith %}

{# 4. 带多个关键字参数的URL #}
{% with current_category="electronics" current_product_guid="a1b2c3d4-e5f6-7890-1234-567890abcdef" %}
    <a href="{% url 'myapp:category_product' category_slug=current_category product_uuid=current_product_guid %}">
        查看 {
           { current_category }} 类别的产品 {
           { current_product_guid }}
    </a>
    {# 会生成类似 /app/category/electronics/product/a1b2c3d4-e5f6-7890-1234-567890abcdef/ 的URL #}
{% endwith %}

{# 5. 混合使用位置参数和关键字参数 (不推荐，容易混淆，但技术上可行，只要不冲突) #}
{# 对于 path('archive/<int:year>/<slug:month_slug>/', views.archive, name='archive_by_month') #}
{# {% url 'myapp:archive_by_month' 2024 month_slug='jan' %}  (位置参数优先匹配未命名组或按顺序匹配命名组) #}
{# {% url 'myapp:archive_by_month' year=2024 'jan' %} (如果可以，不推荐) #}
{# 最佳实践是：如果URL模式中的所有捕获组都是命名的，则始终使用关键字参数传递给 {% url %}。如果都是未命名的，则使用位置参数。 #}

{# 6. URL 不直接接收路径参数，但可能用于构建带查询字符串的链接 #}
{# {% url %} 只负责生成 path 部分。查询字符串 (?key=value) 需要手动附加或通过其他方式。 #}
<form action="{% url 'myapp:search_results' %}" method="get"> {# 生成 /app/search/ #}
    <input type="text" name="q" placeholder="搜索...">
    <button type="submit">搜索</button>
</form>

{# 7. 处理实例命名空间 #}
{# 如果在 project/urls.py 中是这样 include 的: path('app/', include('myapp.urls', namespace='main_app')) #}
{# 那么在模板中引用 myapp 下的URL时，需要带上实例命名空间 #}
<a href="{% url 'main_app:index' %}">首页 (通过实例 'main_app' 和应用 'myapp' (隐式) )</a>
{# 如果 myapp/urls.py 中没有 app_name，则为: {% url 'main_app:index' %} #}
{# 如果 myapp/urls.py 中有 app_name='myapp'，则为: {% url 'main_app:myapp:index' %} 这种用法较少见，通常app_name足够 #}
{# 最常见的是 {% url 'app_namespace:view_name' %} 或 {% url 'instance_namespace:view_name' %} (如果应用内部没有app_namespace) #}
{# 或者 {% url 'instance_namespace:app_namespace:view_name' %} (如果两者都有且需要明确) #}
{# Django 会尝试解析，通常 'instance_namespace:view_name' 或 'app_namespace:view_name' 能够工作，具体取决于你的URL配置的复杂程度。 #}
{# 推荐：应用内部使用 app_name，在项目级 include 时，如果同一个 app 被多次 include，则使用 instance namespace。 #}
{# 引用时，优先使用 'app_name:view_name'。如果存在实例命名空间，则 'instance_name:view_name'。 #}

{# 假设一个URL的name是全局唯一的 (不推荐，容易冲突) #}
{# 如果 urls.py 是 path('global-unique-url/', views.some_view, name='global_view_name') #}
{# {% url 'global_view_name' %} #}

{% url 'myapp:product_detail' product_slug=product.slug as detail_url %} {# 将生成的URL存储在 detail_url 变量中 #}

<a href="{
           { detail_url }}">查看 {
           { product.name }}</a>

{% if user.is_staff %}
    <a href="{
           { detail_url }}?edit=true">编辑 (员工)</a> {# 复用 detail_url 并添加查询参数 #}
{% endif %}

<meta property="og:url" content="{% get_current_site %}{
           { detail_url }}"> {# 在 meta 标签中使用 #}

{% comment %}
   假设有一个复杂的URL，多次在不同地方使用，
   或者需要传递给一个 include 的子模板。
{% endcomment %}
{% url 'myapp:category_product' category_slug="laptops" product_uuid=laptop_product.uuid as laptop_product_url %}

<div class="main-link">
    <a href="{
           { laptop_product_url }}">主要链接到笔记本电脑</a>
</div>

{% include "myapp/includes/share_buttons.html" with share_url=laptop_product_url only %}

{# _navigation.html #}
<nav>
    <ul>
        <li><a href="{% url 'main_app:index' %}" class="{% if request.resolver_match.view_name == 'main_app:index' %}active{% endif %}">首页</a></li> {# request.resolver_match.view_name 可以用于判断当前页面是否匹配某个URL名称 #}
        <li><a href="{% url 'main_app:contact' %}" class="{% if request.resolver_match.view_name == 'main_app:contact' %}active{% endif %}">联系</a></li>
        {% if user.is_authenticated %}
            <li><a href="{% url 'accounts:profile' username=user.username %}">我的账户</a></li> {# 假设有 'accounts' 应用和对应的URL #}
            <li><a href="{% url 'accounts:logout' %}">登出</a></li>
        {% else %}
            <li><a href="{% url 'accounts:login' %}?next={
             { request.path|urlencode }}">登录</a></li> {# 登录后跳转回当前页 #}
        {% endif %}
    </ul>
</nav>

<form method="post" action="{% url 'myapp:submit_feedback' %}">
    {% csrf_token %}
    {
             { form.as_p }}
    <button type="submit">提交反馈</button>
</form>

<a href="{% url 'accounts:login' %}?next={% url 'myapp:user_dashboard' as dashboard_url %}{
             { dashboard_url|urlencode }}">
    登录后访问仪表盘
</a>

# models.py
from django.db import models
from django.urls import reverse

class Product(models.Model):
    name = models.CharField(max_length=100)
    slug = models.SlugField(unique=True)
    # ... other fields ...

    def get_absolute_url(self):
        return reverse('myapp:product_detail', kwargs={
                'product_slug': self.slug})

<a href="{
               { product_instance.get_absolute_url }}">查看 {
               { product_instance.name }}</a>

<input type="hidden" name="csrfmiddlewaretoken" value="a_long_random_looking_string_here">

<form method="post" action="{% url 'some_app:some_action' %}">
    {% csrf_token %} {# 必须放在 <form> 标签内部 #}

    {# ... 其他表单字段 ... #}
    {
           { form.as_p }}

    <button type="submit">提交</button>
</form>

{# template_with_form.html #}
<h2>提交您的反馈</h2>
<form method="post" action="{% url 'myapp:submit_feedback' %}"> {# 表单提交到 myapp:submit_feedback URL #}
    {% csrf_token %} {# 插入CSRF令牌隐藏字段 #}

    <label for="id_name">您的名字:</label>
    <input type="text" name="name" required>
    <br>
    <label for="id_feedback">反馈内容:</label>
    <textarea name="feedback_text" rows="4" required></textarea>
    <br>
    <button type="submit">发送反馈</button>
</form>

{% if submitted_feedback %} {# 假设视图在成功后传递此变量 #}
    <p>感谢您的反馈：“{
           { submitted_feedback }}”</p>
{% endif %}

# myapp/views.py
from django.shortcuts import render
from django.http import HttpResponse

# 假设有一个简单的模型或存储反馈的地方
feedback_storage = []

def submit_feedback_view(request):
    submitted_text = None
    if request.method == 'POST':
        # CSRF验证已由 CsrfViewMiddleware 在此之前自动完成
        # 如果CSRF验证失败，视图代码根本不会执行，会直接返回403
        name = request.POST.get('name', '匿名')
        feedback = request.POST.get('feedback_text', '')
        if feedback:
            full_feedback = f"{
              name} 说: {
              feedback}"
            feedback_storage.append(full_feedback)
            submitted_text = feedback # 用于在模板中显示
            print(f"收到反馈: {
              full_feedback}") # 在服务器端打印
        # 通常这里会进行表单验证、数据保存等操作，然后重定向
        # return redirect('myapp:feedback_success')
    return render(request, 'template_with_form.html', {
            'submitted_feedback': submitted_text})

{# <script>const csrfToken = "{
             { csrf_token }}";</script>  <-- 这样不行，csrf_token 是一个标签，不是直接的值 #}
{# 正确做法是从cookie或DOM中已有的 input[name=csrfmiddlewaretoken] 获取 #}

function getCookie(name) {
              
    let cookieValue = null;
    if (document.cookie && document.cookie !== '') {
              
        const cookies = document.cookie.split(';');
        for (let i = 0; i < cookies.length; i++) {
              
            const cookie = cookies[i].trim();
            // Does this cookie string begin with the name we want?
            if (cookie.substring(0, name.length + 1) === (name + '=')) {
              
                cookieValue = decodeURIComponent(cookie.substring(name.length + 1));
                break;
            }
        }
    }
    return cookieValue;
}
const csrftoken = getCookie('csrftoken'); // 获取名为 'csrftoken' 的cookie值

// 使用 Fetch API 示例
fetch("{% url 'myapp:ajax_action' %}", {
               // 使用 {% url %} 生成AJAX请求的目标URL
    method: 'POST',
    headers: {
              
        'Content-Type': 'application/json',
        'X-CSRFToken': csrftoken, // 设置 X-CSRFToken 头部
        // 'X-Requested-With': 'XMLHttpRequest' // 有时也需要此头部，表明是AJAX请求
    },
    body: JSON.stringify({
               key: 'value' })
})
.then(response => {
              
    if (!response.ok) {
              
        if (response.status === 403) {
              
            console.error("CSRF verification failed or other permission issue.");
        }
        throw new Error('Network response was not ok ' + response.statusText);
    }
    return response.json();
})
.then(data => {
              
    console.log('Success:', data);
})
.catch((error) => {
              
    console.error('Error:', error);
});

// 使用 jQuery AJAX 示例
/*
$.ajax({
    url: "{% url 'myapp:ajax_action' %}",
    type: "POST",
    data: { my_data: "some value" },
    beforeSend: function(xhr) {
        xhr.setRequestHeader("X-CSRFToken", csrftoken);
    },
    success: function(response) {
        console.log("jQuery AJAX success:", response);
    },
    error: function(xhr, errmsg, err) {
        console.log("jQuery AJAX error:", xhr.status + ": " + xhr.responseText);
        if (xhr.status === 403) {
            alert("CSRF token error or permission denied.");
        }
    }
});
*/

from django.views.decorators.csrf import csrf_exempt
from django.http import HttpResponse

@csrf_exempt # 对此视图禁用CSRF保护
def external_webhook_receiver(request):
    if request.method == 'POST':
        # 处理来自外部服务的POST数据
        # 注意：由于禁用了CSRF，需要其他方式验证请求的合法性，如签名、IP白名单等
        return HttpResponse("Webhook received.", status=200)
    return HttpResponse("Please POST data.", status=400)

from django.views.decorators.csrf import ensure_csrf_cookie
from django.shortcuts import render

@ensure_csrf_cookie # 确保CSRF cookie被发送
def spa_entry_point_view(request):
    # 这个视图渲染一个单页应用的骨架，其中表单和AJAX请求由JS处理
    return render(request, 'spa_base.html')

{# 这是一个单行注释，它不会被渲染到最终的HTML输出中 #}

<p>Hello, {
           { user.name }}! {# 显示用户名 #}</p>

{#
    这也可以看作是一个多行注释，
    只要所有内容都在 {# 和 #} 之间。
    每一行都会被忽略。
#}

{% if user.is_authenticated %} {# 检查用户是否登录 #}
    {# 用户已登录，显示欢迎信息 #}
    <p>Welcome back!</p>
{% else %}
    {# 用户未登录，显示登录链接 #}
    <a href="{% url 'login' %}">Login</a>
{% endif %}

{% comment %}
    这里是块级注释的开始。
    下面这段代码将被完全忽略，直到 {% endcomment %} 标签出现。

    <div class="old-feature">
        <h3>旧功能标题</h3>
        <p>旧功能的描述: {
           { old_data.description }}</p>
        {% for item in old_data.items %}
            <li>{
           { item }}</li>
        {% endfor %}
    </div>

    这个注释可以跨越多行，并且可以包含其他的Django模板标签、HTML等，
    它们都不会被解析或渲染。
{% endcomment %}

<p>这部分内容会正常渲染。</p>

{# 你也可以给 comment 标签一个可选的 "note" 参数，它会被忽略，但可以用于标记注释的目的 #}
{% comment "Temporary removal of experimental feature for v2.1 release" %}
    <section class="experimental-feature">
        {% if flags.enable_beta_feature_X %}
            <h4>实验性特性 X</h4>
            <!-- 此处是 HTML 注释，会被发送到浏览器 -->
            <p>此特性仍在测试中。</p>
        {% endif %}
    </section>
{% endcomment %}

{# DTL单行注释：解释下面的变量 #}
{% with company_name="ACME Corp" %}
    <h1>Welcome to {
           { company_name }}</h1> {# company_name在块内可用 #}

    <!-- HTML注释：这个标题对SEO很重要 -->
    <h2>Our Products</h2>

    {% comment "TODO: Implement dynamic product listing from database in v2" %}
        <div class="product-list-placeholder">
            <p>产品列表将显示在此处。</p>
            {# DTL注释：当前是静态占位符 #}
            <!-- HTML注释：产品项将会是<li>元素 -->
        </div>
    {% endcomment %}

    <p>Current year: {% now "Y" %}</p> {# 使用 now 标签获取年份 #}
    {# {% include "old_footer.html" %} <-- 使用DTL注释临时禁用include #}
{% endwith %}

{# 根据用户角色和订阅状态决定显示哪个仪表盘版本 #}
{% if user.is_superuser %}
    {% include "dashboards/admin_dashboard.html" %}
{% elif user.is_authenticated and user.subscription.is_active and user.subscription.level == "premium" %}
    {# 高级用户显示完整功能的仪表盘 #}
    {% include "dashboards/premium_dashboard.html" with stats=user.get_premium_stats %}
{% elif user.is_authenticated %}
    {# 普通登录用户显示基础仪表盘 #}
    {% include "dashboards/basic_dashboard.html" %}
{% else %}
    {# 未登录用户提示 #}
    <p>请登录查看您的仪表盘。</p>
{% endif %}

{# FIXME: 这里的价格显示没有考虑税费，需要在视图中处理或使用过滤器 (JIRA-123) #}
<p>Price: {
             { product.price }}</p>

{# TODO: 添加用户头像上传功能 (v2.1) #}
<img src="{
             { user.profile.avatar_url|default:'/static/images/default_avatar.png' }}">

{% comment "A/B Test: Variant B for new checkout button - disabled for now" %}
    <button class="checkout-button-variant-b">Proceed to Checkout (New)</button>
{% endcomment %}
<button class="checkout-button-variant-a">Checkout</button>

{% comment %}
    v1.0 (2022-01-15): 初始版本
    v1.5 (2023-03-10): 重构了导航栏，使用了新的 include 片段 _navbar_v2.html
                       旧导航 {% include "_navbar_v1.html" %} 已被移除。
{% endcomment %}