完成 htmx 1.x 到 2.x 迁移实战默认值、hx-on: 与扩展拆分的避坑清单【免费下载链接】htmxhtmx - high power tools for HTML项目地址: https://gitcode.com/GitHub_Trending/ht/htmx准备把 htmx 升到 2.x这篇基于当前仓库源码整理的 htmx 1.x 到 2.x 迁移实战把官方迁移清单里的七项破坏性变更逐一落实先判断能不能升再按你的用法改导入、配置与事件语法htmx.swap() 也一并讲透帮你少踩坑。动手前先拍板你的项目还有没有 IE 要兼容结论直接给如果你必须照顾 IE 用户别升留在 htmx 1.x因为 2.0 已彻底移除 IE 支持。反过来只要面向 Chrome、Firefox、Safari、Edge 这类现代浏览器放心升能拿到 hx-on: 新语法、统一的 htmx.swap() 和更稳的安全默认值。官方文档写得很明确2.0 不再支持 IE而仍在维护的 1.x 会继续撑着 IE可预见的未来都有效官方迁移文档。2.0 到底动了哪七块一张表看清动手量先看这张总表把「谁会踩到 / 要改多少 / 能不能改回 1.x」摆清楚你立刻能分清哪些只是换个导入路径、哪些得动配置或代码变了什么谁会踩到动手量能改回 1.x 吗发行文件按模块类型拆分用打包器 / 模块化的低改导入路径是继续用 htmx.js扩展从核心剥离、独立分发用了 SSE / WS 等扩展中升级扩展版本部分SSE 必须 2.xhtmx.config 三项默认值调整依赖平滑滚动 / DELETE 传参 / 跨域低各一行配置是hx-on 换成 hx-on:kebab-case用过 hx-on 事件中改属性名否makeFragment 恒定返回 DocumentFragment写自定义扩展中改返回类型分支否selectAndSwap 移除、由 swap 取代写自定义扩展中改调用否正式停止支持 IE要兼容 IE高无法升级否留 1.x构建脚本里能查到四种文件的生成方式浏览器版 /dist/htmx.js、压缩版、以及 ESM、AMD、CJS 各一份。三项 htmx.config 默认值改了对照表 一行改回2.x 动了三个全局默认全部能用 htmx.config 覆盖回去。对照如下原理紧跟其后配置项1.x 行为2.x 默认改回 1.x 的一行代码scrollBehaviorsmooth 平滑滚动instant 瞬时htmx.config.scrollBehavior smoothmethodsThatUseUrlParams[get][get,delete]htmx.config.methodsThatUseUrlParams [get]selfRequestsOnlyfalse 允许跨域true 仅限同源htmx.config.selfRequestsOnly falsescrollBehavior换成 instant 后htmx 每次 swap 完不再带过渡动画地滚到目标位置它直接决定 scrollIntoView 的 behavior 参数src/htmx.js默认值在配置对象里写成 instantsrc/htmx.js。想要旧手感在初始化里把 scrollBehavior 设回 smooth。methodsThatUseUrlParams决定哪些动词把参数编码进 URL 查询串而不是请求体。2.0 把 delete 也放了进来理由是 DELETE 按 HTTP 规范本该像 GET 一样用 query string 传参src/htmx.js。发送时用 indexOf 判断当前 verb 是否命中这个列表src/htmx.js。后端要是还靠 DELETE 请求体取参就改回[get]。selfRequestsOnly默认 true 后htmx 在真正发请求前会校验目标是否与本机同源不同源直接拦下src/htmx.js这是 2.0 的安全收紧。真有跨域需求时设为 false 放开限制但请求最终通不通仍取决于服务端 CORS 是否配好默认值见 src/htmx.js。按你的用法挑路线script、模块化、还是自定义扩展只在 HTML 里用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考