htmx 如何升级1.x 到 2.x 的平滑迁移自评一下再动手【免费下载链接】htmxhtmx - high power tools for HTML项目地址: https://gitcode.com/GitHub_Trending/ht/htmx本文带你完成 htmx 从 1.x 到 2.x 的大版本升级先做个自评判断自己的项目受不受影响再按换发行文件、重写事件语法、恢复默认值三步动手最后附上扩展迁移、验收清单和随时可执行的回退方案。 先做个自评这次升级会伤到你吗htmx 团队对向后兼容很上心官方迁移文档 的原话是多数情况下几乎不用改代码。但确实有一批破坏性变更对照下表先给自己定性你的情况受影响吗建议动作只是script src.../htmx.js引入没用过事件内联基本无感直接换文件升 2.x模板里有hx-on属性是逐个改写为hx-on:页面间有跨域请求是会被默认拦截关闭selfRequestsOnlyDELETE接口靠请求体传参是参数会改走 URL按后端能力决定是否回退配置依赖 swap 后平滑滚动轻微恢复scrollBehavior自定义扩展里调过selectAndSwap是API 已移除改用swap还必须支持 IE是2.x 不再支持 IE留在 1.x不升结论只要不碰事件内联语法和跨域/IE这两条你的升级成本就是换一下文件。 动手前的清点升级前花十分钟把这几项过一遍每项后面都告诉你为什么值得查你引用的是哪个发行文件2.x 把构建产物按模块体系拆成了多个文件见 scripts/dist.sh用错文件会直接 import 失败。全库搜一下hx-on旧hx-on语法在 2.x 中被移除CHANGELOG 2.0.0 条目这是本次升级唯一必须动手改的语法。列出你在用的扩展清单所有扩展已从核心发行包移出、独立分发其中SSE 扩展必须用 2.x 版本才兼容。搜一下hx-ws、hx-sse这两个 1.x 遗留属性在 2.0 已删除要换成对应扩展的写法。确认是否存在跨域请求和 DELETE 传参这两项对应 2.x 新默认值不改配置就会变行为。看自己的代码有没有直接调htmx.makeFragment()2.x 中它永远返回DocumentFragment见 src/htmx.js 中makeFragment的实现1.x 里为Element返回写的分支要删掉。确认是否还有 IE 用户有就整体锁在 1.x1.x 线会继续维护 IE 支持。 三步完成升级第一步替换发行文件2.x 的构建脚本 scripts/dist.sh 会产出四个文件按你的模块体系选模块体系文件ESMimport/dist/htmx.esm.jsAMDRequireJS 等/dist/htmx.amd.jsCommonJSNode/dist/htmx.cjs.js浏览器script直连/dist/htmx.js与 1.x 同名无需改路径另外注意 package.json2.0.1 起 npm 包的main指向dist/htmx.esm.js也就是说通过 npm 安装的用户入口文件自动就换成了 ESM 版。第二步把hx-on改写成hx-on:旧写法是在一个属性里塞多个事件名: 脚本新写法是一个事件一个属性事件名直接挂在属性名后面!-- 1.x -- button hx-get/info hx-onhtmx:beforeRequest: alert(发请求了)!-- 2.x -- button hx-get/info hx-on:htmx:before-requestalert(发请求了)三个要点事件名必须用 kebab-casehx-on:htmx:beforeRequest不生效因为 HTML 属性名不区分大小写浏览器会把属性名小写化大写字母会被吃掉。写hx-on:htmx:before-request才能稳定匹配详见 www/content/attributes/hx-on.md。htmx 事件可省命名空间hx-on::before-request等价于hx-on:htmx:before-request更省事。模板语言不喜欢冒号连字符形式等价可用hx-on-htmx-before-request、hx-on--before-requestJSX 场景友好。同一个元素上hx-on与hx-on:*不能共存两者同时存在时旧属性会被忽略——所以要么全改完要么混用在不同元素上。第三步恢复被重置的默认值可选按口味可以把这次默认值变更理解成出厂设置被重置了三项全局配置在 2.x 里换了新出厂值都在 src/htmx.js#L211 附近的默认配置对象里。配置项2.x 出厂值1.x 行为想回到 1.x 就写scrollBehaviorinstant瞬时滚动smooth平滑滚动见下方代码methodsThatUseUrlParams[get, delete][get]见下方代码selfRequestsOnlytrue仅同源false允许跨域见下方代码为什么改DELETE不算疯按 HTTP 规范DELETE本就该像GET一样用查询参数而不是请求体2.x 是把行为纠正到规范一侧。如果你的后端一直从 DELETE 请求体里读参数就恢复旧行为如果你的后端本来就解析查询串保持默认即可还能白捡一个合规性。// 想保留 1.x 体验加载 htmx 后执行按需取用 htmx.config.scrollBehavior smooth; htmx.config.methodsThatUseUrlParams [get]; htmx.config.selfRequestsOnly false; 特殊场景你是扩展作者内部 API 里的selectAndSwap被移除了替身是swap它同时挂在了公开 API 上。迁移套路是解析目标 → 取交换规格 → 调 swaplet content divHello world/div; let target api.getTarget(child); let swapSpec api.getSwapSpecification(child); // 自动读取元素上的 hx-swap api.swap(target, content, swapSpec);普通开发者同样能用htmx.swap(#output, divSwapped!/div, {swapStyle: innerHTML})一行就能驱动内容交换swapSpec支持swapStyle必填、swapDelay、settleDelay、scroll/show等字段完整签名见 www/content/api.md 的swap小节。你有跨域请求2.x 的selfRequestsOnly: true会在请求发出前把非同源请求拦下src/htmx.js#L241。确认是业务必需后设selfRequestsOnly false但记住这只是放开 htmx 自己这道门跨域能不能通最终看服务端 CORS。你还有 IE 用户那就别升了。htmx 2.x 放弃 IE1.x 版本线会继续支持官方迁移文档 明确说了 1.x 在可预见的未来都会继续支持。等 IE 流量自然归零再动不迟。✅ 验收与回退按序勾一遍再合主线控制台无报错htmx.version是 2.x。全站搜不到hx-on注意匹配等号避免误伤hx-on:。手动点一遍带hx-on:*的交互重点回归请求前后的事件。触发一次 DELETE 接口抓包确认参数在 URL 还是 body与后端约定一致。若做过跨域场景确认请求没有被selfRequestsOnly拦截。SSE/WS 等扩展均已换成 2.x 独立包版本页面上无hx-ws/hx-sse。跑一遍你自己的测试套件尤其关注 swap 相关断言。回退方案升级时别删 1.x 的发行文件把它挪到/dist/htmx-1.x.js留作后手htmx.config的三项恢复代码用条件包裹比如按版本或环境变量开关。真出问题就把script指回 1.x 文件——三项配置覆盖只存在于你的初始化脚本里撤掉即可页面模板层面的hx-on:与hx-on在同元素下互不干扰混用不同元素是允许的回退窗口期很短。写在最后htmx 1.x 到 2.x 的升级真正必须动手改的其实只有一处hx-on改hx-on:而且记得事件名全部小写横线化。剩下的都是默认值口味问题——滚动快慢、DELETE 走 URL 还是 body、跨域开不开全部可以用htmx.config一行调回来。最容易翻车的两个点事件名大小写和 DELETE 请求的传参位置变了但后端没跟上。把它们盯住这次大版本升级基本就是换文件加跑测试的功夫。【免费下载链接】htmxhtmx - high power tools for HTML项目地址: https://gitcode.com/GitHub_Trending/ht/htmx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考