模板

管理后台中的每个页面都是一个可覆盖的 Jinja2 模板。无需分叉内置模板树，即可修改单个列表页面、某一字段的表格单元格或仪表盘部件。

模板加载器的工作原理

from sqlalchemy import create_engine
from starlette_admin.contrib.sqla import Admin

engine = create_engine("sqlite:///admin.sqlite")
admin = Admin(engine, title="My Admin", templates_dir="my_templates/")

Admin 会构建一个 Jinja2 ChoiceLoader，先检查你的 templates_dir，再检查内置的 starlette_admin/templates/ 包目录。只要在 my_templates/ 下按其在 starlette_admin/templates/ 中的相同相对路径放置文件，你的文件就会遮蔽内置版本。其余所有模板仍从内置目录渲染。

模板目录结构一览

覆盖单个页面模板

my_templates/
└── list.html   ← shadows the built-in list.html

{# my_templates/list.html #}
{% extends "@starlette-admin/list.html" %}

{% block content %}
  <div class="alert alert-info">Custom banner above the list.</div>
  {{ super() }}
{% endblock %}

{% extends "list.html" %} 会重新解析到你自己的 my_templates/list.html，因为 templates_dir 会被优先检查，这种循环引用会引发无限递归错误。@starlette-admin/ 前缀始终指向内置副本，因此覆盖中的每个 extends 和 include 都必须使用该前缀，而不能使用裸文件名。

可覆盖的块

每个内置页面都继承自 layout.html，而后者又继承自 base.html。只需覆盖单个 {% block %} 而非整个文件，即可修改某个片段，而不必复制页面的其余部分：

{# my_templates/list.html #}
{% extends "@starlette-admin/list.html" %}

{% block list_toolbar_extra %}
  {{ super() }}
  <a class="btn btn-outline-primary" href="/reports/export">Custom report</a>
{% endblock %}

base.html

layout.html

list.html

detail.html

create.html / edit.html

login.html

index.html

error.html

示例：用内联 SVG 替换侧边栏 Logo

将 URL 传给 Admin(logo_url=...) 是设置 Logo 最快捷的方式，且适用于大多数情况，包括外部 .svg 文件。不过，内置模板会将该 URL 渲染在 <img> 标签内，因此 SVG 无法从周围的页面继承 CSS 属性。

当你需要让 Logo 响应界面的其余部分时，请使用内联 <svg> 标记覆盖 brand 块。

实现方式

在你的模板目录中创建一个 layout.html 文件。管理后台的每个页面都继承自 layout.html，因此这一处覆盖即可应用于全站。

{# my_templates/layout.html #}
{% extends "@starlette-admin/layout.html" %}

{% block brand %}
  <svg class="navbar-logo" viewBox="0 0 32 32" fill="currentColor">
    <path d="M16 2 L30 9 L30 23 L16 30 L2 23 L2 9 Z" />
  </svg>
{% endblock %}

覆盖字段模板

每种字段上下文使用三个子目录：

你可以只覆盖文本字段的列表单元格，而不影响表单或详情显示：

my_templates/
└── fields/
    └── list/
        └── text.html

要让某一个字段实例改用你的模板，而不是在所有地方覆盖该类型，可以在字段本身上设置 list_template、detail_template、form_template、null_template 或 empty_template：

from starlette_admin.fields import StringField

StringField("status", list_template="fields/list/status_badge.html")

null_template（默认值 "fields/detail/_null.html"）和 empty_template（默认值 "fields/detail/_empty.html"）是两个独立的槽位。只要字段的值为 None 或空列表、空元组，列表和详情页面就会用它们替代 list_template 或 detail_template 进行渲染：

StringField("status", null_template="fields/detail/_status_null.html")

覆盖部件模板

部件遵循相同的覆盖模式。将你的文件放在 widgets/ 目录下：

my_templates/
└── widgets/
    └── stat_widget.html

全局模板变量

这些变量无需显式传入即可在每个模板中使用。Admin 会在设置阶段一次性将其安装为 Jinja2 全局变量：

页面级上下文变量

除上述全局变量之外，每个页面还会把自己的上下文字典传递给 TemplateResponse。

list.html

detail.html

create.html / edit.html

添加自定义全局变量和过滤器

要向模板添加自己的变量和函数，请子类化 Admin 并覆盖 __init__。先调用 super().__init__()，以确保在你添加内容之前 self.templates 已经存在：

from sqlalchemy import create_engine
from starlette_admin.contrib.sqla import Admin


class MyAdmin(Admin):
    def __init__(self, *args, **kwargs) -> None:
        super().__init__(*args, **kwargs)
        self.templates.env.globals["site_name"] = "My App"
        self.templates.env.filters["currency"] = lambda v: f"${v:,.2f}"


engine = create_engine("sqlite:///admin.sqlite")
admin = MyAdmin(engine, title="My Admin")

内置 Jinja2 过滤器

每个 Admin 实例都会在 _setup_templates 期间注册以下过滤器：

后续步骤

• 表单布局：将创建和编辑表单拆分为带标题、可选择折叠的分组，并可覆盖 _form_group.html 来修改其标记。
• 自定义主题：在不改动单个模板的情况下重塑管理后台的样式。
• 自定义字段：将字段的 Python 类与其专属的 list_template 或 form_template 配对使用。
• 扩展点：模板之外全部可插拔扩展点的完整列表。