htmx 4.0.0 已发布
摘要
htmx 4.0.0 已发布，主要变更包括显式属性继承、标准化事件名称，以及从 XMLHttpRequest 迁移至 fetch() API，与版本 2 相比行为差异极小。
<p><a href="https://lobste.rs/s/77uge9/htmx_4_0_0_has_been_released">评论</a></p>
查看缓存全文
缓存时间: 2026/08/28 17:39
# htmx 4.0.0 发布！来源：https://four.htmx.org/announcements/2026-08-28-htmx-4.0.0-is-released
## htmx 4.0.0 发布版 (https://four.htmx.org/announcements/2026-08-28-htmx-4.0.0-is-released#htmx-400-release)
htmx 团队非常高兴地宣布 htmx 4.0.0 发布！这是 8 个月工作（外加一个游戏 (https://four.htmx.org/game)）的成果，我们对结果非常满意。htmx 4 的构想始于我决定创建 fixi (https://fixiproject.org/) 之时，在这个过程中，我更熟悉了 JavaScript 中的 `fetch()` API 和异步编程。（由于向后兼容性问题，htmx 一直使用 XMLHttpRequest (https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest)。）
某个晚上，我偶然收到 Christian 的联系，他对于流式 HTML (https://four.htmx.org/docs#streaming-html) 有一些有趣的想法，这让我思考将内部实现迁移到 `fetch()` 会为他和整个库带来简化。经过一些工作，我成功说服了 Michael 和 Alex 加入，我们便开始了这项工作。开发过程非常顺利。
我们开始移植 fixi 加上 htmx 测试套件。随着时间的推移，我们重新理解了 htmx 做某些事情的原因，并让新的实现越来越接近旧版本。目前，2.x 和 4.x 之间的行为差异相对较小，并且在确实存在差异的地方，我们做出了明确的选择，认为这些选择将使基于 htmx 的应用能够成为面向未来的服务 (https://www.youtube.com/watch?v=lASLZ9TgXyc)。
请注意，我们**没有**在 NPM 中将 4.0 标记为 `latest` (https://docs.npmjs.com/cli/v10/commands/npm-dist-tag#purpose)，因为我们不想强制升级那些依赖非版本化 CDN 链接来使用 htmx 的用户。相反，2.x 将继续作为 `latest`，而 4.0 版本将在 2027 年初之前的某个时间点保持为 `next`。不过，网站将引用 4.0 版本。
### 主要变更 (https://four.htmx.org/announcements/2026-08-28-htmx-4.0.0-is-released#major-changes)
如上所述，从用户角度看，htmx 4 与 htmx 2 几乎相同。有三个主要变更：
- **属性继承现在默认显式而非隐式**（这是最大的升级项）
- htmx 事件名称已标准化和清理。一些高级用户可能需要更改他们监听的事件。
- 历史记录支持现在默认不再使用 `localStorage`（这曾是许多支持问题的根源）。大多数人完全不会注意到这一点。
在内部，我们从 `XMLHttpRequest` 迁移到了 `fetch()`，但这对大多数 htmx 用户来说应该是透明的。
#### 属性继承 (https://four.htmx.org/announcements/2026-08-28-htmx-4.0.0-is-released#attribute-inheritance)
在 htmx 2 中，许多属性默认是“继承”的。这允许你在父元素上放置属性，它们的行为将应用于子元素。这种行为源自 intercooler.js (https://intercoolerjs.org/) 时代，受 CSS 启发，结果也和 CSS 类似：功能强大但有时难以理解。
在 htmx 4 中，除非你明确说明 (https://four.htmx.org/docs#attribute-inheritance)（在属性名后添加 `:inherited`），否则属性不会继承：
```html
<button hx-delete="/article" hx-headers:inherited='{"X-CSRF-Token": "12345"}'>
Delete
</button>
```
这将是 htmx 2 升级到 htmx 4 时最大的负担。为了简化，我们提供了一个命令行工具 (https://four.htmx.org/docs#upgrade-checker) 来查找你需要标记为继承的位置。注意，像 `hx-disinherit` 等属性不再需要，应被移除。
#### 事件 (https://four.htmx.org/announcements/2026-08-28-htmx-4.0.0-is-released#events)
htmx 2 触发的事件随着库的发展而自然增长，组织得并不特别好，使得很难确切知道何时触发了哪个事件。在 htmx 4 中，所有事件现在都遵循 `htmx:phase:action[:sub-action]` 格式：
| htmx 2 事件 | htmx 4 事件 |
| :--- | :--- |
| `htmx:beforeRequest` | `htmx:before:request` |
| `htmx:afterRequest` | `htmx:after:request` |
| `htmx:beforeSwap` | `htmx:before:swap` |
| `htmx:afterSwap` | `htmx:after:swap` |
| `htmx:configRequest` | `htmx:config:request` |
此外，还进行了以下更改：
- 大多数错误事件合并为 `htmx:error` (https://four.htmx.org/reference/events/htmx-error)。HTTP 错误响应触发 `htmx:response:error` (https://four.htmx.org/reference/events/htmx-response-error)。
- `htmx:xhr:*` 事件被移除。htmx 4 使用 `fetch()`。
- `htmx:validation:*` 事件被移除，改用原生浏览器表单验证。
完整表格请参见 htmx 4 的新特性 (https://four.htmx.org/docs/whats-new-in-htmx-4)。命令行升级检查器会标记 `hx-on` 属性和它能在你的 JavaScript 中找到的旧事件名称。
#### 历史记录 (https://four.htmx.org/announcements/2026-08-28-htmx-4.0.0-is-released#history)
历史记录支持一直是 htmx 的一部分，允许你通过简单属性实现支持返回按钮的操作。在 htmx 2 中，使用 `localStorage` 中的缓存来存储页面快照以供恢复。不幸的是，一个主要问题是，这个快照可能包含第三方 JavaScript 库所做的 DOM 修改。当页面恢复时，这些修改仍然存在，但底层的 JavaScript 逻辑却不存在了。
htmx 4 不再在 `localStorage` 中缓存页面。在返回导航时，htmx 会重新获取页面并将其交换到 `<body>` 中，或者如果存在 `[hx-history-elt]` 元素，则交换到该元素中。这使得第三方 JavaScript 库在大多数情况下能够“正常工作”，并且在有良好请求缓存的情况下，速度非常快。
如果你想使用本地缓存，我们现在提供了一个非常完整的 `hx-history-cache` (https://four.htmx.org/extensions/hx-history-cache) 扩展，它从 `sessionStorage` 恢复历史记录，并旨在与 Alpine.js 等脚本解决方案良好集成。
### 新特性 (https://four.htmx.org/announcements/2026-08-28-htmx-4.0.0-is-released#new-features)
htmx 4 有两个我们非常兴奋的重大新特性：
#### 形态变换交换 (https://four.htmx.org/announcements/2026-08-28-htmx-4.0.0-is-released#morph-swaps)
我们现在开箱即用地支持形态变换交换 (https://four.htmx.org/docs#morphing-swaps)。我创建了 idiomorph (https://github.com/bigskysoftware/idiomorph)，并曾考虑将其包含在 htmx 2.x 中，但最终放弃了。在 htmx 4 中，Michael 做出了出色的工作，改进了该算法并将其无缝集成到 htmx 中。
#### `<hx-partial>` (https://four.htmx.org/announcements/2026-08-28-htmx-4.0.0-is-released#hx-partial)
另一个主要新特性是 `<hx-partial>` 标签。这个标签类似于带外交换 (https://four.htmx.org/docs#out-of-band-swaps)，但当你想做的不仅仅是用新版本替换单个元素时，它要清晰得多：
```html
<div hx-partial="/messages/new">
New message 5
</div>
```
#### 扩展 (https://four.htmx.org/announcements/2026-08-28-htmx-4.0.0-is-released#extensions)
htmx 4 的很多兴奋点在于扩展。内部切换到 `fetch()` 让我们重新思考扩展可以以及应该如何工作，并催生了许多新扩展的创建（或重建），例如：
- `hx-preload` - 预加载内容（例如在 `mouseover` 时）以加速请求。
- `hx-download` - 原生、基于 fetch 的文件下载。
- `hx-alpine-compat` - 妥善解决 htmx 与 Alpine.js (https://alpinejs.dev/) 之间的兼容性问题。
- `hx-history-cache` - 在 `sessionStorage` 中缓存历史记录，提供 Alpine.js 兼容性。
此外，还有三个新的或更新的流式 HTML 扩展：
- `hx-sse` (https://four.htmx.org/extensions/hx-sse) 通过 `text/event-stream` 进行流式传输。
- `hx-ws` (https://four.htmx.org/extensions/hx-ws) 通过 WebSockets 进行流式传输和发送。
- `hx-multipart` (https://four.htmx.org/extensions/hx-multipart) 通过 `multipart/mixed` 进行流式传输。
最后，我们认为是时候尝试自己的、与 htmx 紧密集成的小型前端脚本方案了。`hx-live` (https://four.htmx.org/extensions/hx-live) 受到 Alpine.js、jQuery (https://jquery.com/) 和 hyperscript (https://hyperscript.org/) 的启发，使前端脚本变得愉快而有趣。它甚至支持我们所称的基于 DOM 的、HATEOAS 友好的响应式。
在发布包中有一个新的 `htmax.js` (https://four.htmx.org/docs/htmax) 捆绑包，如果你想省心，它将 htmx 与最受欢迎的扩展打包在一个文件中。
### 升级 (https://four.htmx.org/announcements/2026-08-28-htmx-4.0.0-is-released#upgrading)
有关完整的升级指南，请参见 htmx 4 的新特性 (https://four.htmx.org/docs/whats-new-in-htmx-4)。如前所述，我们提供了一个升级工具来帮助你：
```console
$ npx [email protected] upgrade-check -- ./templates
File extensions: .html, .php, .js, .ts, .jinja, .jinja2, .j2, .erb, .hbs
Use --ext to add more (e.g. --ext .vue --ext .svelte)
Scanning 1 file(s)...
Found 8 issue(s) in 1 of 1 file(s).
templates/index.html:1: [inheritance] hx-headers needs :inherited suffix (descendant on line 3 has hx-delete) (this looks like a CSRF token; without :inherited the header does not reach child elements and the server rejects the request)
templates/index.html:2: [inheritance] hx-target needs :inherited suffix (descendant on line 3 has hx-delete)
templates/index.html:2: [inheritance] hx-confirm needs :inherited suffix (descendant on line 3 has hx-delete)
templates/index.html:3: [renamed-attr] hx-disable -> rename to hx-ignore (hx-disable now means 'disable during request')
templates/index.html:4: [removed-attr] hx-vars is removed -> use hx-vals with js: prefix
templates/index.html:4: [removed-attr] hx-prompt is removed -> load the hx-prompt extension to keep the same syntax
templates/index.html:9: [old-event] old event name "htmx:afterRequest" -> "htmx:after:request"
templates/index.html:9: [old-api] htmx.addClass() is removed -> use element.classList.add()
```
我们还提供了一个代理技能 (https://four.htmx.org/docs/editor-support#ai-coding-assistants) 来协助升级。
### 安装 (https://four.htmx.org/announcements/2026-08-28-htmx-4.0.0-is-released#installing)
htmx 4.0 可以通过包管理器引用版本 `4.0.0` 来安装，或者可以通过 CDN 链接：
```html
<script src="https://unpkg.com/[email protected]"></script>
```
或下载 (https://unpkg.com/[email protected]/dist/htmx.min.js)。
### 大型语言模型 (LLMs) (https://four.htmx.org/announcements/2026-08-28-htmx-4.0.0-is-released#llms)
无论你是否喜欢，很多人都在使用大型语言模型，我们为 LLMs 提供以下技能文件：
- `htmx-guidance` (https://raw.githubusercontent.com/bigskysoftware/htmx/v4.0.0/dist/skills/htmx-guidance.md) - 使用 htmx 4 开发的核心 htmx 技能。
- `htmx-debugging` (https://raw.githubusercontent.com/bigskysoftware/htmx/v4.0.0/dist/skills/htmx-debugging.md) - 在开发过程中诊断 htmx 问题。
- `htmx-extension-authoring` (https://raw.githubusercontent.com/bigskysoftware/htmx/v4.0.0/dist/skills/htmx-extension-authoring.md) - 编写和调试 htmx 4 扩展。
- `htmx-upgrade-from-htmx2` (https://raw.githubusercontent.com/bigskysoftware/htmx/v4.0.0/dist/skills/htmx-upgrade-from-htmx2.md) - 将代码库从 htmx 2.x 迁移到 4.x（让我们暂且不讨论在 LLM 时代发布库的新版本是好是坏！）。
### 总结 (https://four.htmx.org/announcements/2026-08-28-htmx-4.0.0-is-released#conclusion)
我们希望你喜欢 htmx 4。htmx 2 将继续无限期地得到支持，所以不要感到升级的压力。
我想感谢以下人员对本次发布的所有帮助：
- Michael West (https://github.com/MichaelWest22) - 非凡的队友与务实的开发者
- Christian Tanul (https://github.com/scriptogre) - 启发了 htmx 4 并主导了流式和实时扩展
- Alex Petros (https://github.com/alexpetros) - 稳定了项目方向
- Stephen Mitchell - 游戏 (https://four.htmx.org/game) 背后的天才
- Stu Kennedy - 我们的 WebSockets 专家
- André Ahlert Jr. - 提供 IDE 和编辑器支持
- Dien Hoa Truong - 在早期 htmx 4 上进行测试并帮助修复了许多错误
### 升级音乐 (https://four.htmx.org/announcements/2026-08-28-htmx-4.0.0-is-released#upgrade-music)
没有升级音乐的 htmx 更新是不完整的：[升级播放列表链接](https://open.spotify.com/playlist/5Z9iiGl2FcIfaYzmDGqLyr?si=d321f6459e9c46e1)
相似文章
@htmx_org: 非常高兴宣布 htmx 4 的发布！
htmx 宣布发布其 HTML 扩展库版本 4，该库用于构建现代 Web 界面。
bigskysoftware/htmx
htmx 是一个 JavaScript 库，通过简单的 HTML 属性支持构建现代用户界面，实现 AJAX、CSS 过渡和其他交互，从而简化 Web 开发。
HTMX 太酷了，我自己写了一个
本文探讨了 HTMX 这个库，它偏爱服务器端渲染的 HTML，而非大量使用 JavaScript 的前端。作者发现 HTMX 对于持久化的 UI 组件很有用，但最终出于个人对最小依赖的偏好，决定自己实现一套解决方案。
我如何将 HTMX 与 Go 结合使用
这篇博文由 Alex Edwards 撰写，解释了如何将 HTMX 与 Go 集成以构建服务端渲染的 Web 应用程序，涵盖了模板结构、局部响应、重定向和错误处理。
Let's make the worst Htmx
A blog post that humorously builds a minimal 'worst' clone of the htmx library, showing how to recreate its core behavior (triggers, fetches, and swaps) in vanilla JavaScript.