htmx | 用 HTML 属性构建 AJAX 与局部更新界面

htmx 是用 HTML 属性声明请求与局部更新的 JavaScript 库，采用 0BSD 许可。按钮、表单等元素可以通过 hx-get、hx-post 发请求，再把服务器返回的 HTML 放到指定位置。已有服务端模板的多页应用，可以用它增加局部交互，继续由后端渲染 HTML。

点一下按钮，服务器返回什么？

先看 v4.0.0 README 的基本用法。页面需要引入库，以下地址和完整性哈希取自该标签：

<script src="https://cdn.jsdelivr.net/npm/htmx.org@4.0.0/dist/htmx.min.js"
        integrity="sha384-BvJpBiO8Kh31EqtJe5DRIeWrHWnCGkwytKs9NKFi86Hhw96dEqdEMzZDeK9iEGTc"
        crossorigin="anonymous"></script>

<button hx-post="/clicked" hx-swap="outerHTML">点我</button>

点击按钮会向 /clicked 发 POST。hx-swap="outerHTML" 表示用响应替换整个按钮；后端必须实现这个地址，完成对应业务后返回合适的 HTML 片段。例如一次成功操作可以返回：

<p role="status">操作已完成</p>

这段响应是说明交换方式的假设示例。仅复制前端代码，没有后端路由，交互仍无法完成；接口如果只返回 JSON，也不会自动变成期望的页面结构。

htmx Clean 与 Dirty 复杂度对比官方插图 — htmx 官方仓库中的 Clean/Dirty 复杂度对比插图，用来表达减少不必要客户端复杂度的设计取向；它不是运行中的界面截图。来源：https://github.com/bigskysoftware/htmx/blob/master/www/static/img/clean-v-dirty.png

把局部交互拆成触发、目标和交换方式

什么时候请求：hx-trigger 选择事件。按钮通常默认 click，表单默认 submit；搜索输入等场景要明确触发频率。
请求哪里：hx-get、hx-post 等指向服务端地址，方法与业务行为应匹配。
更新哪里：hx-target 指定目标元素，例如 #results，避免替换无关区域。
怎样放入响应：hx-swap 决定替换内容、替换整个节点或追加。目标与返回结构需要配合。

例如按钮只更新旁边的结果区域，可以这样声明：

<button hx-get="/results" hx-target="#results" hx-swap="innerHTML">刷新结果</button>
<div id="results"></div>

这里 /results 应返回要放入容器的内容。用 innerHTML 时，容器本身保留；用 outerHTML 时，目标节点也会被替换，返回结构要保留后续交互需要的标识。明确这项区别，能减少“第一次能用、第二次找不到目标”的问题。

等待、失败和并发也属于交互。请求没结束时要显示状态，失败时要让用户知道是否保存，连续输入时要控制过期响应对页面的影响。库负责请求和交换，不会替业务决定重试、取消与冲突策略。

普通导航做通以后，再加渐进增强

hx-boost 可以把普通链接和表单增强为 AJAX；没有 JavaScript 时，它们仍依靠原本的 href、action 和方法工作。因此链接目标、完整页面和表单提交路径应先成立，再增加局部更新。

v4.0.0 文档在父元素批量增强时使用显式继承语法，示例如下：

<div hx-boost:inherited="true">
  <a href="/projects">项目</a>
  <a href="/settings">设置</a>
</div>

直接打开 URL、刷新页面和 AJAX 请求对返回内容的要求可能不同。服务端要能提供完整文档，也要按目标提供适合交换的内容；历史记录、焦点和滚动位置需要与页面结构一起安排。普通 href 不存在时，新增属性也无法提供有效的回退路径。

v4 标签和默认分支要分别核对

截至 2026 年 10 月 6 日，默认分支的包配置与 README 使用 2.0.11，v4.0.0 标签则有自己的 4.0.0 包和文档。本文代码按 v4.0.0 说明编写，不能用默认分支的 2.x 引入代码替换后，假定继承、导航和扩展行为都相同。

npm 包名是 htmx.org，README 特别提醒不要混淆另一个旧的 htmx 包。使用 npm、CDN 或自托管文件时，锁定同一版本；WebSocket、SSE 等扩展也要看匹配版本和加载方式，再处理连接、重连与消息权限。

局部返回的 HTML，也要经过后端校验

认证、授权、CSRF 防护和输入校验仍由服务端承担。响应中含用户内容时，要按 HTML 上下文转义或清洗；一个片段能够插入页面，不代表它可信。前端隐藏按钮也不能阻止未获准的请求。

可访问性同样需要具体处理。使用合适的按钮和表单语义，局部替换以后维持合理焦点，并让重要状态变化可以被感知。示例中的 role="status" 表达状态区域，但不能独自解决所有焦点和读屏问题。

htmx 更适合让服务器继续负责页面状态和 HTML 的应用。大量离线状态、复杂客户端交互或重型可视化，则需要根据任务比较其他方案。0BSD 允许使用、复制、修改和分发项目代码，第三方扩展与其他依赖仍需分别查看许可。

v4.0.0 引入与源码说明：https://github.com/bigskysoftware/htmx/tree/v4.0.0
v4.0.0 属性文档：https://github.com/bigskysoftware/htmx/tree/v4.0.0/www/src/content/reference/01-attributes
官方文档入口：https://htmx.org/docs/

1.本站所发布资源部分收集于网络，仅限用于学习和研究测试使用。2.本站资源售价仅为赞助网站，赞助收费仅用于网站维护运营更新，感谢您的支持。3.本站仅保证资源的正常下载和测试使用，售后不包含相关技术咨询服务，请知悉谅解。4.本站所发布资源为非实物商品，不接受退款，请考虑好再进行支付赞助获取下载。
赞助获取下载注意：
1.支付赞助成功后请勿关闭窗口或其他操作，等待系统自动确认，按钮变为获取下载按钮。2.游客操作请使用 Chrome、Edge 或 FireFox 浏览器，以免支付刷新失败(浏览器缓存7天有效)。3.如支付赞助成功后刷新无法显示下载按钮、链接失效等问题请到 【公告留言】 处理或参考下载说明文档。

THE END