用途:为 Vue 提供无头(headless)列表与网格虚拟化,只渲染可视区域内的元素,适合超长列表、聊天记录、日志流等场景。
主要能力:useVirtualizer 用于自定义滚动容器,useWindowVirtualizer 随浏览器窗口滚动(预填 getScrollElement 与 initialOffset,SSR 安全)。适配器返回 Ref<Virtualizer>,脚本中用 .value,模板自动解包。选项支持 MaybeRef,传入 ref 或 computed 可响应式更新 count、overscan、enabled 等;getScrollElement 以 immediate: true 监听,模板 ref 挂载后会被捕获。onChange 被包装,内部先 triggerRef,使 computed 能随滚动与尺寸变化重新求值;观察器通过 onScopeDispose 清理。measureElement 测量的元素需带索引属性,默认 data-index。不要传 observeElementRect、observeElementOffset、scrollToFn,适配器已预填。
安装:npm install @tanstack/vue-virtual。版本:目标 3.13.39,依赖 @tanstack/virtual-core@3.17.11,peer 为 vue ^2.7.0 || ^3.0.0。
必要用法:滚动容器需有确定高度与 overflow: auto;内层 sizer 使用 getTotalSize();动态高度行推荐块级 translateY 定位(以首个可见项 start 平移),而非逐项绝对定位。窗口虚拟化时若列表位于其他内容下方,需把偏移量测入 scrollMargin。
适用场景:长列表、网格、聊天/日志的末端锚定(anchorTo: 'end'、followOnAppend、scrollToEnd() 等,core 3.16.0 起)、滚动恢复(takeSnapshot(),3.15.0 起)、隐藏列表保留测量(useCachedMeasurements,3.17.0 起)。
限制与注意:动态项 estimateSize 宜取接近最大尺寸;数据重排、过滤、前插或流式更新时应提供稳定 getItemKey;间距用 gap 选项而非 CSS margin;count 变化会使测量缓存失效;暂停观察用 enabled: false 而非卸载;v2 的 useVirtual 已移除,v3 改用 useVirtualizer、count、getScrollElement 与带 data-index 的 measureElement。其余细节暂未提供。