Django 如何覆盖第三方应用或 django.contrib.admin 的内置模板

Django 如何覆盖第三方应用或 django.contrib.admin 的内置模板【免费下载链接】djangoThe Web framework for perfectionists with deadlines.项目地址: https://gitcode.com/GitHub_Trending/dj/django当你在项目中使用了第三方应用或django.contrib.admin这类 contrib 应用却想改动它们自带的页面外观比如给 admin 后台加一个 logo、改掉 admin 顶部标题时Django 的模板加载机制允许你用自己写的模板文件替换它们内置的模板而不用修改这些应用的源码。本文介绍两条官方支持的路径把覆盖模板放在项目级templates目录或放在某个应用的templates目录以及如何用{% extends %}只改模板中的某一块内容。适用前提是项目使用默认项目模板django-admin startproject生成settings.py中已有TEMPLATES设置。先确认 TEMPLATES 设置覆盖模板依赖两个配置项DIRS模板引擎在文件系统上查找模板的目录列表搜索路径默认为空列表。APP_DIRS是否在已安装应用的内部查找模板默认为Falsestartproject生成的默认settings.py会将其设为True。这两项的完整说明见 settings 文档模板加载的底层机制DIRS选项、loader 类型见 模板 API 文档。主路径在项目级 templates 目录中覆盖这是官方文档推荐的常用方式以 How to override templates 的blog第三方应用为例。假设第三方应用blog提供了blog/post.html和blog/list.html两个模板。首先确保settings.py中TEMPLATES配置了DIRS指向项目根目录下的templates目录from pathlib import Path BASE_DIR Path(__file__).resolve().parent.parent INSTALLED_APPS [ ..., blog, ..., ] TEMPLATES [ { BACKEND: django.template.backends.django.DjangoTemplates, DIRS: [BASE_DIR / templates], APP_DIRS: True, # ... }, ]如果项目是用默认项目模板创建的TEMPLATES和BASE_DIR已经存在需要修改的只是DIRS这一项。然后在项目根目录的templates目录里按被覆盖模板的同名路径新建文件templates/ blog/ list.html post.html工作原理模板加载器先查找DIRS中的目录。当blog应用的视图请求blog/post.html和blog/list.html时加载器会返回你刚创建的文件而不是blog应用自带的版本。这也是文档给出的行为判断依据请求模板时拿到的是你创建的覆盖文件。可选路径在某个应用的 templates 目录中覆盖由于覆盖的是项目内应用之外的模板更常见的做法是上面的项目级目录方式但文档同样支持把覆盖模板放进某个应用的模板目录。前提是确认APP_DIRS为TrueTEMPLATES [ { # ... APP_DIRS: True, # ... }, ]如果想把blog/list.html和blog/post.html的覆盖版本放进名为myapp的应用目录结构为myapp/ templates/ blog/ list.html post.htmlAPP_DIRS设为True后模板加载器会到各应用的templates目录里查找并找到这些模板。需要注意优先级如果应用目录和项目目录都含有同名覆盖模板默认 Django 模板加载器会优先从项目级目录加载即DIRS先于APP_DIRS被搜索。覆盖 admin 模板并保留原内容对于django.contrib.admin的模板可以直接复制改写也可以用{% extends %}在覆盖的同时继承原模板只替换其中某一段。官方示例 是在 admin 首页添加自定义 logo{% extends admin/base_site.html %} {% block branding %} img srclink/to/logo.png altlogo {{ block.super }} {% endblock %}上面文件保存在templates/admin/base_site.html示例中link/to/logo.png是文档示意值请替换为你自己的 logo 路径。文档对这段示例的要点说明该文件位于项目级templates目录用来覆盖admin/base_site.html新模板extends的正是被覆盖的同一个模板admin/base_site.html只替换branding这一个 block用block.super保留原有内容模板其余部分原样继承自admin/base_site.html。之所以可行是因为模板加载器在解析extends标签时不会把已经加载的那个覆盖模板即templates/admin/base_site.html算进去。仓库中真实的 admin 模板可以对照查看base_site.html 和 base.html 都定义了brandingblock。不继承、整体复制改写的做法Django 教程第 7 部分 展示了另一种做法直接复制admin/base_site.html再编辑。步骤是在项目目录如djangotutorial下创建templates目录在settings.py的TEMPLATES中加DIRS: [BASE_DIR / templates]在templates下建admin目录把 Django 源码中的admin/base_site.html默认 admin 模板目录位于django/contrib/admin/templates复制进去编辑文件例如把{{ site_header|default:_(Django administration) }}连同花括号替换为站点名称得到一个定制的{% block branding %}。如果找不到 Django 源码在哪文档给出的定位命令是$ python -c import django; print(django.__path__)教程还指出Django 任何默认 admin 模板都可以用同样方式覆盖——从默认目录复制到你的自定义目录然后修改。另有一个边界说明仅仅改 admin 站点标题这类定制实际项目中更简单的方式是使用AdminSite.site_header属性模板覆盖更适合需要改动页面结构的情况。结果验证与注意事项验证方式文档对覆盖生效的判断标准是加载器行为本身——当应用视图请求被覆盖的模板名时加载器返回你在DIRS或应用templates目录中创建的文件。对 admin 而言访问后台页面即可看到branding区域的定制内容新 logo 或新标题取代了默认内容。搜索顺序DIRS先于APP_DIRS项目级目录中的同名模板会先于应用目录中的模板被找到两处同时放同名文件时以此为准。内置表单控件模板如果你的目标是覆盖 widget 等表单内置模板而不是普通页面模板必须使用TemplatesSettingrenderer做法与本文的覆盖流程相同详见 表单 renderer 文档中的 “Overriding built-in widget templates”。加载器适用范围上述“默认 Django 模板加载器”的行为描述针对内置 Django 模板引擎若项目改用 Jinja2 后端或自定义 loader模板查找行为以对应后端为准。参考资料How to override templates、教程 7模板定制章节、settings 文档。【免费下载链接】djangoThe Web framework for perfectionists with deadlines.项目地址: https://gitcode.com/GitHub_Trending/dj/django创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考