方法)
htmx 2.x 遷移完整指南7 處破壞性變更與舊行為恢復(fù)方法【免費下載鏈接】htmxhtmx - high power tools for HTML項目地址: https://gitcode.com/GitHub_Trending/ht/htmxhtmx 從 1.x 升到 2.x全部 7 處破壞性變更可以分成三類3 處加幾行配置就能恢復(fù)3 處要動語法或依賴1 處直接決定你能不能升。這篇文章給出變更清單和一套升級后能直接執(zhí)行的檢查順序按它做完你當(dāng)天就能合入 2.x 而不留尾巴。我的項目現(xiàn)在能不能升 htmx 2.x先看兩個硬條件。產(chǎn)品端還有 Internet Explorer 的硬性需求留在 1.x 線2.0 已放棄 IE官方表示 1.x 線會在可預(yù)見的未來繼續(xù)支持 IE。你寫過內(nèi)部擴展、調(diào)用了selectAndSwap內(nèi)部 API先把調(diào)用遷移到新的swap方法再升主包。其余場景——包括大量使用hx-get、hx-post、hx-boost的普通頁面——直接升即可。htmx 對向后兼容給了極高優(yōu)先級官方遷移文檔的說法是絕大多數(shù)項目幾乎不需要改動。升完之后最容易壞的四個場景是內(nèi)容交換不再平滑滾動DELETE 的參數(shù)從請求體跑進了 URL query跨域請求被新的同源默認值攔下用舊hx-on屬性綁的事件處理器靜默失效。后面逐一對應(yīng)解法。零改動這部分你不用動任何手指用script src...htmx.js加載的項目/dist/htmx.js在 2.x 里繼續(xù)面向瀏覽器提供路徑和用法不變只換版本號就行。模塊化工程里發(fā)行文件按模塊體系拆分了構(gòu)建邏輯見 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-*屬性行為基本未變存量頁面升級后照常渲染、照常發(fā)請求——這就是可以放心升的原因核心交換與請求鏈路本身沒有改簽名。只加幾行配置三個新默認值怎么恢復(fù)舊行為三項變更全部通過htmx.config覆蓋配置對象在 src/htmx.js 中定義當(dāng)前默認值一覽見 api.md。內(nèi)容交換為什么不再平滑滾動舊行為swap 后目標(biāo)元素平滑滾入視口。新行為一步到位scrollBehavior默認instant它直接決定scrollIntoView的滾動方式?；謴?fù)一行htmx.config.scrollBehavior smooth也可用auto交還給 CSS 決定。DELETE 的參數(shù)為什么進了 URL舊行為DELETE 的參數(shù)編碼進請求體。新行為參數(shù)走 query stringmethodsThatUseUrlParams默認[get, delete]發(fā)請求時 htmx 按 verb 查這個列表決定編碼方式。依據(jù)是 HTTP 規(guī)范里 DELETE 本應(yīng)像 GET 一樣使用請求參數(shù)這屬于規(guī)范對齊。后端如果還在讀 body恢復(fù)一行htmx.config.methodsThatUseUrlParams [get]?？缬蛘埱鬄槭裁撮_始被攔截舊行為跨域可用。新行為請求發(fā)出前檢查來源非同源直接攔下selfRequestsOnly默認true這是安全加固。確實需要跨域時恢復(fù)一行htmx.config.selfRequestsOnly false——放開的是 htmx 這層限制請求最終能否成功仍取決于服務(wù)端 CORS。必須動代碼四處要親手改hx-on 事件處理器不生效了改用 hx-on: 語法癥狀老寫法hx-on事件名: 腳本的特殊語法在 2.0 已被移除CHANGELOG.md 2.0.0 條目升級后處理器不執(zhí)行且不報任何錯是最容易被漏掉的。舊寫法遷到新寫法!-- 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 環(huán)境還可把冒號換成連字符hx-on 文檔 有對照。另外同一個元素上兩種形式不能混用存在hx-on:*時舊hx-on的值會被靜默忽略。makeFragment 現(xiàn)在永遠返回 DocumentFragment癥狀如果你的代碼按返回類型分支比如fragment instanceof Element的判斷升級后該分支恒為假按 Element 讀屬性拿到 undefined。1.x 中makeFragment可能返回Element或DocumentFragment2.x 起完整頁面、body 片段、部分 HTML 一律組裝成DocumentFragment實現(xiàn)見 src/htmx.js 的makeFragment函數(shù)完整頁面響應(yīng)的title存在fragment.title上?？硬辉陬愋捅旧矶谒且粋€元素的假設(shè)對片段容器做querySelector沒問題直接讀fragment.tagName就斷。把調(diào)用方統(tǒng)一按片段容器處理即可。內(nèi)部 API selectAndSwap 沒了swap 接管癥狀擴展代碼直接拋方法不存在。這一條只影響擴展作者。新的調(diào)用序列是三步let target api.getTarget(child); let swapSpec api.getSwapSpecification(child); api.swap(target, content, swapSpec);swap同時掛在公開 API 上普通應(yīng)用代碼可以用htmx.swap(#output, divhi/div, {swapStyle: innerHTML})直接驅(qū)動交換——注意swapStyle是必填項完整參數(shù)在 api.md 的swap一節(jié)。最容易踩的坑getSwapSpecification是從元素上的hx-swap屬性解析出來的如果你手工構(gòu)造 swapSpecswapDelay、settleDelay、scroll這些字段不會自動帶上動手前先確認目標(biāo)元素真實掛了哪些交換修飾符。擴展不再隨核心分發(fā)SSE 擴展必須升到 2.x癥狀升級后 WebSocket / SSE 連接的頁面不再更新。1.x 的擴展打包在核心發(fā)行包里2.x 全部移出、獨立分發(fā)2.0.0 條目同時移除了舊的hx-ws、hx-sse屬性。兩條要求SSE 擴展必須升到 2.x 版本否則不工作其余擴展建議一并升到 2.x。舊屬性要遷到擴展寫法例如hx-sse換成hx-extsse交換訂閱改用新的sse-swap屬性聲明完整對照表在 extensions/sse.md。?? 這里最容易踩的坑是多數(shù) 1.x 擴展仍能在 2.x 下工作這句話——仍工作不等于不用升SSE 是唯一的強制項。IE 正式退役2.0 不再支持 IE1.x 線繼續(xù)支持且這是單行道升級后沒有配置開關(guān)能找回 IE 路徑。所以這一條要在能不能升那一步就定下來而不是升到一半才發(fā)現(xiàn)。升級后怎么確認沒壞按這個順序查加載打開頁面控制臺無報錯模塊導(dǎo)入指向新的 ESM 文件事件全倉庫 grephx-on命中的都是未遷移的舊形式手動觸發(fā)一次請求確認before-request/after-requestkebab-case仍然觸發(fā)請求回歸 DELETE 接口確認參數(shù)位置與后端預(yù)期一致不一致就恢復(fù)methodsThatUseUrlParams跨域觀察請求是否被攔被攔就恢復(fù)selfRequestsOnly false擴展確認 SSE 擴展已是 2.xgrep 全庫hx-ws、hx-sse無殘留舊 APIgrepselectAndSwap以及makeFragment附近的instanceof Element判斷。哪些操作可以隨時回退配置層是最可回退的三條覆蓋都是運行時語句刪掉即回到新默認整個發(fā)行文件換回 1.x 就是完整基線。事件語法遷移是最不可回退的部分——2.x 已移除舊hx-on形式建議把語法轉(zhuǎn)換單獨放一個提交出問題 revert 這一個提交即可。版本線本身就是天然退路1.x 仍在維護且支持 IE先釘在 1.x、下個迭代再遷永遠是成立的選項。【免費下載鏈接】htmxhtmx - high power tools for HTML項目地址: https://gitcode.com/GitHub_Trending/ht/htmx創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 htmx 2.x 遷移完整指南：7 處破壞性變更與舊行為恢復(fù)方法
htmx 2.x 遷移完整指南7 處破壞性變更與舊行為恢復(fù)方法【免費下載鏈接】htmxhtmx - high power tools for HTML項目地址: https://gitcode.com/GitHub_Trending/ht/htmxhtmx 從 1.x 升到 2.x全部 7 處破壞性變更可以分成三類3 處加幾行配置就能恢復(fù)3 處要動語法或依賴1 處直接決定你能不能升。這篇文章給出變更清單和一套升級后能直接執(zhí)行的檢查順序按它做完你當(dāng)天就能合入 2.x 而不留尾巴。我的項目現(xiàn)在能不能升 htmx 2.x先看兩個硬條件。產(chǎn)品端還有 Internet Explorer 的硬性需求留在 1.x 線2.0 已放棄 IE官方表示 1.x 線會在可預(yù)見的未來繼續(xù)支持 IE。你寫過內(nèi)部擴展、調(diào)用了selectAndSwap內(nèi)部 API先把調(diào)用遷移到新的swap方法再升主包。其余場景——包括大量使用hx-get、hx-post、hx-boost的普通頁面——直接升即可。htmx 對向后兼容給了極高優(yōu)先級官方遷移文檔的說法是絕大多數(shù)項目幾乎不需要改動。升完之后最容易壞的四個場景是內(nèi)容交換不再平滑滾動DELETE 的參數(shù)從請求體跑進了 URL query跨域請求被新的同源默認值攔下用舊hx-on屬性綁的事件處理器靜默失效。后面逐一對應(yīng)解法。零改動這部分你不用動任何手指用script src...htmx.js加載的項目/dist/htmx.js在 2.x 里繼續(xù)面向瀏覽器提供路徑和用法不變只換版本號就行。模塊化工程里發(fā)行文件按模塊體系拆分了構(gòu)建邏輯見 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-*屬性行為基本未變存量頁面升級后照常渲染、照常發(fā)請求——這就是可以放心升的原因核心交換與請求鏈路本身沒有改簽名。只加幾行配置三個新默認值怎么恢復(fù)舊行為三項變更全部通過htmx.config覆蓋配置對象在 src/htmx.js 中定義當(dāng)前默認值一覽見 api.md。內(nèi)容交換為什么不再平滑滾動舊行為swap 后目標(biāo)元素平滑滾入視口。新行為一步到位scrollBehavior默認instant它直接決定scrollIntoView的滾動方式?；謴?fù)一行htmx.config.scrollBehavior smooth也可用auto交還給 CSS 決定。DELETE 的參數(shù)為什么進了 URL舊行為DELETE 的參數(shù)編碼進請求體。新行為參數(shù)走 query stringmethodsThatUseUrlParams默認[get, delete]發(fā)請求時 htmx 按 verb 查這個列表決定編碼方式。依據(jù)是 HTTP 規(guī)范里 DELETE 本應(yīng)像 GET 一樣使用請求參數(shù)這屬于規(guī)范對齊。后端如果還在讀 body恢復(fù)一行htmx.config.methodsThatUseUrlParams [get]?？缬蛘埱鬄槭裁撮_始被攔截舊行為跨域可用。新行為請求發(fā)出前檢查來源非同源直接攔下selfRequestsOnly默認true這是安全加固。確實需要跨域時恢復(fù)一行htmx.config.selfRequestsOnly false——放開的是 htmx 這層限制請求最終能否成功仍取決于服務(wù)端 CORS。必須動代碼四處要親手改hx-on 事件處理器不生效了改用 hx-on: 語法癥狀老寫法hx-on事件名: 腳本的特殊語法在 2.0 已被移除CHANGELOG.md 2.0.0 條目升級后處理器不執(zhí)行且不報任何錯是最容易被漏掉的。舊寫法遷到新寫法!-- 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 環(huán)境還可把冒號換成連字符hx-on 文檔 有對照。另外同一個元素上兩種形式不能混用存在hx-on:*時舊hx-on的值會被靜默忽略。makeFragment 現(xiàn)在永遠返回 DocumentFragment癥狀如果你的代碼按返回類型分支比如fragment instanceof Element的判斷升級后該分支恒為假按 Element 讀屬性拿到 undefined。1.x 中makeFragment可能返回Element或DocumentFragment2.x 起完整頁面、body 片段、部分 HTML 一律組裝成DocumentFragment實現(xiàn)見 src/htmx.js 的makeFragment函數(shù)完整頁面響應(yīng)的title存在fragment.title上?？硬辉陬愋捅旧矶谒且粋€元素的假設(shè)對片段容器做querySelector沒問題直接讀fragment.tagName就斷。把調(diào)用方統(tǒng)一按片段容器處理即可。內(nèi)部 API selectAndSwap 沒了swap 接管癥狀擴展代碼直接拋方法不存在。這一條只影響擴展作者。新的調(diào)用序列是三步let target api.getTarget(child); let swapSpec api.getSwapSpecification(child); api.swap(target, content, swapSpec);swap同時掛在公開 API 上普通應(yīng)用代碼可以用htmx.swap(#output, divhi/div, {swapStyle: innerHTML})直接驅(qū)動交換——注意swapStyle是必填項完整參數(shù)在 api.md 的swap一節(jié)。最容易踩的坑getSwapSpecification是從元素上的hx-swap屬性解析出來的如果你手工構(gòu)造 swapSpecswapDelay、settleDelay、scroll這些字段不會自動帶上動手前先確認目標(biāo)元素真實掛了哪些交換修飾符。擴展不再隨核心分發(fā)SSE 擴展必須升到 2.x癥狀升級后 WebSocket / SSE 連接的頁面不再更新。1.x 的擴展打包在核心發(fā)行包里2.x 全部移出、獨立分發(fā)2.0.0 條目同時移除了舊的hx-ws、hx-sse屬性。兩條要求SSE 擴展必須升到 2.x 版本否則不工作其余擴展建議一并升到 2.x。舊屬性要遷到擴展寫法例如hx-sse換成hx-extsse交換訂閱改用新的sse-swap屬性聲明完整對照表在 extensions/sse.md。?? 這里最容易踩的坑是多數(shù) 1.x 擴展仍能在 2.x 下工作這句話——仍工作不等于不用升SSE 是唯一的強制項。IE 正式退役2.0 不再支持 IE1.x 線繼續(xù)支持且這是單行道升級后沒有配置開關(guān)能找回 IE 路徑。所以這一條要在能不能升那一步就定下來而不是升到一半才發(fā)現(xiàn)。升級后怎么確認沒壞按這個順序查加載打開頁面控制臺無報錯模塊導(dǎo)入指向新的 ESM 文件事件全倉庫 grephx-on命中的都是未遷移的舊形式手動觸發(fā)一次請求確認before-request/after-requestkebab-case仍然觸發(fā)請求回歸 DELETE 接口確認參數(shù)位置與后端預(yù)期一致不一致就恢復(fù)methodsThatUseUrlParams跨域觀察請求是否被攔被攔就恢復(fù)selfRequestsOnly false擴展確認 SSE 擴展已是 2.xgrep 全庫hx-ws、hx-sse無殘留舊 APIgrepselectAndSwap以及makeFragment附近的instanceof Element判斷。哪些操作可以隨時回退配置層是最可回退的三條覆蓋都是運行時語句刪掉即回到新默認整個發(fā)行文件換回 1.x 就是完整基線。事件語法遷移是最不可回退的部分——2.x 已移除舊hx-on形式建議把語法轉(zhuǎn)換單獨放一個提交出問題 revert 這一個提交即可。版本線本身就是天然退路1.x 仍在維護且支持 IE先釘在 1.x、下個迭代再遷永遠是成立的選項。【免費下載鏈接】htmxhtmx - high power tools for HTML項目地址: https://gitcode.com/GitHub_Trending/ht/htmx創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考