用途
htmx 用于通过 HTML 属性构建动态 Web UI,采用 HTML-over-the-wire 方式。其核心思路是:任何元素都可以通过 HTML 属性发起 HTTP 请求,服务器返回 HTML 片段并交换进 DOM。无需 JSON API、客户端渲染或构建步骤,服务器是唯一数据来源。资料中列举的适用场景包括:服务端渲染应用(Django、Rails、Laravel、Go 模板)、以 CRUD 为主且交互直接的应用程序、在不重写的前提下增强现有多页应用、团队熟悉后端但不熟悉前端框架的情况,以及 SEO 关键且 SSR 复杂度是考虑因素的情况。
主要能力
引入与基础请求
通过 script 标签引入 htmx,例如 https://unpkg.com/htmx.org@2.0.4。任何元素都可以发起请求,资料给出按钮示例:hx-get="/api/users"、hx-target="#user-list"、hx-swap="innerHTML"。
核心请求属性
支持 GET、POST、PUT、PATCH、DELETE。POST 可使用 hx-vals 传值;DELETE 可配合 hx-confirm 弹出确认。
交换策略(hx-swap)
hx-swap 控制响应 HTML 如何替换内容,可选值包括:innerHTML(默认,替换目标内部内容)、outerHTML(替换整个目标元素)、afterbegin、beforeend、beforebegin、afterend、delete(请求后删除目标)、none(不发交换、DOM 不变)。还支持交换修饰符,如 swap:300ms、settle:500ms、scroll:top、show:top。
目标定位(hx-target)
可使用 CSS 选择器,也可使用相对选择器:closest、find、next、previous、this,以及 body 进行整页交换。
触发方式(hx-trigger)
默认触发:按钮/链接为 click、输入框为 change、表单为 submit。支持修饰符:changed、delay:300ms、throttle:500ms,以及 every 30s。可使用 from: 监听其他元素事件、多个触发器、intersect once(进入视口时触发)、load(页面加载时触发)以及自定义事件。
指示器与表单
用 hx-indicator 显示加载状态,配合 .htmx-indicator、.htmx-request 类;用 hx-disabled-elt 在请求期间禁用元素。表单自动包含所有输入;hx-include 可包含触发元素之外的输入;hx-vals 可添加额外值,支持 js: 动态值;hx-params 可控制发送哪些参数(*、none、指定字段、not 排除);文件上传使用 hx-encoding="multipart/form-data"。
Out-of-Band 交换
一次响应可更新页面多个部分,元素带 hx-swap-oob 会被交换到匹配 ID 的位置,支持 true、innerHTML、outerHTML 等。
请求与响应头
请求头由 htmx 发送:HX-Request、HX-Target、HX-Trigger、HX-Trigger-Name、HX-Current-URL、HX-Prompt、HX-Boosted。响应头由服务器发送:HX-Redirect、HX-Refresh、HX-Retarget、HX-Reswap、HX-Trigger(可带 detail)、HX-Push-Url。
后端集成
资料给出 Express(Node.js)、Flask(Python)、Django、Go 的示例,通常通过检测 HX-Request 头决定返回片段还是整页。
常见模式
包括活动搜索、无限滚动、点击编辑、批量更新、懒加载、带动画的删除行。
页面增强(Boosting)
hx-boost 将标准链接和表单转换为带历史支持的 AJAX 请求,可作用于容器或整个 body,并可用 hx-boost="false" 排除特定链接,用 hx-push-url 控制历史记录。
扩展与配合
支持 WebSocket 扩展(htmx-ext-ws,使用 hx-ext="ws"、ws-connect、ws-send)与 SSE 扩展(htmx-ext-sse,使用 sse-connect、sse-swap),可与 Alpine.js 配合,也可使用 CSS 过渡类(.htmx-swapping、.htmx-added、.htmx-settling、.htmx-request)与 View Transitions API(transition:true)。
验证与事件
支持内联字段验证、表单级验证与错误汇总,以及在客户端验证失败时阻止请求。htmx 事件可通过 hx-on::after-settle 或 JavaScript 事件监听使用,如 htmx:beforeRequest、htmx:afterSwap、htmx:responseError,并可通过 HX-Trigger 头触发自定义事件。
使用方式
在页面中引入 htmx 脚本,然后通过 HTML 属性声明请求、目标、交换与触发行为。例如按钮设置 hx-get、hx-target、hx-swap;表单设置 hx-post 并指定目标与交换位置。服务器端根据 HX-Request 头返回 HTML 片段或整页,并可利用响应头控制重定向、刷新、更改目标与交换策略、推送 URL、触发事件。
适用场景
服务端渲染应用、CRUD 密集型应用、增强现有多页应用、后端强而前端框架经验有限的团队、对 SEO 有要求的场景。
限制
资料列出了选择 htmx 的部分适用条件,但关于不适用 htmx 的完整限制、性能边界、浏览器兼容性等事实暂未提供;关于收费、价格与官方支持政策,资料中暂未提供。