Django模板变量语法与高级应用指南-代码聚汇网

Django模板变量语法与高级应用指南

芙蓉塘外有轻雷·2026-07-08·阅读 60 GEO检测（免费）

Django模板模板变量模板过滤器

|难度：普通|阅读约 13 分钟

1. Django模板变量基础语法与工作原理

在Django模板系统中，变量是最基础也最常用的元素。它的基本语法形式是双大括号包裹变量名：{{ variable }}。当模板引擎遇到这种结构时，会按照特定顺序查找并评估该变量，最终用实际值替换这个占位符。

变量名称的命名规则比较灵活：

允许使用字母、数字和下划线的任意组合
不能以数字开头
不能以下划线开头（这类变量通常被视为私有属性）
不能包含空格或标点符号（除了特殊的点号"."）

点号在Django模板变量中有特殊含义，它用于访问变量的属性。当遇到{{ user.name }}这样的表达式时，模板引擎会按照以下顺序进行查找：

字典查找：先检查变量是否是字典类型，并尝试获取name键对应的值
属性或方法查找：如果不是字典或键不存在，则尝试获取对象的name属性
数字索引查找：如果前两步都失败，且name是数字，会尝试作为列表/元组的索引

重要提示：如果查找结果是可调用对象（如方法），模板引擎会自动调用它（不带参数）并使用返回值。这意味着你不需要在模板中显式地加上括号来调用方法。

一个实际例子：

html复制<!-- 假设context中有个article对象，它有title属性和get_author()方法 -->
<h1>{{ article.title }}</h1>
<p>作者：{{ article.get_author }}</p>  <!-- 注意这里没有括号 -->

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 变量查找的深度解析与常见陷阱

2.1 查找顺序的潜在问题

Django的变量查找顺序虽然直观，但在某些特殊情况下可能导致意外行为。例如，当使用collections.defaultdict时：

python复制# 视图代码
from collections import defaultdict
context = {
    'defaultdict': defaultdict(int, {'items': 'custom_value'})
}

html复制<!-- 模板代码 -->
{{ defaultdict.items }}  <!-- 这里会返回0而不是'custom_value' -->

这是因为字典查找优先于方法调用，而defaultdict的特性会导致它返回默认值0，而不是调用items()方法。解决方法是在视图中先转换为普通字典：

python复制context = {
    'defaultdict': dict(defaultdict(int, {'items': 'custom_value'}))
}

2.2 处理不存在的变量

当模板引用不存在的变量时，Django的处理方式取决于配置：

默认情况下，会插入空字符串('')
可以通过设置string_if_invalid来改变这一行为（在settings.py中）

python复制# settings.py
TEMPLATES = [
    {
        'OPTIONS': {
            'string_if_invalid': 'INVALID_VARIABLE',
        },
    },
]

2.3 变量作用域的特殊情况

在模板继承和包含中，变量作用域有以下特点：

父模板中定义的变量对子模板可见
include引入的模板可以访问当前模板的所有变量
with标签可以创建局部变量作用域

html复制{% with total=products|length %}
    <p>共有{{ total }}件商品</p>
    {% include "product_list.html" %}  <!-- 也能访问total变量 -->
{% endwith %}

3. 模板过滤器：增强变量输出的利器

3.1 基本过滤器语法

过滤器通过管道符(|)应用于变量，基本形式为{{ variable|filter }}。Django内置了约60个过滤器，常用的包括：

default：变量为假时使用默认值

html复制{{ value|default:"nothing" }}  <!-- 当value为False/None/空时显示"nothing" -->

length：获取长度

html复制{{ list|length }}  <!-- 返回列表元素个数 -->

filesizeformat：格式化文件大小

html复制{{ 1024|filesizeformat }}  <!-- 输出"1.0 KB" -->

3.2 过滤器链与参数传递

过滤器可以串联使用，前一个的输出作为后一个的输入：

