一、前言：为什么业务必须用「不定高虚拟列表」？按理说，

经常需要渲染上千甚至上万条长列表数据。

使用者痛点：

• 全量渲染一次性生成大量 DOM，导致页面卡顿、滚动掉帧。
• 白屏卡顿、内存使用过高，影响使用者体验。
• 列表项高度不统一，固定高度方案根本无法适配。

虚拟列表是长列表性能调整的合适方案，主要思想非常清晰：只渲染当前可视区域的 DOM 节点。销毁/缓存非可视区域内容，让页面始终维持极少 DOM 数量从根源解决大数据渲染卡顿问题。

目前多数开源方案基于固定高度实现，算法简单但业务兼容性极差。真实业务中，不定高虚拟列表才是覆盖绝大多数场景的通用方案。

二、定高 vs 不定高 虚拟列表主要差异对比

方案类型	优点	缺点	适用场景
定高虚拟列表	算法简单、计算开销小、滚动响应丝滑	高度固定写死，无法适配动态内容；业务兼容性差	每行高度统一的简单结构化列表
不定高虚拟列表	自适应任意动态高度、无需手动传入高度、业务适配性极强	需要动态计算真实高度+缓存管理。算法复杂度略高	聊天记录、富文本列表、商品卡片、动态内容不规则列表等场景

三、不定高虚拟列表主要实现原理

不同于定高列表通过「索引 × 固定高度」快速定位，不定高虚拟列表面临未知高度、动态渲染、精准校正滚动位置的难题。

整套方案依赖以下三大主要能力：

1. 智能高度缓存：记录每条数据的真实渲染高度，避免重复重排计算。不过，
2. 累计高度动态计算：实时累加条目高度。以得到整体容器高度和每项的顶部偏移量。
3. 可视区间截取 & 实时偏移校正：根据滚动位置推算起止索引。并通过 translateY 精准位移，解决抖动和错位。
4. 占位容器模拟滚动区域：Paddling 整体总高度，使滚动条比例与完整列表一致。不过，
5. 自动重置机制：深度监听数据源变化。在刷新/筛选时自动清空缓存并重置状态。说起来，

四、全局通用 Hooks 封装

. Hook 实现代码

import { ref。computed,watch,type Ref } from 'vue'
/** 虚拟列表配置参数 */
export interface VirtualListOptions {
/** 单次渲染可视条数 */
pageSize?: number
/** 条目预估兜底高度 */
estimateHeight?: number
}
/**
* Vue3 不定高虚拟列表 Hooks
* - 自动缓存真实高度
* - 动态计算可视区间
* - 滚动偏移精准校正
* - 支持全量刷新 & 增量分页加载
*/
export default function useVirtualList(
listData: Ref,options: VirtualListOptions = {}
) {
const { pageSize = 20。estimateHeight = 60 } = options
// 滚动容器 DOM 实例
const wrapperRef = ref
// 可视区域起止索引
const startIndex = ref
const endIndex = ref
// 当前滚动偏移量
const scrollOffset = ref
// 高度缓存：key=全局索引，value=真实 DOM 高度
const itemHeightCache = ref
/** 获取单条条目真实高度 */
const getItemHeight = : number => {
return itemHeightCache.value?，estimateHeight
}
/** 累计指定索引之前所有条目的总高度 */
const getItemTop = : number => {
let top = 0
for {
top += getItemHeight
}
return top
}
/** 列表整体总高度，用于撑开外层滚动条 */
const totalHeight = computed => {
let total = 0
listData.value.forEach => {
total += getItemHeight
})
return total
})
/** 当前可视区间渲染的数据 */
const visibleList = computed => {
return listData.value.slice
})
**/** 滚动监听主要原因：实时计算起止索引 & 更新 offset **/
const handleScroll = : void => {
if return
const scrollTop = wrapperRef.value.scrollTop
scrollOffset.value = scrollTop
let heightSum = 0
let startIdx = 0
for {
heightSum += getItemHeight
if {
startIdx = i
break
}
}
startIndex.value = startIdx
endIndex.value   = startIdx + pageSize
}
/** 更新并缓存单条真实 DOM 高度 */
const updateItemHeight = :void=>{
if{
itemHeightCache.value=height
}
}
/** 全量重置 */
const resetVirtualList = :void=>{
startIndex.value    = 0
endIndex.value      = pageSize
scrollOffset.value  = 0
itemHeightCache.value={}
if{
wrapperRef.value.scrollTop=0
}
}
/** 增量加载——仅拼接数据保留历史缓存 */
const appendListData=:void=>{
listData.value=
}
// 深度监听全量变化 → 自动全量重置
watch(listData。=>resetVirtualList,{ deep:true }
)
return{
wrapperRef,visibleList,totalHeight,scrollOffset,startIndex,endIndex,handleScroll,updateItemHeight,resetVirtualList,appendListData // 分页增量专用方法
}
}

