Litestar HTMX 插件 API 参考基于 litestar.plugins.htmx 构建超媒体交互应用【免费下载链接】litestarLight, flexible and extensible ASGI framework | Built to scale项目地址: https://gitcode.com/GitHub_Trending/li/litestar本文以仓库中 docs/reference/plugins/htmx.rst 这一 API 参考文档为骨架系统梳理litestar.plugins.htmx模块暴露的全部类型与用法并结合 docs/usage/htmx.rst 的实战指南与 litestar/plugins/htmx.py 的源码实现展开。读完本文你将掌握如何在 Litestar 应用中通过HTMXPlugin、HTMXRequest与各类 HTMX 响应类实现局部页面刷新、URL 推送、事件触发等超媒体交互同时理解这些 API 在源码与测试中的真实存在形态。模块定位一个面向 API 参考的重新导出层docs/reference/plugins/htmx.rst是一个典型的 Sphinxautomodule参考页其技术核心是litestar.plugins.htmx模块。从源码 litestar/plugins/htmx.py 可以看出该模块本身并不实现 HTMX 逻辑而是对独立分发包litestar-htmx的完整重新导出re-export层模块顶部通过from litestar_htmx import (...)一次性导入 22 个公开符号与_utils工具模块__all__明确列出全部公开 API作为稳定契约供文档系统、IDE 与下游代码引用源码第一行标注# pyright: reportUnusedImportfalse说明这些导入的目的是对外暴露而非内部使用。这一设计被单元测试 tests/unit/test_plugins/test_htmx/test_htmx_reexports.py 严格锁定test_all_re_exports_are_importable逐一验证每个符号可导入且非空test_all_items_in_all_are_exported则断言htmx.__all__与期望集合完全一致防止导出清单漂移。安装前提由于litestar-htmx在 Litestar 3.x 中已从默认依赖移除见 docs/release-notes/whats-new-3.rst使用本插件必须通过包额外依赖安装pip install litestar[htmx]对应依赖声明位于 pyproject.tomlhtmx [litestar-htmx0.4.0]。未安装时导入litestar.plugins.htmx会因缺少第三方包而失败请先完成安装。公开 API 总览litestar.plugins.htmx.__all__暴露的 22 个符号可划分为四类对应 API 参考页的完整成员清单类别符号用途插件与配置HTMXPlugin、HTMXConfig全局启用 HTMX 请求类与配置请求与详情HTMXRequest、HTMXDetails、HTMXHeaders、HtmxHeaderType解析 HX-* 请求头暴露请求详情响应类HTMXTemplate、HXLocation、HXStopPolling、ClientRedirect、ClientRefresh、PushUrl、ReplaceUrl、Reswap、Retarget、TriggerEvent生成各类 HTMX 响应头/响应体类型别名EventAfterType、LocationType、PushUrlType、ReSwapMethod、TriggerEventType及_utils提供参数取值约束与工具函数以下各节按此分类展开并给出可运行示例。HTMXPlugin全局配置默认请求类HTMXPlugin是接入 HTMX 的最简入口。它自动将应用的路由默认请求类切换为HTMXRequest使所有处理器都能访问 HTMX 客户端信息无需在每个路由上单独声明request_class。from litestar import Litestar from litestar.plugins.htmx import HTMXPlugin from litestar.plugins.jinja import JinjaTemplateEngine from litestar.template.config import TemplateConfig from pathlib import Path app Litestar( route_handlers[get_form], debugTrue, plugins[HTMXPlugin()], template_configTemplateConfig( directoryPath(litestar_htmx/templates), engineJinjaTemplateEngine, ), )要点说明plugins[HTMXPlugin()]将HTMXRequest设为全局默认请求类等价于在Litestar(...)上手动设置request_classHTMXRequest插件常与模板配置搭配使用因为 HTMX 的核心工作流是返回 HTML 片段partial若需要更细粒度控制也可以在单个路由、控制器、路由器的request_class参数上单独指定HTMXRequest覆盖全局默认值。HTMXRequest 与 HTMXDetails读取客户端状态HTMXRequest是litestar.connection.Request的特化请求类负责解析 HTMX 客户端发送的HX-*请求头。其核心交互属性为request.htmx返回HTMXDetails实例包含当前 URL、目标元素、触发器等完整信息。from litestar import get, Litestar from litestar.plugins.htmx import HTMXRequest, HTMXTemplate from litestar.plugins.jinja import JinjaTemplateEngine from litestar.template.config import TemplateConfig from litestar.response import Template from pathlib import Path get(path/form) def get_form(request: HTMXRequest) - Template: if request.htmx: # 请求带有 HX-Request 头时成立 print(request.htmx) # HTMXDetails 实例 print(request.htmx.current_url) return HTMXTemplate( template_namepartial.html, contextcontext, push_url/form, ) app Litestar( route_handlers[get_form], debugTrue, request_classHTMXRequest, template_configTemplateConfig( directoryPath(litestar_htmx/templates), engineJinjaTemplateEngine, ), )使用提示if request.htmx的布尔判断用于区分当前请求是否来自 HTMX 客户端即是否携带HX-Request头便于同一端点同时服务普通浏览器请求与局部刷新请求HTMXDetails是查看请求详情属性的权威来源其成员清单以litestar_htmx包中的实现为准包括current_url、目标元素、触发器等由HX-*头解码出的字段若请求带有HX-Request头但缺失receive/send等字段HTMXRequest会提供默认值相关修复历史记录在 docs/release-notes/2.x-changelog.rst。响应类覆盖 HTMX 两种响应模型HTMX 的响应分为两类一类不修改 DOM另一类可以修改 DOM。litestar.plugins.htmx对两类均提供了对应响应类且所有响应类都支持content参数承载响应体。HTMXTemplate渲染 HTML 片段最常用HTMXTemplate用于渲染 HTML 页面或片段是 HTMX 场景下最常用的响应类。注意其返回类型标注应为 Litestar 的Template而非HTMXTemplate本身from litestar.plugins.htmx import HTMXTemplate from litestar.response import Template get(path/form) def get_form(request: HTMXRequest) - Template: ... return HTMXTemplate( template_namepartial.html, contextcontext, # 以下均为可选参数 push_url/form, # 更新浏览器历史记录 re_swapouterHTML, # 修改交换方式 re_target#new-target, # 修改目标元素 trigger_eventshowMessage, # 触发事件名 params{alert: Confirm your Choice.}, # 传给事件的参数 afterreceive, # 事件触发时机receive、settle、swap )参数联动规则来自原文档的明确约束trigger_event、params、after三个参数相互关联必须配套使用触发事件时after为必填项取值只能是receive、settle、swap三者之一push_url控制是否把新 URL 推入浏览器历史栈。不修改 DOM 的响应类此类响应不触碰页面 DOM仅执行客户端层面的导航或停止操作。HXStopPolling停止客户端轮询。get(/) def handler() - HXStopPolling: ... return HXStopPolling()ClientRedirect带页面重载的客户端重定向。get(/) def handler() - ClientRedirect: ... return ClientRedirect(redirect_to/contact-us)ClientRefresh强制整页刷新。get(/) def handler() - ClientRefresh: ... return ClientRefresh()可修改 DOM 的响应类此类响应通过HX-*响应头指示客户端执行 DOM 操作。HXLocation无页面重载地跳转到新位置支持自定义目标、交换方式、提交值与请求头。get(/about) def handler() - HXLocation: ... return HXLocation( redirect_to/contact-us, # 以下均为可选参数 sourcesource, # 请求的来源元素 eventevent, # 触发请求的事件 target#target, # 目标元素 id swapouterHTML, # 使用的交换方式 hx_headers{attr: val}, # 传给 HTMX 的请求头 values{val: one}, # 随响应提交的值 )PushUrl携带响应体并将 URL 推入浏览器可选择是否更新历史栈push_urlFalse时阻止历史更新。get(/about) def handler() - PushUrl: ... return PushUrl(contentSuccess!, push_url/about)ReplaceUrl携带响应体并替换浏览器地址栏 URLreplace_urlFalse时阻止地址栏更新。get(/contact-us) def handler() - ReplaceUrl: ... return ReplaceUrl(contentSuccess!, replace_url/contact-us)Reswap携带响应体并指定交换方法。get(/contact-us) def handler() - Reswap: ... return Reswap(contentSuccess!, methodbeforebegin)Retarget携带响应体并修改目标元素。get(/contact-us) def handler() - Retarget: ... return Retarget(contentSuccess!, target#new-target)TriggerEvent携带响应体并触发客户端事件after的合法取值为receive、settle、swap。get(/contact-us) def handler() - TriggerEvent: ... return TriggerEvent( contentSuccess!, nameshowMessage, params{attr: value}, afterreceive, # 可选 receive、settle、swap )类型别名约束参数取值的编译期契约EventAfterType、LocationType、PushUrlType、ReSwapMethod、TriggerEventType等类型别名由litestar-htmx包定义用于约束上文各响应类参数如after、swap、push_url的合法取值。在类型检查器与 IDE 的配合下传入非法取值会得到即时提示是从源码层面保障配置正确性的关键机制。HTMXHeaders与HtmxHeaderType则用于描述与校验HX-*请求头集合。与仓库其他部分的衔接API 参考目录本文档隶属于 docs/reference/plugins/index.rst 中的插件参考章节与 attrs、jinja、mako、pydantic 等插件参考页并列实战指南完整的用法教程见 docs/usage/htmx.rst本文所有代码示例均继承自该文档依赖声明litestar[htmx]extra 的版本约束litestar-htmx0.4.0见 pyproject.toml测试保障重新导出契约由 tests/unit/test_plugins/test_htmx/test_htmx_reexports.py 验证确保__all__中的每个符号均可从litestar.plugins.htmx导入。从源码结构看litestar.plugins.htmx是一个典型的薄封装模块它把litestar-htmx的完整 API 收敛到 Litestar 的统一命名空间下既保持了与 Litestar 插件体系plugins[HTMXPlugin()]的无缝集成又通过__all__与单元测试维护了稳定、可文档化的公共接口。在实际项目中你可以按安装 extra → 注册 HTMXPlugin → 在处理器中注入 HTMXRequest → 返回 HTMXTemplate 或专用响应类这条链路快速构建服务端渲染的交互式页面。【免费下载链接】litestarLight, flexible and extensible ASGI framework | Built to scale项目地址: https://gitcode.com/GitHub_Trending/li/litestar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Litestar HTMX 插件 API 参考：基于 litestar.plugins.htmx 构建超媒体交互应用
Litestar HTMX 插件 API 参考基于 litestar.plugins.htmx 构建超媒体交互应用【免费下载链接】litestarLight, flexible and extensible ASGI framework | Built to scale项目地址: https://gitcode.com/GitHub_Trending/li/litestar本文以仓库中 docs/reference/plugins/htmx.rst 这一 API 参考文档为骨架系统梳理litestar.plugins.htmx模块暴露的全部类型与用法并结合 docs/usage/htmx.rst 的实战指南与 litestar/plugins/htmx.py 的源码实现展开。读完本文你将掌握如何在 Litestar 应用中通过HTMXPlugin、HTMXRequest与各类 HTMX 响应类实现局部页面刷新、URL 推送、事件触发等超媒体交互同时理解这些 API 在源码与测试中的真实存在形态。模块定位一个面向 API 参考的重新导出层docs/reference/plugins/htmx.rst是一个典型的 Sphinxautomodule参考页其技术核心是litestar.plugins.htmx模块。从源码 litestar/plugins/htmx.py 可以看出该模块本身并不实现 HTMX 逻辑而是对独立分发包litestar-htmx的完整重新导出re-export层模块顶部通过from litestar_htmx import (...)一次性导入 22 个公开符号与_utils工具模块__all__明确列出全部公开 API作为稳定契约供文档系统、IDE 与下游代码引用源码第一行标注# pyright: reportUnusedImportfalse说明这些导入的目的是对外暴露而非内部使用。这一设计被单元测试 tests/unit/test_plugins/test_htmx/test_htmx_reexports.py 严格锁定test_all_re_exports_are_importable逐一验证每个符号可导入且非空test_all_items_in_all_are_exported则断言htmx.__all__与期望集合完全一致防止导出清单漂移。安装前提由于litestar-htmx在 Litestar 3.x 中已从默认依赖移除见 docs/release-notes/whats-new-3.rst使用本插件必须通过包额外依赖安装pip install litestar[htmx]对应依赖声明位于 pyproject.tomlhtmx [litestar-htmx0.4.0]。未安装时导入litestar.plugins.htmx会因缺少第三方包而失败请先完成安装。公开 API 总览litestar.plugins.htmx.__all__暴露的 22 个符号可划分为四类对应 API 参考页的完整成员清单类别符号用途插件与配置HTMXPlugin、HTMXConfig全局启用 HTMX 请求类与配置请求与详情HTMXRequest、HTMXDetails、HTMXHeaders、HtmxHeaderType解析 HX-* 请求头暴露请求详情响应类HTMXTemplate、HXLocation、HXStopPolling、ClientRedirect、ClientRefresh、PushUrl、ReplaceUrl、Reswap、Retarget、TriggerEvent生成各类 HTMX 响应头/响应体类型别名EventAfterType、LocationType、PushUrlType、ReSwapMethod、TriggerEventType及_utils提供参数取值约束与工具函数以下各节按此分类展开并给出可运行示例。HTMXPlugin全局配置默认请求类HTMXPlugin是接入 HTMX 的最简入口。它自动将应用的路由默认请求类切换为HTMXRequest使所有处理器都能访问 HTMX 客户端信息无需在每个路由上单独声明request_class。from litestar import Litestar from litestar.plugins.htmx import HTMXPlugin from litestar.plugins.jinja import JinjaTemplateEngine from litestar.template.config import TemplateConfig from pathlib import Path app Litestar( route_handlers[get_form], debugTrue, plugins[HTMXPlugin()], template_configTemplateConfig( directoryPath(litestar_htmx/templates), engineJinjaTemplateEngine, ), )要点说明plugins[HTMXPlugin()]将HTMXRequest设为全局默认请求类等价于在Litestar(...)上手动设置request_classHTMXRequest插件常与模板配置搭配使用因为 HTMX 的核心工作流是返回 HTML 片段partial若需要更细粒度控制也可以在单个路由、控制器、路由器的request_class参数上单独指定HTMXRequest覆盖全局默认值。HTMXRequest 与 HTMXDetails读取客户端状态HTMXRequest是litestar.connection.Request的特化请求类负责解析 HTMX 客户端发送的HX-*请求头。其核心交互属性为request.htmx返回HTMXDetails实例包含当前 URL、目标元素、触发器等完整信息。from litestar import get, Litestar from litestar.plugins.htmx import HTMXRequest, HTMXTemplate from litestar.plugins.jinja import JinjaTemplateEngine from litestar.template.config import TemplateConfig from litestar.response import Template from pathlib import Path get(path/form) def get_form(request: HTMXRequest) - Template: if request.htmx: # 请求带有 HX-Request 头时成立 print(request.htmx) # HTMXDetails 实例 print(request.htmx.current_url) return HTMXTemplate( template_namepartial.html, contextcontext, push_url/form, ) app Litestar( route_handlers[get_form], debugTrue, request_classHTMXRequest, template_configTemplateConfig( directoryPath(litestar_htmx/templates), engineJinjaTemplateEngine, ), )使用提示if request.htmx的布尔判断用于区分当前请求是否来自 HTMX 客户端即是否携带HX-Request头便于同一端点同时服务普通浏览器请求与局部刷新请求HTMXDetails是查看请求详情属性的权威来源其成员清单以litestar_htmx包中的实现为准包括current_url、目标元素、触发器等由HX-*头解码出的字段若请求带有HX-Request头但缺失receive/send等字段HTMXRequest会提供默认值相关修复历史记录在 docs/release-notes/2.x-changelog.rst。响应类覆盖 HTMX 两种响应模型HTMX 的响应分为两类一类不修改 DOM另一类可以修改 DOM。litestar.plugins.htmx对两类均提供了对应响应类且所有响应类都支持content参数承载响应体。HTMXTemplate渲染 HTML 片段最常用HTMXTemplate用于渲染 HTML 页面或片段是 HTMX 场景下最常用的响应类。注意其返回类型标注应为 Litestar 的Template而非HTMXTemplate本身from litestar.plugins.htmx import HTMXTemplate from litestar.response import Template get(path/form) def get_form(request: HTMXRequest) - Template: ... return HTMXTemplate( template_namepartial.html, contextcontext, # 以下均为可选参数 push_url/form, # 更新浏览器历史记录 re_swapouterHTML, # 修改交换方式 re_target#new-target, # 修改目标元素 trigger_eventshowMessage, # 触发事件名 params{alert: Confirm your Choice.}, # 传给事件的参数 afterreceive, # 事件触发时机receive、settle、swap )参数联动规则来自原文档的明确约束trigger_event、params、after三个参数相互关联必须配套使用触发事件时after为必填项取值只能是receive、settle、swap三者之一push_url控制是否把新 URL 推入浏览器历史栈。不修改 DOM 的响应类此类响应不触碰页面 DOM仅执行客户端层面的导航或停止操作。HXStopPolling停止客户端轮询。get(/) def handler() - HXStopPolling: ... return HXStopPolling()ClientRedirect带页面重载的客户端重定向。get(/) def handler() - ClientRedirect: ... return ClientRedirect(redirect_to/contact-us)ClientRefresh强制整页刷新。get(/) def handler() - ClientRefresh: ... return ClientRefresh()可修改 DOM 的响应类此类响应通过HX-*响应头指示客户端执行 DOM 操作。HXLocation无页面重载地跳转到新位置支持自定义目标、交换方式、提交值与请求头。get(/about) def handler() - HXLocation: ... return HXLocation( redirect_to/contact-us, # 以下均为可选参数 sourcesource, # 请求的来源元素 eventevent, # 触发请求的事件 target#target, # 目标元素 id swapouterHTML, # 使用的交换方式 hx_headers{attr: val}, # 传给 HTMX 的请求头 values{val: one}, # 随响应提交的值 )PushUrl携带响应体并将 URL 推入浏览器可选择是否更新历史栈push_urlFalse时阻止历史更新。get(/about) def handler() - PushUrl: ... return PushUrl(contentSuccess!, push_url/about)ReplaceUrl携带响应体并替换浏览器地址栏 URLreplace_urlFalse时阻止地址栏更新。get(/contact-us) def handler() - ReplaceUrl: ... return ReplaceUrl(contentSuccess!, replace_url/contact-us)Reswap携带响应体并指定交换方法。get(/contact-us) def handler() - Reswap: ... return Reswap(contentSuccess!, methodbeforebegin)Retarget携带响应体并修改目标元素。get(/contact-us) def handler() - Retarget: ... return Retarget(contentSuccess!, target#new-target)TriggerEvent携带响应体并触发客户端事件after的合法取值为receive、settle、swap。get(/contact-us) def handler() - TriggerEvent: ... return TriggerEvent( contentSuccess!, nameshowMessage, params{attr: value}, afterreceive, # 可选 receive、settle、swap )类型别名约束参数取值的编译期契约EventAfterType、LocationType、PushUrlType、ReSwapMethod、TriggerEventType等类型别名由litestar-htmx包定义用于约束上文各响应类参数如after、swap、push_url的合法取值。在类型检查器与 IDE 的配合下传入非法取值会得到即时提示是从源码层面保障配置正确性的关键机制。HTMXHeaders与HtmxHeaderType则用于描述与校验HX-*请求头集合。与仓库其他部分的衔接API 参考目录本文档隶属于 docs/reference/plugins/index.rst 中的插件参考章节与 attrs、jinja、mako、pydantic 等插件参考页并列实战指南完整的用法教程见 docs/usage/htmx.rst本文所有代码示例均继承自该文档依赖声明litestar[htmx]extra 的版本约束litestar-htmx0.4.0见 pyproject.toml测试保障重新导出契约由 tests/unit/test_plugins/test_htmx/test_htmx_reexports.py 验证确保__all__中的每个符号均可从litestar.plugins.htmx导入。从源码结构看litestar.plugins.htmx是一个典型的薄封装模块它把litestar-htmx的完整 API 收敛到 Litestar 的统一命名空间下既保持了与 Litestar 插件体系plugins[HTMXPlugin()]的无缝集成又通过__all__与单元测试维护了稳定、可文档化的公共接口。在实际项目中你可以按安装 extra → 注册 HTMXPlugin → 在处理器中注入 HTMXRequest → 返回 HTMXTemplate 或专用响应类这条链路快速构建服务端渲染的交互式页面。【免费下载链接】litestarLight, flexible and extensible ASGI framework | Built to scale项目地址: https://gitcode.com/GitHub_Trending/li/litestar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