html复制{{ text|escape|linebreaks }}  <!-- 先转义HTML，再把换行转为<br> -->

带参数的过滤器使用冒号(:)分隔：

html复制{{ text|truncatewords:30 }}  <!-- 截断到30个单词 -->
{{ list|join:", " }}  <!-- 用逗号+空格连接列表 -->

3.3 创建自定义过滤器

虽然Django内置过滤器很丰富，但有时需要自定义。创建步骤：

在app目录下创建templatetags文件夹
添加__init__.py文件（空文件即可）
创建过滤器模块，如custom_filters.py：

python复制from django import template

register = template.Library()

@register.filter
def add_prefix(value, prefix):
    return f"{prefix}{value}"

使用自定义过滤器前需要先加载：

html复制{% load custom_filters %}
{{ username|add_prefix:"user_" }}

4. 高级变量操作技巧与最佳实践

4.1 安全处理HTML内容

Django默认会自动转义HTML特殊字符，防止XSS攻击。但有时需要输出原始HTML：

html复制{{ html_content|safe }}  <!-- 标记为安全，不转义 -->

或者控制整个区块的转义行为：

html复制{% autoescape off %}
    {{ untrusted_html }}  <!-- 这里的内容不会被自动转义 -->
{% endautoescape %}

4.2 高效访问关联数据

Django模板可以方便地访问模型关联：

html复制<!-- 访问外键关联对象 -->
<p>作者：{{ article.author.name }}</p>

<!-- 访问多对多关系 -->
<ul>
{% for tag in article.tags.all %}
    <li>{{ tag.name }}</li>
{% endfor %}
</ul>

<!-- 访问反向关联 -->
<h3>这篇文章的评论({{ article.comment_set.count }})：</h3>

4.3 使用`with`创建临时变量

对于复杂表达式，可以使用with创建临时变量提高可读性：

html复制{% with full_name=user.first_name|add:" "|add:user.last_name %}
    <p>欢迎，{{ full_name }}!</p>
{% endwith %}

4.4 模板片段复用（Django 6.0+新特性）

Django 6.0引入了模板片段(partials)功能，可以定义可复用的模板块：

html复制{% partialdef user-card %}
    <div class="card">
        <h3>{{ user.name }}</h3>
        <p>{{ user.bio|truncatewords:20 }}</p>
    </div>
{% endpartialdef %}

<!-- 在模板中多次使用 -->
{% partial user-card %}

还可以单独渲染片段用于AJAX请求：

python复制# 视图代码
return render(request, "template.html#user-card", {"user": user})

5. 实战经验与性能优化

5.1 避免在模板中进行复杂计算

虽然模板语言支持方法调用，但应避免：

html复制<!-- 不推荐 -->
{{ article.get_comments().filter(approved=True).count }}

<!-- 推荐在视图中预处理 -->
context = {
    'approved_comments_count': article.get_comments().filter(approved=True).count()
}

5.2 使用`select_related`和`prefetch_related`优化查询

对于模板中频繁访问的关联数据：

python复制# 视图代码
articles = Article.objects.select_related('author').prefetch_related('tags')

这样可以减少模板渲染时的数据库查询次数。

5.3 调试模板变量

当变量不按预期显示时，可以使用debug过滤器检查：

html复制{{ variable|pprint }}  <!-- 漂亮打印变量内容 -->
{{ variable|dir }}     <!-- 查看变量可用属性和方法 -->

或者在视图中检查模板上下文：

python复制from django.template import Template, Context
template = Template("...")
context = Context({...})
print(template.render(context))  # 查看渲染结果

5.4 处理日期和时间

Django提供了丰富的日期时间格式化过滤器：

html复制{{ value|date:"Y-m-d" }}  <!-- 2023-07-15 -->
{{ value|time:"H:i" }}    <!-- 14:30 -->
{{ value|timesince }}     <!-- 3天，2小时 -->

对于时区处理，确保USE_TZ = True，并在视图中使用时区感知的datetime对象。