django-template-partials快速上手：可复用命名partial的安装与第一个示例

django-template-partials快速上手：可复用命名partial的安装与第一个示例

【免费下载链接】django-template-partials Reusable named inline partials for the Django Template Language. 项目地址: https://gitcode.com/gh_mirrors/dj/django-template-partials

在 Django 开发中，你是否经常遇到同一段模板代码被反复复制粘贴？django-template-partials 就是为解决这一痛点而生的开源库，它让 Django 模板语言（DTL）支持可复用的命名 partial（片段），只需定义一次，就能在同一模板乃至多个模板中随意引用。本文将带你从零开始，完成 django-template-partials 的安装配置，并写出你的第一个 partial 示例，快速掌握 Django 模板片段复用的核心技巧。

django-template-partials是什么：模板片段复用的核心价值

django-template-partials 的作者是 Django 核心团队成员 Carlton Gibson，它的定位非常纯粹：在单个模板文件内定义有名字的模板片段，然后在任意位置多次复用。

它的核心思想可以总结为一句话：

用 {% partialdef %} 定义片段，用 {% partial %} 引用片段。

相比传统的 {% include %}（需要单独建文件、传参数），命名 partial 有以下明显优势：

• ✅ 片段与模板同文件，无需额外维护小模板文件
• ✅ 继承当前上下文，循环中使用天然友好
• ✅ 支持 inline 模式，原地渲染不占位置
• ✅ 可通过 模板名#片段名 语法被加载器和 include 直接引用

它的标签实现位于 partials.py，模板加载器集成在 loader.py，阅读源码可以更深入理解其工作方式。

django-template-partials安装步骤：三步完成环境配置

安装 django-template-partials 非常简单，只需三步。

第一步：使用 pip 安装

在项目虚拟环境中执行：

pip install django-template-partials

第二步：注册到 INSTALLED_APPS

打开项目的 settings.py，把 "template_partials" 加入 INSTALLED_APPS：

INSTALLED_APPS = [
    "template_partials",
    # ... 其他应用
]

第三步：确认模板配置

默认情况下，应用启动时会自动把 template_partials.loader.Loader 包装进 Django 模板加载器（见 apps.py），你无需手动修改 TEMPLATES 配置，开箱即用。🚀

小提示：如果希望手动控制加载器，可以把 INSTALLED_APPS 中的值改为 "template_partials.apps.SimpleAppConfig"，再用 wrap_loaders("django") 自行配置。

第一个示例：用 partialdef 定义你的命名 partial

安装完成后，我们直接写第一个示例。假设你有一个模板 example.html（可参考项目测试模板 tests/templates/example.html）：

{% load partials %}

{% partialdef test-partial %}
TEST-PARTIAL-CONTENT
{% endpartialdef %}

这里发生了两件事：

1. {% load partials %} 加载模板标签库
2. {% partialdef test-partial %} 定义了一个名为 test-partial 的片段

片段定义本身不会输出任何内容，它只是"登记"了一段可复用的模板代码。

在模板中复用 partial：核心标签的使用技巧

定义好 partial 之后，就可以在模板任意位置多次引用了：

{% block main %}
BEGINNING
{% partial test-partial %}
MIDDLE
{% partial test-partial %}
END
{% endblock main %}

渲染结果如下：

BEGINNING
TEST-PARTIAL-CONTENT
MIDDLE
TEST-PARTIAL-CONTENT
END

一份定义，多处复用，这就是命名 partial 最直观的价值。在循环中它同样得心应手，因为 partial 会继承当前渲染上下文：

{% for object in object_list %}
    {% partial test-partial %}
{% endfor %}

需要调整上下文时，配合 {% with %} 标签即可。

进阶用法：inline模式与加载器集成

inline 模式：原地输出内容

如果想保留原有内容的位置，同时又能让片段可复用，可以在定义时加上 inline 参数：

{% block main %}
{% partialdef inline-partial inline %}
CONTENT
{% endpartialdef %}
{% endblock main %}

此时内容会原地渲染，同时片段名也被注册，之后依然可以通过 {% partial inline-partial %} 复用。

通过加载器引用：模板名#片段名

这是 django-template-partials 的一大特色——partial 对视图层完全透明。在视图函数中可以直接写：

self.template_name = "example.html#test-partial"

也可以在模板中用 include 标签引用其他模板里的片段：

{% include "example.html#test-partial" %}

更棒的是，partial 支持跨模板协作：父模板通过 {% include %} 引入子模板，而子模板里定义的 partial 也能正常工作（参见 tests/templates/parent.html 与 tests/templates/included.html 的测试用例）。

与Django 6.0内置partial的关系：升级须知

从 Django 6.0 开始，官方已将 partial 和 partialdef 标签并入核心模板语言。因此：

• 新项目建议直接使用 Django 6.0 内置的模板 partial 功能
• 旧项目升级时，{% load partials %} 可以移除，标签会自动提示废弃警告
• 老标签 {% startpartial %} 已废弃，请改用 {% partialdef %}

即便如此，对于仍使用 Django 4.2 / 5.x 的项目，django-template-partials 依然是实现模板片段复用最轻量、最优雅的选择。

小结：快速上手的三个要点

要点	内容
安装	pip install django-template-partials + 注册 INSTALLED_APPS
定义	{% partialdef 名称 %} 内容 {% endpartialdef %}
复用	{% partial 名称 %} 或 模板名#名称

django-template-partials 用最少的代码解决了 Django 模板复用的大问题。现在，打开你的模板文件，定义一个 partial 试试吧，你会发现模板代码瞬间清爽了很多！🎉

【免费下载链接】django-template-partials Reusable named inline partials for the Django Template Language. 项目地址: https://gitcode.com/gh_mirrors/dj/django-template-partials