Htmx 4.0 正式发布：属性继承显式化、事件标准化、支持流式HTML

Htmx 4.0 发布公告页面截图 — 头图来源： Wikimedia Commons（请在文件页查看原作者与许可条款）

发布概述

Htmx 团队正式宣布 Htmx 4.0.0 发布，这是自 2.x 以来的一次重大更新。开发历时 8 个月，期间团队还制作了一款小游戏作为铺垫。本次升级的核心动机是内部从 XMLHttpRequest 迁移到 fetch()，以更好地支持流式 HTML 和现代异步编程。

Htmx 4.0 在用户视角上与 2.x 高度相似，但带来了三项重大变更：属性继承改为显式、事件命名标准化、历史记录不再默认使用 localStorage。此外，团队表示不会在 NPM 上将 4.0 标记为 latest，以免强制升级依赖 CDN 链接的用户，2.x 将继续作为默认版本至 2027 年初。

重大变化

属性继承显式化

在 Htmx 2 中，许多属性（如 hx-confirm、hx-target）会默认从父元素继承给子元素，这种设计虽灵活但容易造成混淆。Htmx 4 废除了隐式继承，现在开发者必须在属性名后添加 :inherited 后缀才能开启继承。例如：

旧写法：<div hx-confirm="Are you sure?"><button hx-delete="/item/1">Delete</button></div>
新写法：<div hx-confirm:inherited="Are you sure?"><button hx-delete="/item/1">Delete</button></div>

此变更将是升级中最大的工作量，但团队提供了命令行工具来自动检测需要标记的位置，同时废弃的 hx-disinherit 等属性应被移除。

事件命名标准化

Htmx 2 的事件名缺乏统一规范，难以判断触发时机。Htmx 4 采用了 htmx:phase:action[:sub-action] 的三段式命名。例如：

htmx:beforeRequest → htmx:before:request
htmx:afterRequest → htmx:after:request
htmx:configRequest → htmx:config:request

此外，大多数错误事件合并为 htmx:error，HTTP 错误响应触发 htmx:response:error，移除了所有 htmx:xhr:* 事件（因为改用 fetch），并弃用了 htmx:validation:* 事件，转而使用原生浏览器表单验证。升级工具可以检测旧事件名并给出提示。

历史记录改进

Htmx 2 使用 localStorage 缓存页面快照，但第三方 JavaScript 库的 DOM 突变会残留在快照中，导致恢复时出现逻辑不一致。Htmx 4 不再默认缓存页面到 localStorage，而是通过重新请求页面并交换到 <body> 或 [hx-history-elt] 元素来实现后退导航。配合良好的请求缓存，这种方式速度很快。如果用户需要本地缓存，官方提供了 hx-history-cache 扩展，支持 sessionStorage 并与 Alpine.js 等脚本方案集成。

新特性

Morph Swaps

Htmx 4 原生支持形态交换（Morphing Swaps），基于 idiomorph 算法。该算法由 Michael 在 Htmx 2 时已开发但未纳入，此次由 Michael 进一步优化并平滑集成，使得页面元素更新时能更加智能地保留状态。

`<hx-partial>` 标签

这是另一个重大新特性，类似于带外交换（Out-of-Band Swaps），但语义更清晰。开发者可以在 HTML 响应中嵌入多个 <hx-partial> 标签，每个标签指定不同的 hx-target 和 hx-swap，从而实现一次性更新多个 DOM 区域。例如：

<hx-partial hx-target="#messages" hx-swap="beforeend"><div>New message</div></hx-partial>
<hx-partial hx-target="#count"><span>5</span></hx-partial>

扩展生态

切换到 fetch() 后，扩展机制得以重构，催生了大量新扩展：

hx-preload：预加载内容（如鼠标悬停时），加速请求
hx-download：基于 fetch 的原生文件下载
hx-alpine-compat：平滑 Htmx 与 Alpine.js 的兼容性
hx-history-cache：将历史记录缓存到 sessionStorage，并提供 Alpine.js 兼容
hx-sse、hx-ws、hx-multipart：分别支持 SSE、WebSocket 和 multipart/mixed 流式 HTML
hx-live：团队自研的轻量级前端脚本方案，融合 Alpine.js、jQuery 和 hyperscript，支持 DOM 级 HATEOAS 响应式

此外，官方还提供了 htmax.js 捆绑包，将最流行的扩展打包成一个文件，方便直接使用。

升级工具与指南

团队提供了完整的升级指南，并发布了一个命令行工具 npx htmx.org@4.0.0 upgrade-check -- ./templates，可以扫描项目中的 HTML、PHP、JS、TS 等文件，自动检测以下问题：

需要添加 :inherited 后缀的属性
已重命名的属性（如 hx-disable → hx-ignore）
已移除的属性（如 hx-vars → 使用 hx-vals 的 js: 前缀）
旧的事件名称
已移除的 API（如 htmx.addClass() → 使用原生 element.classList.add()）

同时，为适应 LLM 时代，团队提供了多个 LLM 技能文件，帮助开发者通过 AI 辅助升级和开发：

htmx-guidance：核心开发技能
htmx-debugging：调试诊断
htmx-extension-authoring：扩展编写
htmx-upgrade-from-htmx2：从 2.x 迁移到 4.x

安装方式

可以通过 CDN 或包管理器安装：

CDN：<script src="https://unpkg.com/htmx.org@4.0.0/dist/htmx.min.js"></script>
包管理器：指定版本 4.0.0

结语

Htmx 4 代表了库的一次重要演进，在保持极简 API 的同时，增强了现代性和可维护性。团队强调 2.x 将继续获得无限期支持，用户无需急于升级。感谢 Michael West、Christian Tanul、Alex Petros 等核心贡献者以及社区的支持。

原标题：Htmx 4.0。 HN 原始发布时间：2026年8月28日星期五。当前记录为 798 分、212 条评论。

阅读原文 · 查看 HN 讨论