FastHX

正确使用 FastAPI 和 HTMX 的方法。

主要特性：

装饰器语法与 FastAPI 的使用方式一致，路由中无需使用未使用的或魔术依赖。
可与任何模板引擎或服务器端渲染库兼容，如 markyp-html 或 dominate。
内置 Jinja2 模板支持（甚至支持多个模板文件夹）。
让渲染引擎可以访问装饰路由的所有依赖项。
默认情况下，FastAPI 路由在接收非 HTMX 请求时将正常工作，因此同一路由可以同时提供数据和渲染 HTML。
在路由中设置的响应头在渲染后会保留，符合 FastAPI 的预期行为。
正确的类型提示使得可以将其他（带类型的）装饰器应用于路由。
适用于同步和异步路由。

安装

该包可在 PyPI 上获取，可以通过以下命令安装：

$ pip install fasthx

示例

有关展示 FastHX 基本用法的完整但简单的示例，请查看 examples 文件夹。

如果你正在寻找更复杂的（Jinja2）示例，包含主动搜索、延迟加载、服务器发送事件、自定义服务器端 HTMX 触发器、对话框以及 TailwindCSS 和 DaisyUI 集成等功能，请查看这个 FastAPI-HTMX-Tailwind 示例。

Jinja2 模板

要开始提供 HTML 和 HTMX 请求，你只需创建一个 fasthx.Jinja 实例，并将其 hx() 或 page() 方法用作路由的装饰器。hx() 仅针对 HTMX 请求触发 HTML 渲染，而 page() 无条件渲染 HTML，为你节省一些样板代码。请参阅以下示例代码：

from fastapi import FastAPI
from fastapi.templating import Jinja2Templates
from fasthx import Jinja
from pydantic import BaseModel

# 示例 API 使用的 Pydantic 模型
class User(BaseModel):
    first_name: str
    last_name: str

# 创建应用
app = FastAPI()

# 创建 FastAPI Jinja2Templates 实例，并用它创建一个
# FastHX Jinja 实例，作为你的装饰器
jinja = Jinja(Jinja2Templates("templates"))

@app.get("/")
@jinja.page("index.html")
def index() -> None:
    ...

@app.get("/user-list")
@jinja.hx("user-list.html")
async def htmx_or_data() -> list[User]:
    return [
        User(first_name="John", last_name="Lennon"),
        User(first_name="Paul", last_name="McCartney"),
        User(first_name="George", last_name="Harrison"),
        User(first_name="Ringo", last_name="Starr"),
    ]

@app.get("/admin-list")
@jinja.hx("user-list.html", no_data=True)
def htmx_only() -> list[User]:
    return [User(first_name="Billy", last_name="Shears")]

自定义模板

如果你不喜欢 Jinja 模板，hx() 和 page() 装饰器为你提供了所需的所有灵活性：你可以通过实现 HTMLRenderer 协议将任何 HTML 渲染或模板引擎集成到 fasthx 中。与 Jinja 的情况类似，hx() 仅针对 HTMX 请求触发 HTML 渲染，而 page() 无条件渲染 HTML。请参阅以下示例代码：

from typing import Annotated, Any

from fastapi import Depends, FastAPI, Request
from fasthx import hx, page

# 创建应用
app = FastAPI()

# 创建一个依赖项，以查看其返回值在渲染函数中是否可用
def get_random_number() -> int:
    return 4  # 通过公平的骰子选择

DependsRandomNumber = Annotated[int, Depends(get_random_number)]

# 创建渲染方法：它们必须始终具有这三个参数
# 如果你使用静态类型检查器，`result` 的类型提示必须与
# 使用此渲染方法的路由的返回类型注解匹配
def render_index(result: list[dict[str, str]], *, context: dict[str, Any], request: Request) -> str:
    return "<h1>Hello FastHX</h1>"

def render_user_list(result: list[dict[str, str]], *, context: dict[str, Any], request: Request) -> str:
    # `DependsRandomNumber` 依赖项的值可以通过与路由中相同的名称访问
    random_number = context["random_number"]
    lucky_number = f"<h1>{random_number}</h1>"
    users = "".join(("<ul>", *(f"<li>{u['name']}</li>" for u in result), "</ul>"))
    return f"{lucky_number}\n{users}"

@app.get("/")
@page(render_index)
def index() -> None:
    ...

@app.get("/htmx-or-data")
@hx(render_user_list)
def htmx_or_data(random_number: DependsRandomNumber) -> list[dict[str, str]]:
    return [{"name": "Joe"}]

@app.get("/htmx-only")
@hx(render_user_list, no_data=True)
async def htmx_only(random_number: DependsRandomNumber) -> list[dict[str, str]]:
    return [{"name": "Joe"}]