五、TS业务组件完整使用示例

六、主要亮点与关键调整细节

. 智能高度缓存策略

- 首次渲染使用预估占位。高度未知导致白屏闪烁 ‑ 渲染完成后立即采集真实 DOM 高度并写入缓存 ‑ 后续滚动直接复用缓存，无需 回流测量，实现“无抖动·无回弹”。

. 完全解耦的逻辑层

- 所有复杂计算与状态管理都封装在 #useVirtualList.ts# ‑ UI 层只负责结构与样式。无需关心任何数学运算 ‑ 同一个 Hook 能在多种业务页面复用，实现“一套代码，多处使用”。

. 数据源监听自动重置

- 深度 watch 列表数组变化 ‑ 搜索 / 筛选 / 刷新时自动清空旧缓存并恢复滚动到顶部 ‑ 防止“旧数据残留导致错位”这类常见 bug。

. 精准位移修正

- 使用 :style="{transform:`translateY`}" ‑ 根据实时累计偏移校正可视区域位置 ‑ 解决问题不定高布局下的空白跳跃问题。

七、通用业务场景适配

. 完美支持分页加载

- 上拉加载下一页时仅调用 #appendListData# ‑ 保留历史 Height 缓存，不会出现回弹或抖动。

. 支持搜索筛选实时刷新

- 数据源被替换后 Hook 自动执行 #resetVirtualList# ‑ 清空旧缓存并重新计算所有 Height。

. 增删改操作一样稳健

- 列表置顶 / 删除 / 编辑，只需更新数组 ‑ Hook 会同步更新对应索引的 Height 与可视区间。

八、分页增量加载

User Pain Point：

• AOP 全量监听导致分页“下拉加载更多”时每次都会清空历史 Height，造成页面抖动与错位。
• 需要在同一个 Hook 中同时兼顾“全量刷新”和“增量加载”两种截然不同的业务需求。

. 主要思路

• 关闭默认深度监听的全量重置，将其交给业务自行决定何时调用。
• a) 刷新/筛选 → 手动调用 #resetVirtualList#
• b) 分页增量 → 调用 #appendListData#。保留旧缓存，不触发重置，不过，
• a+b 两套流程相互独立。实现“增量不丢失·全量安全刷新的双模式”。

. 改造后的 Hook

import { ref。computed,type Ref } from 'vue'
export interface VirtualListOptions{
pageSize?:number
estimateHeight?:number
}
/** Vue3 不定高虚拟列表 Hooks */
export default function useVirtualList(
listData:Ref,options:VirtualListOptions={}
){
const {pageSize=20。estimateHeight=60}=options
const wrapperRef=ref
const startIndex=ref
const endIndex=ref
const scrollOffset=ref
const itemHeightCache=ref
const getItemHeight==>itemHeightCache.value?，estimateHeight
const totalHeight=computed=>{
let t=0
listData.value.forEach=>t+=getItemHeight)
return t
})
const visibleList=computed=>listData.value.slice)
const handleScroll=:void=>{
ifreturn
const top=wrapperRef.value.scrollTop
scrollOffset.value=top
let sum=0,start=0
for{
sum+=getItemHeight
if{start=i;br​eak}
}
startIndex.value=start
endIndex.value=start+pageSize
}
/** 缓存单条真实 Height */
const updateItemHeight==>{if{itemHeig…htCache.val，/** 全量重置 – 搜索/刷新/弹窗等情形调用 */
const resetVirtualL…st=>{，}
/** 增量拼接 – 分页加载专用 */
const appendLis…
ta==>{listDa…
value=}
return{
wrapperRef,visibleLis…不过，t,totalHeig…scrol，ffset,startI…handl，croll,u…updat，temHei…rese，tVir…appe，dLis…}
}

. 分页业务组件完整案例

&/d iv>

&/t emplate&

---