用途:指导在 Litestar 中构建 HTMX 驱动的交互流程,统一服务端渲染与局部片段响应的写法。
主要能力:决定 HTMX 是全局启用(HTMXPlugin)还是局部启用(request_class=HTMXRequest);通过 request.htmx 读取请求上下文,避免手工解析 HX-* 头;按场景选择响应原语,如 HTMXTemplate 渲染片段,ClientRedirect 全量跳转,HXLocation 无刷新导航,PushUrl/ReplaceUrl 修改历史或地址栏,Reswap/Retarget/TriggerEvent 调整客户端行为,ClientRefresh 刷新整页,HXStopPolling 停止轮询。
使用方式:为处理器建立统一契约——普通请求返回完整页面,HTMX 请求返回片段或 HTMX 感知响应;HTMXTemplate 处理器应标注返回 Template;触发事件时提供 after= 并限定为 receive、settle 或 swap。模板应保持小而面向交换目标。
适用场景:以 HTMX 为主要交互模型的应用;需要局部刷新、轮询、重定向语义或历史管理的服务端渲染页面。
限制与注意:不要向片段目标返回完整布局 HTML;不要混用 JSON API 与片段 HTML 而无明确分支;不要手工设置 HX-* 头;仍需覆盖非 HTMX 的回退路径;测试需同时验证正文内容与 HTMX 行为。
相关参考:https://docs.litestar.dev/2/usage/htmx.html 与 https://docs.litestar.dev/2/reference/plugins/htmx.html。安装命令与具体版本资料暂未提供。