# htmx

> 分类：`libs/state-dom/` · 档位：**评估** · 更新时间：2026-11-17

## 1. 基本信息

| 项 | 内容 |
|---|---|
| 当前版本 | 2.x |
| License | BSD 2-Clause（以仓库为准） |
| 维护方 | Big Sky Software（Carson Gross） |
| 仓库 / 文档 | https://github.com/bigskysoftware/htmx · https://htmx.org |
| 最近 release | 见官方 releases |

## 2. 一句话定位

用 HTML 属性发起 AJAX、把服务端返回的 HTML 片段换进页面。交互逻辑留在服务端，前端不写请求与状态代码。
它适合"服务端渲染 + 局部刷新"，不适合重客户端状态与复杂前端编排。

## 3. 体积

| 引入方式 | min | gzip |
|---|---|---|
| htmx.min.js | 约 48 KB | 约 14 KB（第三方口径，待实测） |

无依赖、无构建要求。

## 4. 核心 API

```html
<button hx-get="/cart" hx-target="#cart" hx-swap="innerHTML">刷新购物车</button>

<form hx-post="/search"
      hx-trigger="input changed delay:300ms"
      hx-target="#results">
  <input name="q">
</form>
```

```js
htmx.on('htmx:afterSwap', (e) => { /* 片段替换后 */ });
htmx.config.historyCacheSize = 10;
```

## 5. 适用 / 不适用

- **适用**：Django / Rails / Laravel / Express 模板类应用、后台表单、渐进增强、想减少前端 JS 的项目。
- **不适用**：重客户端状态、离线 SPA、需要复杂动画编排或大量前端派生数据的界面。

## 6. 硬缺口与已知坑

- 服务端必须返回 HTML 片段；返回整页会把布局套进局部。
- 局部替换会丢失焦点、滚动位置与未提交状态，需要 `hx-preserve`、`hx-settle` 或手动恢复。
- CSRF 要自己通过 `hx-headers` 注入 token。
- `hx-on` 等特性涉及内联脚本，严格 CSP 下需要调整策略。
- 历史记录要显式 `hx-push-url`，否则前进后退行为不符合预期。
- 错误处理依赖 `htmx:responseError` 等事件，默认提示很弱。

## 7. 受限环境可用性

| 环境 | 结论 | 说明 |
|---|---|---|
| 无构建 | 可用 | 一个 `<script>` 即可 |
| ESM / 打包器 | 可用 | 也提供 npm 包 |
| SSR | 天然适配 | 服务端输出 HTML 就是它的工作方式 |
| 动态插入区块 | 可用 | 属性在替换后依然生效 |

## 8. 稳定性评分

| 维度 | 评分 | 依据 |
|---|---|---|
| 维护活跃度 | 5 | 2.x 持续迭代 |
| 版本与破坏性变更 | 4 | 2.0 有迁移说明 |
| 采用度 | 4 | 服务端框架社区采用明显 |
| 体积与按需 | 5 | 约 14 KB，无依赖 |
| 生态兼容 | 5 | 任何后端模板都能配合 |
| License | 5 | BSD 2-Clause |

## 9. 替代品对比

| 方案 | 优势 | 劣势 | 何时选它 |
|---|---|---|---|
| Turbo | Rails 生态成熟、整页导航增强 | 与 htmx 的局部刷新模型不同 | Rails / Hotwire |
| Stimulus | 轻量控制器、与 HTML 共存 | 请求与替换要自己写 | 需要少量行为增强 |
| Unpoly | 局部刷新 + 更多 UI 原语 | 生态小于 htmx | 复杂服务端页面 |
| Alpine + fetch | 状态与请求都自己掌控 | 模板代码更多 | 需要前端状态 |
