前端UI組件【免費下載鏈接】virtual Headless UI for Virtualizing Large Element Lists in JS/TS, React, Solid, Vue and Svelte項目地址https://gitcode.com/gh_mirrors/vi/virtual點擊查看免費下載tanstack/vue-virtual是 TanStack Virtual 在 Vue 框架上的官方適配層負(fù)責(zé)把無框架的tanstack/virtual-core核心虛擬化邏輯封裝為響應(yīng)式的 Vue 組合式 API。本文以倉庫中的 CHANGELOG 為主線梳理該適配器從 3.13.3 到 3.13.39 的版本演進(jìn)脈絡(luò)結(jié)合 源碼實現(xiàn)、虛擬化核心 API 文檔 與 Vue 示例 中的真實代碼講清楚每個關(guān)鍵修復(fù)背后的原理以及 Vue 適配器究竟如何把核心虛擬化能力橋接到 Vue 的響應(yīng)式體系。讀完你會掌握如何閱讀這個包的版本記錄并追蹤底層 core 的變更、useVirtualizer/useWindowVirtualizer兩個入口的響應(yīng)式工作原理以及動態(tài)測量、錨定模式等新能力的實戰(zhàn)用法。版本總覽Vue 適配器版本節(jié)奏與 core 的耦合關(guān)系tanstack/vue-virtual走的是「薄適配層 共享核心」的包結(jié)構(gòu)。從 CHANGELOG 可以看到一個非常清晰的事實幾乎所有版本號3.13.4 ~ 3.13.39都只有一個 Patch Changes 條目即「Updated dependencies」指向tanstack/virtual-core的某個新版本。這并非版本記錄偷懶而是工程設(shè)計的必然結(jié)果。查看包的依賴聲明package.json 中唯一的運(yùn)行時依賴就是tanstack/virtual-core以 workspace 協(xié)議引入整個src/index.ts不過百來行。也就是說3.13.4 ~ 3.13.12、3.13.14 ~ 3.13.21、3.13.23 ~ 3.13.26 等版本純屬 core 升級適配器自身零改動3.13.13 是唯一一個自帶 Fix 條目的版本修復(fù)了count變化時getTotalSize()返回過期值的問題3.13.22、3.13.27、3.13.28、3.13.39 等版本對應(yīng) core 的 minor如 3.14.0、3.15.0、3.16.0、3.17.0/3.17.11或 patch 升級其中 core 的 3.16.0 與 3.17.0 引入了影響面較大的新能力。在倉庫中可以通過兩條 CHANGELOG 對照閱讀Vue 側(cè)記錄「適配器自身改了什么 依賴的 core 升到哪」virtual-core 的 CHANGELOG 記錄「core 具體修了什么」。這種分層讓框架適配器與核心邏輯可以各自獨立迭代、共享同一份性能與正確性改進(jìn)這也是本倉庫所有框架包React、Solid、Svelte、Lit、Marko、Angular 等共用的架構(gòu)。版本對照速查表下表整理了本倉庫所記錄的兩個包在對應(yīng)版本號上的耦合關(guān)系Vue 適配器 3.13.39 對應(yīng) virtual-core 3.17.11為當(dāng)前最新版本tanstack/vue-virtualtanstack/virtual-core主要變更3.13.33.13.3基礎(chǔ)版本3.13.133.13.13修復(fù) count 變化時 getTotalSize() 過期適配器層唯一 Fix3.13.243.14.0core minor 升級3.13.253.15.0core minor 升級多列 masonry 相關(guān)能力3.13.273.16.0/3.16.1core minoranchorTo: end 聊天/日志模式等3.13.283.17.0core minoruseCachedMeasurements 選項3.13.393.17.11最新版本core 修復(fù)平滑滾動、錨定補(bǔ)償?shù)任ㄒ蛔詭迯?fù)的版本3.13.13 與 count 變化時的高度更新在 CHANGELOG 的 3.13.13 條目中記錄了一個值得展開的修復(fù)對應(yīng) upstream PR #1085Fix: Notify framework when count changes to updategetTotalSize()問題現(xiàn)象當(dāng)count選項發(fā)生變化時例如前端做過濾或搜索列表從 100 條變成 20 條getTotalSize()會返回過期值。修復(fù)前過濾后列表容器仍保持之前的高度——count減少時出現(xiàn)大片空白count增加時新內(nèi)容不可達(dá)。修復(fù)方式virtualizer 在「會影響測量結(jié)果的選項」變化時自動通知框架。也就是說core 現(xiàn)在會追蹤哪些選項影響測量緩存一旦count這類選項變更就觸發(fā)框架側(cè)重新渲染讓高度隨count同步更新用戶不再需要手寫useMemo之類的補(bǔ)償邏輯。條目還強(qiáng)調(diào)該修復(fù)對所有框架適配器生效且每次變化的性能開銷極小 0.1ms。對照 Vue 適配器的實現(xiàn)可以理解「通知框架」是如何落地的。在 packages/vue-virtual/src/index.ts 中適配器用watch監(jiān)聽選項對象一旦變化就調(diào)用virtualizer.setOptions(...)并在onChange回調(diào)里執(zhí)行triggerRef(state)watch( () unref(options), (options) { virtualizer.setOptions({ ...options, onChange: (instance, sync) { triggerRef(state) options.onChange?.(instance, sync) }, }) virtualizer._willUpdate() triggerRef(state) }, { immediate: true }, )state是一個shallowRef(virtualizer)triggerRef強(qiáng)制觸發(fā)該 ref 的更新從而讓依賴它的getTotalSize()/getVirtualItems()計算屬性重新求值。這就是「core 通知框架」在 Vue 側(cè)的完整鏈路core 內(nèi)部檢測到測量相關(guān)選項變化 → 調(diào)用onChange→ 適配器triggerRef→ 模板中的computed重新計算。適配器的響應(yīng)式工作原理useVirtualizer 與 useWindowVirtualizer兩個組合式 API 的入口Vue 框架文檔 明確說明tanstack/vue-virtual是圍繞核心虛擬邏輯的薄封裝對外只暴露兩個函數(shù)function useVirtualizerTScrollElement, TItemElement unknown( options: PartialKeys VirtualizerOptionsTScrollElement, TItemElement, observeElementRect | observeElementOffset | scrollToFn , ): VirtualizerTScrollElement, TItemElement function useWindowVirtualizerTItemElement unknown( options: PartialKeys VirtualizerOptionsWindow, TItemElement, | getScrollElement | observeElementRect | observeElementOffset | scrollToFn , ): VirtualizerWindow, TItemElement兩者的區(qū)別只在于滾動載體useVirtualizer返回配置為以HTML 元素作為滾動元素的Virtualizer實例useWindowVirtualizer返回以window作為滾動元素的實例用于整頁滾動場景。源碼級實現(xiàn)解析從 packages/vue-virtual/src/index.ts 可以完整還原適配器實現(xiàn)。兩個入口都匯聚到私有的useVirtualizerBase創(chuàng)建實例const virtualizer new Virtualizer(unref(options))用shallowRef包裹為state掛載清理調(diào)用virtualizer._didMount()得到cleanup注冊到onScopeDispose(cleanup)組件銷毀時自動解除 ResizeObserver、滾動監(jiān)聽等副作用滾動元素監(jiān)聽watch(() unref(options).getScrollElement(), ...)滾動元素一旦就緒比如 ref 綁定完成就調(diào)用_willUpdate()選項響應(yīng)式同步上面的watch用setOptions把新選項含包裝后的onChange同步給 core并觸發(fā)_willUpdate()與triggerRef(state)返回state即RefVirtualizer模板中通過.value訪問實例方法。useVirtualizer額外通過computed注入三個默認(rèn)實現(xiàn)useVirtualizerBase( computed(() ({ observeElementRect: observeElementRect, observeElementOffset: observeElementOffset, scrollToFn: elementScroll, ...unref(options), })), )即元素模式下默認(rèn)使用observeElementRect/observeElementOffset基于 ResizeObserver 與 scroll 事件和elementScroll。useWindowVirtualizer則注入getScrollElement: () window、observeWindowRect、observeWindowOffset、windowScroll以及initialOffset: () window.scrollY見 源碼這些默認(rèn)實現(xiàn)與 virtualizer API 文檔 中描述的elementScroll/windowScroll/observeElementRect/observeWindowRect一一對應(yīng)。需要注意盡管文檔簽名寫作返回Virtualizer實際實現(xiàn)返回的是RefVirtualizerstateVue 模板與計算屬性中要用.value訪問——這正是 示例代碼 中rowVirtualizer.value.getVirtualItems()的寫法來源。版本演進(jìn)中的核心能力從 core 升級看功能增量雖然 Vue 適配器自身改動極少但跟隨 core 的版本升級Vue 用戶也同步獲得了大量底層能力。以下是本倉庫 virtual-core CHANGELOG 中記錄的、隨 Vue 適配器各版本一起落地的關(guān)鍵能力core 3.16.0anchorTo: end 聊天/日志模式core 3.16.0對應(yīng) Vue 3.13.26 → 3.13.27引入了端錨定虛擬化專為聊天、日志、反向信息流設(shè)計新增anchorTo: end選項當(dāng)舊內(nèi)容被前插prepend時保持當(dāng)前可見項穩(wěn)定流式輸出中最后一項增長時保持視口釘在底部默認(rèn)仍是start頂部/左側(cè)錨定保持原有行為新增followOnAppend只有視口原本就在末尾時新追加內(nèi)容才自動滾入視野往上翻看歷史的用戶不會被拉回底部新增輔助 APIscrollEndThreshold、scrollToEnd()、getDistanceFromEnd()、isAtEnd()。這些 API 的語義在 virtualizer 文檔 中有完整定義scrollEndThreshold默認(rèn)1像素閾值isAtEnd(threshold?)判斷視口是否在距末端閾值范圍內(nèi)scrollToEnd()對縱向列表滾動到底部。配套文檔還強(qiáng)調(diào)前插穩(wěn)定性要求基于持久 id 的穩(wěn)定getItemKey因為索引鍵無法區(qū)分前插與追加。3.16.1 又修復(fù)了一個前插時的「一幀跳躍」問題anchorTo: end下前插內(nèi)容時會有一幀按舊估算位置計算可見范圍隨后_willUpdate修正產(chǎn)生可見跳動修復(fù)后在渲染過程中于setOptions內(nèi)提前調(diào)整scrollOffset使calculateRange/getVirtualItems立即返回正確條目。core 3.17.0useCachedMeasurements 與測量緩存core 3.17.0對應(yīng) Vue 3.13.28新增useCachedMeasurements選項見 virtualizer 文檔啟用后默認(rèn)measureElement跳過 DOM 讀取直接返回緩存尺寸無緩存則回退到estimateSize典型場景列表被臨時隱藏如父元素display: none時ResizeObserver 會對所有項報告尺寸 0導(dǎo)致測量被重置啟用該選項后隱藏期間測量不被清零恢復(fù)顯示后也不會出現(xiàn)布局跳動使用方式是在隱藏前把該選項置true、顯示后置falseResizeObserver 始終保持掛載關(guān)閉后真實測量自動恢復(fù)注意它只影響默認(rèn)measureElement自定義測量時需自行處理。3.17.0 還順帶優(yōu)化了默認(rèn)measureElement已有緩存時跳過同步 DOM 讀offsetWidth/offsetHeight減少重渲染時的 layout reflow。滾動與測量正確性修復(fù)3.17.x 系列從 3.17.1 到 3.17.11 的密集 patch 主要打磨滾動補(bǔ)償與測量時序這些修復(fù)全部隨 Vue 適配器 3.13.29 自動獲得向上滾動不跳動3.17.1默認(rèn)滾動補(bǔ)償謂詞在向上滾動時也補(bǔ)償「估算→實測」首測差值但跳過重測補(bǔ)償避免級聯(lián)抖動滾動方向不誤鎖3.17.3、3.17.5虛擬器自身補(bǔ)償寫入觸發(fā)的滾動事件不再被當(dāng)作backward方向鎖定避免多幀回流期間視口漂移減少 GC 壓力3.17.3默認(rèn)單車道路徑按滾動幀零分配去掉每次滾動事件上的選項對象與閉包分配gap 選項變化失效測量3.17.4gap 變更會失效測量緩存多車道m(xù)asonry布局改用增量車道 argmin替代反向掃描滾動事件去重與端錨定同步3.17.2跳過相同 offset 的冗余滾動事件applyScrollAdjustment中同步scrollOffset避免端錨定流式增長時被瀏覽器 clamp 丟失iOS 處理3.17.5、3.17.6、3.17.7清理時重置 iOS 手勢/延遲狀態(tài)視口整體跨越折疊線的條目增長不再默認(rèn)補(bǔ)償避免聊天流式消息被逐 token 拖拽iOS 延遲補(bǔ)償不再重放過期增量平滑滾動存活3.17.11前插內(nèi)容時保持行進(jìn)中的平滑scrollToIndex存活anchorTo: end下不再被同步寫scrollTop打斷debounced 滾動結(jié)束回退讀取當(dāng)前 offset避免被過期狀態(tài)覆蓋。這些條目同樣值得開發(fā)者關(guān)注如果你的 Vue 列表在聊天、日志、流式輸出、iOS 觸屏滾動等場景遇到跳動、漂移或釘?shù)资栴}對應(yīng)的修復(fù)版本就是排查與升級依據(jù)。Vue 中的實際用法從倉庫示例看標(biāo)準(zhǔn)接線固定/動態(tài)尺寸的經(jīng)典寫法examples/vue/fixed 展示了基于固定尺寸的「行、列、網(wǎng)格」三種形態(tài)examples/vue/variable 展示了動態(tài)尺寸寫法。核心接線方式以動態(tài)為例script setup langts import { ref, computed } from vue import { useVirtualizer } from tanstack/vue-virtual const parentRef refHTMLElement | null(null) const rowVirtualizer useVirtualizer({ count: props.rows.length, getScrollElement: () parentRef.value, estimateSize: (i) props.rows[i], overscan: 5, }) const virtualRows computed(() rowVirtualizer.value.getVirtualItems()) const totalSize computed(() rowVirtualizer.value.getTotalSize()) /script template div refparentRef classList styleheight: 200px; overflow: auto div :style{ height: ${totalSize}px, position: relative } div v-forvirtualRow in virtualRows :keyvirtualRow.index :style{ position: absolute, top: 0, left: 0, width: 100%, height: ${virtualRow.size}px, transform: translateY(${virtualRow.start}px), } Row {{ virtualRow.index }} /div /div /div /template要點拆解getScrollElement: () parentRef.value返回滾動容器配合適配器內(nèi)部的watch實現(xiàn)滾動元素的響應(yīng)式綁定外層容器高度設(shè)為totalSize撐起整個滾動區(qū)域每個虛擬項position: absolute; top: 0加transform: translateY(start px)絕對定位到對應(yīng)位置需要動態(tài)測量時variable 場景給元素加:refrowVirtualizer.value.measureElement與data-index虛擬器會用 ResizeObserver 實測尺寸并逐步逼近真實高度。無限滾動與 Vue Query 組合examples/vue/infinite-scroll/src/App.vue 展示了無限滾動的完整模式useInfiniteQuery分頁拉數(shù)據(jù) →allRows合并所有頁 →useVirtualizer接收computed選項count: hasNextPage ? allRows.length 1 : allRows.length→ 用一個額外的 loader 行占位。關(guān)鍵觸發(fā)邏輯用watchEffect實現(xiàn)當(dāng)可見項中最后一項接近數(shù)據(jù)末尾且hasNextPage為真時調(diào)用fetchNextPage()watchEffect(() { const [lastItem] [...virtualRows.value].reverse() if (!lastItem) return if ( lastItem.index allRows.value.length - 1 hasNextPage.value !isFetchingNextPage.value ) { fetchNextPage() } })這個示例還體現(xiàn)了兩個適配器特性選項用computed傳入useVirtualizer(rowVirtualizerOptions)當(dāng)分頁數(shù)據(jù)增長時count變化適配器會通過watchsetOptions把新選項同步給 core——這正是 3.13.13 修復(fù)所保證的「count 變化后高度自動更新」在真實場景中的應(yīng)用。版本對照與升級建議結(jié)合本倉庫兩條 CHANGELOG 可以給出以下實用的版本追蹤方法看 Vue 包版本號tanstack/vue-virtual的 3.13.x 序列幾乎全部對應(yīng)tanstack/virtual-core的 3.13.x ~ 3.17.x只有 3.13.13 是適配器自身修復(fù)追 core 的 minor想要新能力聊天錨定、緩存測量、多車道優(yōu)化看 core 的 3.14.0、3.15.0、3.16.0、3.17.0 各自引入什么再映射到對應(yīng)的 Vue 版本3.13.24、3.13.25、3.13.27、3.13.28關(guān)注滾動正確性修復(fù)3.17.x 系列密集修復(fù)了 iOS、平滑滾動、錨定補(bǔ)償?shù)冗吔鐔栴}如果你的場景命中這些邊界優(yōu)先升級到較新的 3.13.39包結(jié)構(gòu)與構(gòu)建信息tanstack/vue-virtual以 ESM/CJS 雙格式發(fā)布見 package.json 的exports字段peerDependencies支持 Vue^2.7.0 || ^3.0.0sideEffects: false便于 tree-shaking。升級時建議參照倉庫的 workspace 結(jié)構(gòu)Vue 適配器與 core 在同一倉庫內(nèi)協(xié)同發(fā)版pnpm-lock.yaml與pnpm-workspace.yaml鎖定了版本關(guān)系本地開發(fā)可通過packages/vue-virtual目錄結(jié)合examples/vue下的固定、動態(tài)、無限滾動、padding、scroll-padding、smooth-scroll、sticky、table 等示例進(jìn)行驗證。文檔側(cè)Vue 框架指南 提供組合式 API 的類型簽名Virtualizer API 文檔 提供全部選項與實例方法詳解兩者配合 CHANGELOG 閱讀即可獲得完整的使用與演進(jìn)視圖。贊分享前端UI組件【免費下載鏈接】virtual Headless UI for Virtualizing Large Element Lists in JS/TS, React, Solid, Vue and Svelte項目地址https://gitcode.com/gh_mirrors/vi/virtual點擊查看免費下載相關(guān)推薦TanStack Solid Query Devtools 演進(jìn)與實戰(zhàn)版本變更、核心原理與配置詳解TanStack Solid Query Devtools 演進(jìn)與實戰(zhàn)版本變更、核心原理與配置詳解 tanstack/solid query devtool前端緩存狀態(tài)管理Focalboard 版本演進(jìn)全解析從 v0.6 到 v0.15 的核心功能與實現(xiàn)原理Focalboard 版本演進(jìn)全解析從 v0.6 到 v0.15 的核心功能與實現(xiàn)原理 Focalboard 是一個開源、可自托管的項目管理工具定位為 Tr后端前端企業(yè)應(yīng)用桌面應(yīng)用協(xié)同辦公從 CHANGELOG 讀懂 eggjs/coreEgg 框架核心的版本演進(jìn)與底層機(jī)制從 CHANGELOG 讀懂 eggjs/coreEgg 框架核心的版本演進(jìn)與底層機(jī)制 本文以 packages/core/CHANGELOG.md htt后端Web框架上一篇如何 10 分鐘跑通 FinRobot多智能體股票研究平臺完整上手指南下一篇如何快速構(gòu)建高性能Web應(yīng)用Lwan與Lua集成的終極指南創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考