Django包含标签（include tag）[编辑 | 编辑源代码]

Django包含标签（{% include %}）是Django模板系统中用于实现模板代码复用的核心功能，允许开发者将重复使用的模板片段分离为独立文件，并通过声明式语法嵌入到其他模板中。该机制遵循DRY（Don't Repeat Yourself）原则，显著提升模板的可维护性。

基础概念[编辑 | 编辑源代码]

包含标签的工作原理类似于编程语言中的"模块导入"——当一个模板通过{% include %}引用另一个模板时：

Django模板引擎会将被引用的模板内容直接插入到当前模板的调用位置
被包含的模板可以访问当前模板的所有上下文变量
支持动态路径（通过变量指定模板名称）

基本语法[编辑 | 编辑源代码]

{% include "path/to/template.html" %}

参数详解[编辑 | 编辑源代码]

包含标签支持三种参数形式：

参数类型	示例	说明
硬编码路径	`{% include "header.html" %}`	直接指定模板路径
变量路径	`{% include template_name %}`	通过上下文变量动态指定
带额外上下文	`{% include "item.html" with product=current_item %}`	向被包含模板传递独立上下文

上下文继承示例[编辑 | 编辑源代码]

主模板：

<!-- main_template.html -->
{% with title="Home Page" %}
    {% include "header.html" %}
{% endwith %}

被包含模板：

<!-- header.html -->
<h1>{{ title }}</h1>  {# 输出: <h1>Home Page</h1> #}

高级用法[编辑 | 编辑源代码]

条件包含[编辑 | 编辑源代码]

通过only参数限制上下文传递：

{% include "sidebar.html" only %}  {# 阻止上下文变量泄漏 #}

动态包含流程[编辑 | 编辑源代码]

实际应用案例[编辑 | 编辑源代码]

案例1：跨页面公共头部[编辑 | 编辑源代码]

创建可复用的导航栏模板：

<!-- nav_bar.html -->
<nav class="navbar">
    <a href="/">Home</a>
    <a href="/blog/">Blog</a>
    {% if user.is_authenticated %}
        <a href="/logout/">Logout</a>
    {% endif %}
</nav>

在页面模板中引用：

<!-- home.html -->
<!DOCTYPE html>
<html>
<head>...</head>
<body>
    {% include "nav_bar.html" %}
    <main>...</main>
</body>
</html>

案例2：动态组件加载[编辑 | 编辑源代码]

电商网站的商品卡片组件：

<!-- product_card.html -->
<div class="card">
    <h3>{{ product.name }}</h3>
    <p>Price: ${{ product.price }}</p>
    <button>Add to Cart</button>
</div>

列表页中的调用方式：

<!-- product_list.html -->
{% for product in products %}
    {% include "product_card.html" with product=product %}
{% endfor %}

性能考量[编辑 | 编辑源代码]

Django处理包含标签时会： 1. 检查TEMPLATES配置中的模板加载器 2. 根据APP_DIRS设置搜索应用目录 3. 缓存已编译的模板（默认开启）

数学表达式的渲染效率对比： $O (n) 基础包含 < O (n^{2}) 嵌套包含$

最佳实践[编辑 | 编辑源代码]

将重复使用的UI组件拆分为包含模板（按钮、表单控件等）
避免超过3层的嵌套包含
对高频使用的片段考虑使用{% static %}标签
在团队开发中建立统一的包含模板命名规范（如components/目录）

错误处理[编辑 | 编辑源代码]

当被包含模板不存在时：

默认行为：静默失败（渲染空字符串）
可通过TEMPLATES配置中的OPTIONS['debug']开启调试信息

强制报错模式：

{% include "missing.html" ignore missing=False %}  {# Django 3.0+ #}

与其他模板标签对比[编辑 | 编辑源代码]

标签	复用级别	上下文传递	适用场景
`include`	模板级	自动继承/手动指定	UI组件
`extends`	页面级	完全继承	基础布局
`block`	片段级	块内继承	布局可变区域

版本变化[编辑 | 编辑源代码]

Django 1.11：新增only参数
Django 3.0：引入ignore missing参数
Django 4.2：优化包含模板的缓存机制