摘要：HTMX 超详细完整教程 htmx 是一个极小、零依赖的前端库，让你直接在 HTML 标签上通过属性实现： AJAX、Websocket、SSE、局部刷新、无刷新页面、加载动画、表单验证、懒加载、下拉刷新等所有现代交互，几乎不用写 JavaScript。 它的核心思想：让 HTML 恢复“超文本”本…

HTMX 超详细完整教程

htmx 是一个极小、零依赖的前端库，让你直接在 HTML 标签上通过属性实现：
AJAX、Websocket、SSE、局部刷新、无刷新页面、加载动画、表单验证、懒加载、下拉刷新等所有现代交互，几乎不用写 JavaScript。

它的核心思想：让 HTML 恢复“超文本”本该有的能力。

---

1. 基础信息

• 官网：https://htmx.org
• 大小：~14KB（gzip）
• 无依赖，直接引入即可使用
• 兼容所有后端：Java/PHP/Python/Node/.NET/Rails 等
• 后端只需要返回HTML 片段，不用 JSON，不用前端渲染

快速引入

<script src="https://unpkg.com/htmx.org@1.9.12"></script>

---

2. 核心属性体系（最重要）

所有功能都靠 hx-* 属性实现。

2.1 发起请求

hx-get          发起 GET
hx-post         发起 POST
hx-put          发起 PUT
hx-patch        发起 PATCH
hx-delete       发起 DELETE

示例：

<button hx-get="/api/hello">点我加载</button>

2.2 触发时机 hx-trigger

控制什么时候发请求。

常用触发：

• click 默认（按钮、a 标签）
• load 页面加载时
• mouseenter 鼠标移入
• keyup 键盘输入
• changed 值改变时
• every 1s 定时刷新

修饰符：

• delay:500ms 延迟发送（搜索防抖）
• throttle:1s 节流
• once 只触发一次

示例：实时搜索

<input
  hx-get="/search"
  hx-trigger="keyup changed delay:500ms"
>

2.3 目标位置 hx-target

把返回的 HTML 放到哪里。

支持：

• #id
• .class
• this 自身
• closest div
• next div 下一个元素

示例：

<button hx-get="/data" hx-target="#result">加载</button>
<div id="result"></div>

2.4 替换方式 hx-swap

控制如何插入返回内容。

可选值：

• innerHTML 默认，替换内部
• outerHTML 替换整个标签
• beforebegin 插入到前面
• afterbegin 插入到内部最前
• beforeend 插入到内部最后
• afterend 插入到后面
• none 不替换

2.5 只取返回的一部分 hx-select

后端返回完整页面，但你只想用其中一块：

hx-select="#content"

2.6 表单自动提交 hx-include

包含其他输入框的值：

hx-include="#form input"

2.7 同步/异步 hx-sync

防止重复请求，常用：

hx-sync="closest form:abort"

---

3. 最常用示例（直接复制可用）

3.1 点击局部刷新

<button hx-get="/user/info" hx-target="#box">加载用户</button>
<div id="box"></div>

3.2 无刷新表单提交

<form hx-post="/submit" hx-target="#msg">
  <input name="username">
  <button>提交</button>
</form>
<div id="msg"></div>

3.3 实时搜索

<input
  type="text"
  hx-get="/search"
  hx-trigger="keyup changed delay:500ms"
  hx-target="#result"
>
<div id="result"></div>

3.4 页面加载自动请求

<div hx-get="/news" hx-trigger="load"></div>

3.5 定时刷新（实时数据）

<div hx-get="/stats" hx-trigger="every 2s"></div>

3.6 确认删除

<button
  hx-delete="/item/1"
  hx-confirm="确定删除？"
>删除</button>

---

4. 进阶功能

4.1 页面无刷新跳转（SPA 效果）

<a href="/page" hx-boost="true">首页</a>

• 行为像单页应用
• 不刷新整个页面
• 自动更新历史记录

4.2 加载状态样式

htmx 会自动给正在请求的元素添加类：

htmx-request

你可以直接写 CSS：

.htmx-request { opacity:0.5; pointer-events:none; }

4.3 进度指示器

<div class="htmx-indicator">加载中...</div>

请求时自动显示，结束隐藏。

4.4 文件上传

<form hx-post="/upload" enctype="multipart/form-data">
  <input type="file" name="file">
  <button>上传</button>
</form>

4.5 下拉菜单（鼠标悬停加载）

<div hx-get="/menu" hx-trigger="mouseenter"></div>

4.6 对话框/模态框

后端返回模态框 HTML，直接插入即可。

---

5. 事件系统（hx-on:*）

不用写 JS，直接在标签上绑定事件：

hx-on:htmx:beforeRequest    请求前
hx-on:htmx:afterRequest     请求后
hx-on:htmx:success          成功
hx-on:htmx:error            失败
hx-on:htmx:sseMessage       SSE 消息

示例：

<button
  hx-get="/api"
  hx-on:htmx:error="alert('加载失败')"
>

---

6. 实时推送（WebSocket & SSE）

6.1 WebSocket

<div hx-ws="connect:/ws">
  <div id="msg"></div>
</div>

后端推送 HTML 片段，前端自动更新。

6.2 SSE（服务端推送）

<div hx-sse="connect:/sse">
  <div hx-sse="swap:message"></div>
</div>

---

7. 验证与错误处理

• 后端返回 4xx/5xx 会触发 htmx:error
• 可以返回带错误信息的 HTML 片段直接展示
• 支持 hx-validate 开启 HTML5 表单验证

---

8. 扩展机制（Extensions）

htmx 自带很多扩展：

• path-deps 路径缓存
• loading-states 加载状态
• remove-me 自动删除
• debug 调试

使用：

<script src="https://unpkg.com/htmx.org/dist/ext/loading-states.js"></script>

<button hx-ext="loading-states" data-loading>提交中</button>

---

9. HTMX 工作流程（理解原理）

1. 元素触发事件 →
2. htmx 发送 AJAX →
3. 后端返回HTML 片段 →
4. htmx 把片段插入到指定位置 →
5. 自动处理加载、动画、事件

全程不需要 JSON、不需要前端渲染、不需要虚拟DOM。

---

10. 适用场景

非常适合：

• 后台管理系统
• 内容网站
• 表单、列表、弹窗
• 服务端渲染项目（Razor、Django、Flask、Laravel、Thymeleaf）
• 不想写复杂前端框架的项目

不适合：

• 极高交互的超级应用（如在线文档、大型图床编辑器）
• 纯前后端分离、只提供 JSON 接口的项目

---

11. HTMX + Alpine.js（黄金组合）

• htmx：负责数据加载、请求、局部刷新
• alpine.js：负责前端状态、弹窗、折叠、显示隐藏

两者加起来不到 20KB，替代大部分 Vue/React 场景。

---