htmx 2.x 迁移完整指南7 处破坏性变更与旧行为恢复方法【免费下载链接】htmxhtmx - high power tools for HTML项目地址: https://gitcode.com/GitHub_Trending/ht/htmxhtmx 从 1.x 升到 2.x全部 7 处破坏性变更可以分成三类3 处加几行配置就能恢复3 处要动语法或依赖1 处直接决定你能不能升。这篇文章给出变更清单和一套升级后能直接执行的检查顺序按它做完你当天就能合入 2.x 而不留尾巴。我的项目现在能不能升 htmx 2.x先看两个硬条件。产品端还有 Internet Explorer 的硬性需求留在 1.x 线2.0 已放弃 IE官方表示 1.x 线会在可预见的未来继续支持 IE。你写过内部扩展、调用了selectAndSwap内部 API先把调用迁移到新的swap方法再升主包。其余场景——包括大量使用hx-get、hx-post、hx-boost的普通页面——直接升即可。htmx 对向后兼容给了极高优先级官方迁移文档的说法是绝大多数项目几乎不需要改动。升完之后最容易坏的四个场景是内容交换不再平滑滚动DELETE 的参数从请求体跑进了 URL query跨域请求被新的同源默认值拦下用旧hx-on属性绑的事件处理器静默失效。后面逐一对应解法。零改动这部分你不用动任何手指用script src...htmx.js加载的项目/dist/htmx.js在 2.x 里继续面向浏览器提供路径和用法不变只换版本号就行。模块化工程里发行文件按模块体系拆分了构建逻辑见 scripts/dist.shESM/dist/htmx.esm.jsAMD/dist/htmx.amd.jsCJS/dist/htmx.cjs.jsnpm install的项目不用手动选2.0.1 起 package.json 的main已指向 ESM 文件见 CHANGELOG.md。其余hx-*属性行为基本未变存量页面升级后照常渲染、照常发请求——这就是可以放心升的原因核心交换与请求链路本身没有改签名。只加几行配置三个新默认值怎么恢复旧行为三项变更全部通过htmx.config覆盖配置对象在 src/htmx.js 中定义当前默认值一览见 api.md。内容交换为什么不再平滑滚动旧行为swap 后目标元素平滑滚入视口。新行为一步到位scrollBehavior默认instant它直接决定scrollIntoView的滚动方式。恢复一行htmx.config.scrollBehavior smooth也可用auto交还给 CSS 决定。DELETE 的参数为什么进了 URL旧行为DELETE 的参数编码进请求体。新行为参数走 query stringmethodsThatUseUrlParams默认[get, delete]发请求时 htmx 按 verb 查这个列表决定编码方式。依据是 HTTP 规范里 DELETE 本应像 GET 一样使用请求参数这属于规范对齐。后端如果还在读 body恢复一行htmx.config.methodsThatUseUrlParams [get]。跨域请求为什么开始被拦截旧行为跨域可用。新行为请求发出前检查来源非同源直接拦下selfRequestsOnly默认true这是安全加固。确实需要跨域时恢复一行htmx.config.selfRequestsOnly false——放开的是 htmx 这层限制请求最终能否成功仍取决于服务端 CORS。必须动代码四处要亲手改hx-on 事件处理器不生效了改用 hx-on: 语法症状老写法hx-on事件名: 脚本的特殊语法在 2.0 已被移除CHANGELOG.md 2.0.0 条目升级后处理器不执行且不报任何错是最容易被漏掉的。旧写法迁到新写法!-- 1.x -- button hx-onhtmx:beforeRequest: alert(hi) !-- 2.x -- button hx-on:htmx:before-requestalert(hi)这里最容易踩的坑HTML 属性名会被浏览器小写化hx-on:htmx:beforeRequest里的大写字母会损坏事件名必须写 kebab-case 的before-request。嫌htmx:啰嗦可以用双冒号简写hx-on::before-requestJSX 环境还可把冒号换成连字符hx-on 文档 有对照。另外同一个元素上两种形式不能混用存在hx-on:*时旧hx-on的值会被静默忽略。makeFragment 现在永远返回 DocumentFragment症状如果你的代码按返回类型分支比如fragment instanceof Element的判断升级后该分支恒为假按 Element 读属性拿到 undefined。1.x 中makeFragment可能返回Element或DocumentFragment2.x 起完整页面、body 片段、部分 HTML 一律组装成DocumentFragment实现见 src/htmx.js 的makeFragment函数完整页面响应的title存在fragment.title上。坑不在类型本身而在它是一个元素的假设对片段容器做querySelector没问题直接读fragment.tagName就断。把调用方统一按片段容器处理即可。内部 API selectAndSwap 没了swap 接管症状扩展代码直接抛方法不存在。这一条只影响扩展作者。新的调用序列是三步let target api.getTarget(child); let swapSpec api.getSwapSpecification(child); api.swap(target, content, swapSpec);swap同时挂在公开 API 上普通应用代码可以用htmx.swap(#output, divhi/div, {swapStyle: innerHTML})直接驱动交换——注意swapStyle是必填项完整参数在 api.md 的swap一节。最容易踩的坑getSwapSpecification是从元素上的hx-swap属性解析出来的如果你手工构造 swapSpecswapDelay、settleDelay、scroll这些字段不会自动带上动手前先确认目标元素真实挂了哪些交换修饰符。扩展不再随核心分发SSE 扩展必须升到 2.x症状升级后 WebSocket / SSE 连接的页面不再更新。1.x 的扩展打包在核心发行包里2.x 全部移出、独立分发2.0.0 条目同时移除了旧的hx-ws、hx-sse属性。两条要求SSE 扩展必须升到 2.x 版本否则不工作其余扩展建议一并升到 2.x。旧属性要迁到扩展写法例如hx-sse换成hx-extsse交换订阅改用新的sse-swap属性声明完整对照表在 extensions/sse.md。⚠️ 这里最容易踩的坑是多数 1.x 扩展仍能在 2.x 下工作这句话——仍工作不等于不用升SSE 是唯一的强制项。IE 正式退役2.0 不再支持 IE1.x 线继续支持且这是单行道升级后没有配置开关能找回 IE 路径。所以这一条要在能不能升那一步就定下来而不是升到一半才发现。升级后怎么确认没坏按这个顺序查加载打开页面控制台无报错模块导入指向新的 ESM 文件事件全仓库 grephx-on命中的都是未迁移的旧形式手动触发一次请求确认before-request/after-requestkebab-case仍然触发请求回归 DELETE 接口确认参数位置与后端预期一致不一致就恢复methodsThatUseUrlParams跨域观察请求是否被拦被拦就恢复selfRequestsOnly false扩展确认 SSE 扩展已是 2.xgrep 全库hx-ws、hx-sse无残留旧 APIgrepselectAndSwap以及makeFragment附近的instanceof Element判断。哪些操作可以随时回退配置层是最可回退的三条覆盖都是运行时语句删掉即回到新默认整个发行文件换回 1.x 就是完整基线。事件语法迁移是最不可回退的部分——2.x 已移除旧hx-on形式建议把语法转换单独放一个提交出问题 revert 这一个提交即可。版本线本身就是天然退路1.x 仍在维护且支持 IE先钉在 1.x、下个迭代再迁永远是成立的选项。【免费下载链接】htmxhtmx - high power tools for HTML项目地址: https://gitcode.com/GitHub_Trending/ht/htmx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
htmx 2.x 迁移完整指南：7 处破坏性变更与旧行为恢复方法
htmx 2.x 迁移完整指南7 处破坏性变更与旧行为恢复方法【免费下载链接】htmxhtmx - high power tools for HTML项目地址: https://gitcode.com/GitHub_Trending/ht/htmxhtmx 从 1.x 升到 2.x全部 7 处破坏性变更可以分成三类3 处加几行配置就能恢复3 处要动语法或依赖1 处直接决定你能不能升。这篇文章给出变更清单和一套升级后能直接执行的检查顺序按它做完你当天就能合入 2.x 而不留尾巴。我的项目现在能不能升 htmx 2.x先看两个硬条件。产品端还有 Internet Explorer 的硬性需求留在 1.x 线2.0 已放弃 IE官方表示 1.x 线会在可预见的未来继续支持 IE。你写过内部扩展、调用了selectAndSwap内部 API先把调用迁移到新的swap方法再升主包。其余场景——包括大量使用hx-get、hx-post、hx-boost的普通页面——直接升即可。htmx 对向后兼容给了极高优先级官方迁移文档的说法是绝大多数项目几乎不需要改动。升完之后最容易坏的四个场景是内容交换不再平滑滚动DELETE 的参数从请求体跑进了 URL query跨域请求被新的同源默认值拦下用旧hx-on属性绑的事件处理器静默失效。后面逐一对应解法。零改动这部分你不用动任何手指用script src...htmx.js加载的项目/dist/htmx.js在 2.x 里继续面向浏览器提供路径和用法不变只换版本号就行。模块化工程里发行文件按模块体系拆分了构建逻辑见 scripts/dist.shESM/dist/htmx.esm.jsAMD/dist/htmx.amd.jsCJS/dist/htmx.cjs.jsnpm install的项目不用手动选2.0.1 起 package.json 的main已指向 ESM 文件见 CHANGELOG.md。其余hx-*属性行为基本未变存量页面升级后照常渲染、照常发请求——这就是可以放心升的原因核心交换与请求链路本身没有改签名。只加几行配置三个新默认值怎么恢复旧行为三项变更全部通过htmx.config覆盖配置对象在 src/htmx.js 中定义当前默认值一览见 api.md。内容交换为什么不再平滑滚动旧行为swap 后目标元素平滑滚入视口。新行为一步到位scrollBehavior默认instant它直接决定scrollIntoView的滚动方式。恢复一行htmx.config.scrollBehavior smooth也可用auto交还给 CSS 决定。DELETE 的参数为什么进了 URL旧行为DELETE 的参数编码进请求体。新行为参数走 query stringmethodsThatUseUrlParams默认[get, delete]发请求时 htmx 按 verb 查这个列表决定编码方式。依据是 HTTP 规范里 DELETE 本应像 GET 一样使用请求参数这属于规范对齐。后端如果还在读 body恢复一行htmx.config.methodsThatUseUrlParams [get]。跨域请求为什么开始被拦截旧行为跨域可用。新行为请求发出前检查来源非同源直接拦下selfRequestsOnly默认true这是安全加固。确实需要跨域时恢复一行htmx.config.selfRequestsOnly false——放开的是 htmx 这层限制请求最终能否成功仍取决于服务端 CORS。必须动代码四处要亲手改hx-on 事件处理器不生效了改用 hx-on: 语法症状老写法hx-on事件名: 脚本的特殊语法在 2.0 已被移除CHANGELOG.md 2.0.0 条目升级后处理器不执行且不报任何错是最容易被漏掉的。旧写法迁到新写法!-- 1.x -- button hx-onhtmx:beforeRequest: alert(hi) !-- 2.x -- button hx-on:htmx:before-requestalert(hi)这里最容易踩的坑HTML 属性名会被浏览器小写化hx-on:htmx:beforeRequest里的大写字母会损坏事件名必须写 kebab-case 的before-request。嫌htmx:啰嗦可以用双冒号简写hx-on::before-requestJSX 环境还可把冒号换成连字符hx-on 文档 有对照。另外同一个元素上两种形式不能混用存在hx-on:*时旧hx-on的值会被静默忽略。makeFragment 现在永远返回 DocumentFragment症状如果你的代码按返回类型分支比如fragment instanceof Element的判断升级后该分支恒为假按 Element 读属性拿到 undefined。1.x 中makeFragment可能返回Element或DocumentFragment2.x 起完整页面、body 片段、部分 HTML 一律组装成DocumentFragment实现见 src/htmx.js 的makeFragment函数完整页面响应的title存在fragment.title上。坑不在类型本身而在它是一个元素的假设对片段容器做querySelector没问题直接读fragment.tagName就断。把调用方统一按片段容器处理即可。内部 API selectAndSwap 没了swap 接管症状扩展代码直接抛方法不存在。这一条只影响扩展作者。新的调用序列是三步let target api.getTarget(child); let swapSpec api.getSwapSpecification(child); api.swap(target, content, swapSpec);swap同时挂在公开 API 上普通应用代码可以用htmx.swap(#output, divhi/div, {swapStyle: innerHTML})直接驱动交换——注意swapStyle是必填项完整参数在 api.md 的swap一节。最容易踩的坑getSwapSpecification是从元素上的hx-swap属性解析出来的如果你手工构造 swapSpecswapDelay、settleDelay、scroll这些字段不会自动带上动手前先确认目标元素真实挂了哪些交换修饰符。扩展不再随核心分发SSE 扩展必须升到 2.x症状升级后 WebSocket / SSE 连接的页面不再更新。1.x 的扩展打包在核心发行包里2.x 全部移出、独立分发2.0.0 条目同时移除了旧的hx-ws、hx-sse属性。两条要求SSE 扩展必须升到 2.x 版本否则不工作其余扩展建议一并升到 2.x。旧属性要迁到扩展写法例如hx-sse换成hx-extsse交换订阅改用新的sse-swap属性声明完整对照表在 extensions/sse.md。⚠️ 这里最容易踩的坑是多数 1.x 扩展仍能在 2.x 下工作这句话——仍工作不等于不用升SSE 是唯一的强制项。IE 正式退役2.0 不再支持 IE1.x 线继续支持且这是单行道升级后没有配置开关能找回 IE 路径。所以这一条要在能不能升那一步就定下来而不是升到一半才发现。升级后怎么确认没坏按这个顺序查加载打开页面控制台无报错模块导入指向新的 ESM 文件事件全仓库 grephx-on命中的都是未迁移的旧形式手动触发一次请求确认before-request/after-requestkebab-case仍然触发请求回归 DELETE 接口确认参数位置与后端预期一致不一致就恢复methodsThatUseUrlParams跨域观察请求是否被拦被拦就恢复selfRequestsOnly false扩展确认 SSE 扩展已是 2.xgrep 全库hx-ws、hx-sse无残留旧 APIgrepselectAndSwap以及makeFragment附近的instanceof Element判断。哪些操作可以随时回退配置层是最可回退的三条覆盖都是运行时语句删掉即回到新默认整个发行文件换回 1.x 就是完整基线。事件语法迁移是最不可回退的部分——2.x 已移除旧hx-on形式建议把语法转换单独放一个提交出问题 revert 这一个提交即可。版本线本身就是天然退路1.x 仍在维护且支持 IE先钉在 1.x、下个迭代再迁永远是成立的选项。【免费下载链接】htmxhtmx - high power tools for HTML项目地址: https://gitcode.com/GitHub_Trending/ht/htmx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
