htmx 1.x 升级到 2.x 实战：默认值、hx-on 语法与扩展拆分的完整改造清单

htmx 1.x 升级到 2.x 实战默认值、hx-on 语法与扩展拆分的完整改造清单【免费下载链接】htmxhtmx - high power tools for HTML项目地址: https://gitcode.com/GitHub_Trending/ht/htmxhtmx 是一套主打高功率 HTML的无构建前端工具让你直接在标签上写hx-*属性就能发起请求并替换页面片段。从 htmx 1.x 升到 2.x 时真正要动手的只有少数几处几个默认配置的调整、hx-on事件语法的换血、扩展从核心包里被拆出去以及两个内部 API 的替换。下面按升级前判断 → 逐项改造 → 验证回退的工作流来走每一项都给出恢复 1.x 行为的具体写法方便你逐步推进、随时回退。升级前先判断模块文件和加载方式要不要动2.x 把发行产物按 JavaScript 模块体系做了拆分不同构建场景要挑对应的文件。构建脚本 scripts/dist.sh 里能直接看到它产出htmx.amd.js、htmx.cjs.js、htmx.esm.js这几份模块专属产物而htmx.js则继续留给浏览器直接加载。你的项目形态选这个文件浏览器script直接引/dist/htmx.js无需改动打包用 ESMimport/export/dist/htmx.esm.jsRequireJS 等 AMD 加载器/dist/htmx.amd.jsNode / CommonJS/dist/htmx.cjs.js所以如果线上一直是用script src/dist/htmx.js挂着的升级后这条引用原封不动就能跑。只有在模块化打包场景里才需要按上表核对一下导入路径。把扩展从核心包里搬出去1.x 时代跟着核心一起发布的扩展在 2.x 里已经全部独立分发核心包不再捆绑它们。大部分 1.x 扩展在 2.x 下能继续工作但有两点要留意SSE 扩展是强制项必须升到 2.x 版本否则跑不起来官方建议把用到的扩展整体升到 2.x好与新版核心的事件模型对齐。另外如果你页面上还在用旧的hx-ws、hx-sse写法要换成对应扩展提供的属性形式。扩展的引入与构建细节参考 www/content/extensions/_index.md 和 www/content/extensions/building.md。三个默认值2.x 悄悄改了什么2.x 调整了三个全局配置的默认值全部能通过htmx.config覆盖。当前取值在 src/htmx.js 的默认配置对象里能直接对上。配置项2.x 默认1.x 行为想恢复 1.x 的写法scrollBehaviorinstant平滑滚动htmx.config.scrollBehavior smoothmethodsThatUseUrlParams[get, delete][get]htmx.config.methodsThatUseUrlParams [get]selfRequestsOnlytruefalsehtmx.config.selfRequestsOnly false3.1 滚动默认从平滑改成瞬时scrollBehavior在 src/htmx.js 里默认写成instant可选auto | instant | smooth。它直接决定了每次内容交换后的滚动手感swap 完成后 htmx 会调用target.scrollIntoView({ block, behavior: htmx.config.scrollBehavior })见 src/htmx.js也就是说不再默认带平滑过渡动画。如果产品上依赖那种缓缓滚过去的体验在初始化里加一行即可htmx.config.scrollBehavior smooth;3.2 DELETE 的参数默认走 URL 查询串methodsThatUseUrlParams决定哪些 HTTP 方法的参数被编码进 URL 查询串、而不是塞进请求体。2.x 把它默认设成[get, delete]src/htmx.js。请求发送前会走到htmx.config.methodsThatUseUrlParams.indexOf(verb) 0这个判断src/htmx.js来分流。这里看似反常其实是更贴 HTTP 规范的修正规范认为DELETE和GET一样应该用请求参数而非请求体。如果你的后端一直靠 DELETE 请求体拿参数那就显式回退htmx.config.methodsThatUseUrlParams [get];3.3 跨域请求默认被关闸selfRequestsOnly默认truesrc/htmx.js意味着只放行同源请求。它在请求真正发出前就被检查src/htmx.js属于一次安全加固。确有跨域需求时再放开htmx.config.selfRequestsOnly false;提示关掉selfRequestsOnly只是解除了 htmx 这一侧的拦截跨域请求最终能否成功仍然取决于服务端有没有正确配置 CORS。事件写法换血从 hx-on 到 hx-on:1.x 用一个hx-on属性把事件名 冒号 处理代码叠在一起2.x 改成一个事件一个独立属性的hx-on:形式。官方给出的标准对照是这样的——1.xbutton hx-get/info hx-onhtmx:beforeRequest: alert(Making a request!) htmx:afterRequest: alert(Done making a request!) Get Info! /button2.x 等价button hx-get/info hx-on:htmx:before-requestalert(Making a request!) hx-on:htmx:after-requestalert(Done making a request!) Get Info! /button这里有个容易踩的坑事件名必须写成 kebab-case。比如htmx:beforeRequest要写成htmx:before-request。根因是 HTML 属性名不区分大小写浏览器会把属性名整体小写化一旦写了驼峰里面的大写就废掉了只有短横线写法能稳定匹配到。htmx 本身同时认驼峰和短横线事件名但在属性位置只能靠 kebab-case这一点在 www/content/attributes/hx-on.md 里有说明。源码侧2.x 的属性发现逻辑在 src/htmx.js 里同时兼容hx-on:/data-hx-on:以及旧式hx-on-/data-hx-on-前缀。还有一条简写能省事hx-on::before-request等价于hx-on:htmx:before-request省掉了重复写htmx:命名空间适合挂请求周期事件。提示同一元素上hx-on:*和旧的hx-on不能并存只要存在hx-on:*旧hx-on的值就会被忽略迁移时要清理掉旧写法。两个 API 层面的断舍离makeFragment 永远返回 DocumentFragment1.x 里htmx.makeFragment()视响应内容不同可能返回Element或DocumentFragment2.x 起统一只返回DocumentFragment。看 src/htmx.js 的实现就清楚了响应以html开头时解析整份文档、取出body子节点组装成片段并把title存进fragment.title以body开头则类似处理 body其他部分 HTML 会用内部template classinternal-htmx-wrapper包一层再解析以最大化解析灵活性同时兼容根级title的旧行为。函数还会把hx-*自定义标签临时转成template hx type*以便在 HTML 解析中存活并对script做规范化。如果你之前在代码里对makeFragment的返回值做了Element/DocumentFragment的分支判断升级后统一按DocumentFragment处理即可。selectAndSwap 没了交给 swap这是给扩展作者的重点1.x 内部 API 里的selectAndSwap被移除改由swap顶替而且它同时开放在内部 API 和公开 API 上普通开发者也能直接用htmx.swap()驱动交换。官方迁移序列www/content/migration-guide-htmx-1.mdlet content divHello world/div; // 要交换进目标的 HTML let target api.getTarget(child); // 解析交换目标元素 let swapSpec api.getSwapSpecification(child); // 读取 hx-swap 规格 api.swap(target, content, swapSpec);底层swap(target, content, swapSpec, swapOptions)在 src/htmx.js 里依次做解析出真正目标、在文档根节点上下文里处理 OOB 交换与hx-select-oob、处理hx-select与hx-preserve、执行主交换并触发htmx:beforeSwap/htmx:afterSwap、维护焦点与选区document.activeElement及其selectionStart/End最后走 settle 流程。而把hx-swap解析成结构化的getSwapSpecificationsrc/htmx.js会拆出swapStyle、swapDelay/settleDelay、transition、ignoreTitle、scroll/show及各自目标选择器、focus-scroll等。公开 API 形态见 www/content/api.md核心参数target元素或选择器、content要交换的 HTML 字符串、swapSpecswapStyle必填如innerHTML可选swapDelay、settleDelay、transition、ignoreTitle、head、scroll系列以及可选的swapOptionsselect、selectOOB、eventInfo、anchor、contextElement、afterSwapCallback/afterSettleCallback等。极简用法htmx.swap(#output, divSwapped!/div, {swapStyle: innerHTML});提示扩展内若需要为指定元素查找可用扩展可把相关元素放进swapOptions.contextElement源码注释表明它目前就承担这个用途。浏览器支持IE 正式告别htmx 2.0 不再支持 IE。仍在维护的 1.x 系列会继续照顾 IE并会维持可预见的未来。有 IE 硬兼容需求的项目请继续锁在 1.x 版本线已面向现代浏览器Chrome / Firefox / Safari / Edge的可以放心升 2.x享受新语法、统一 API 与更稳的安全默认值。升级后的验证与回退升完之后建议按这条线过一遍全部能过再合进主线加载无报错确认script或模块导入指向 2.x 产物控制台干净。事件回归逐一核对hx-on是否都改成了hx-on:且事件名是 kebab-case重点回归htmx:before-request/htmx:after-request这类请求周期事件。DELETE 接口回归测试参数走 URL 查询串后后端能否正确解析不行就回退methodsThatUseUrlParams [get]。跨域场景升级后被拦截的跨域请求检查是否需要selfRequestsOnly false。扩展确认 SSE 等扩展升到 2.x并清掉hx-ws/hx-sse旧属性。自定义扩展全局搜selectAndSwap残留全部换成swap并按 www/content/api.md 的签名调整参数。得益于默认值可用htmx.config覆盖 旧hx-on兼容层 可继续引用旧发行文件整个过程能做得很平滑改动集中在独立分支上验证发现不对劲随时能回退。逐项对照 CHANGELOG.md 里的版本记录再结合 src/htmx.js 的实现与 www/content/api.md 的公开 API 文档就能把这次大版本升级做得既干净又稳。【免费下载链接】htmxhtmx - high power tools for HTML项目地址: https://gitcode.com/GitHub_Trending/ht/htmx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考