模板¶

🌐 由 AI 与人类协作翻译

本翻译由人类引导的 AI 生成。🤝

可能存在误解原意或不够自然等问题。🤖

你可以通过帮助我们更好地引导 AI LLM来改进此翻译。

英文版本

你可以在 FastAPI 中使用任何你想用的模板引擎。

常见选择是 Jinja2，它也是 Flask 和其他工具使用的模板引擎。

有一些工具可以轻松配置它，你可以直接在 FastAPI 应用中使用（由 Starlette 提供）。

安装依赖项¶

将 jinja2 添加到你的项目中：

$ uv add jinja2

---> 100%

使用 `Jinja2Templates`¶

导入 Jinja2Templates。
创建可复用的 templates 对象。
在返回模板的路径操作中声明 Request 参数。
使用你创建的 templates 渲染并返回 TemplateResponse，传递模板的名称、请求对象以及一个包含多个键值对（用于 Jinja2 模板）的 "context" 字典。

Python 3.10+

from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse
from fastapi.staticfiles import StaticFiles
from fastapi.templating import Jinja2Templates

app = FastAPI()

app.mount("/static", StaticFiles(directory="static"), name="static")


templates = Jinja2Templates(directory="templates")


@app.get("/items/{id}", response_class=HTMLResponse)
async def read_item(request: Request, id: str):
    return templates.TemplateResponse(
        request=request, name="item.html", context={"id": id}
    )

注意

在 FastAPI 0.108.0，Starlette 0.29.0 之前，name 是第一个参数。

并且，在此之前的旧版本中，request 对象是作为 Jinja2 的 context 中的键值对的一部分传递的。

提示

通过声明 response_class=HTMLResponse，文档 UI 就能知道响应会是 HTML。

技术细节

你还可以使用 from starlette.templating import Jinja2Templates。

FastAPI 将同一个 starlette.templating 作为 fastapi.templating 提供，只是为了方便开发者使用。但绝大多数可用响应都直接来自 Starlette。Request 和 StaticFiles 也一样。

编写模板¶

然后你可以在 templates/item.html 编写一个模板，例如：

<html>
<head>
    <title>Item Details</title>
    <link href="{{ url_for('static', path='/styles.css') }}" rel="stylesheet">
</head>
<body>
    <h1><a href="{{ url_for('read_item', id=id) }}">Item ID: {{ id }}</a></h1>
</body>
</html>

模板上下文值¶

在包含如下语句的 HTML 中：

{% raw %}

Item ID: {{ id }}

{% endraw %}

...它会显示你传入的 "context" dict 中取得的 id：

{"id": id}

例如，当 ID 为 42 时，会渲染成：

Item ID: 42

模板 `url_for` 参数¶

你还可以在模板内使用 url_for()，其参数与路径操作函数使用的参数相同。

所以，该部分：

{% raw %}

<a href="{{ url_for('read_item', id=id) }}">

{% endraw %}

...将生成一个链接，指向由路径操作函数 read_item(id=id) 处理的同一个 URL。

例如，当 ID 为 42 时，会渲染成：

<a href="/items/42">

模板与静态文件¶

你还可以在模板内部使用 url_for()，例如将它与你挂载的 name="static" 的 StaticFiles 一起使用。

<html>
<head>
    <title>Item Details</title>
    <link href="{{ url_for('static', path='/styles.css') }}" rel="stylesheet">
</head>
<body>
    <h1><a href="{{ url_for('read_item', id=id) }}">Item ID: {{ id }}</a></h1>
</body>
</html>

在这个示例中，它会通过以下内容链接到 static/styles.css 中的 CSS 文件：

h1 {
    color: green;
}

而且因为你使用了 StaticFiles，该 CSS 文件会由你的 FastAPI 应用在 URL /static/styles.css 自动提供。

模板¶