uni-app虚拟列表需手动基于scroll-view实现,核心是固定行高、动态偏移渲染子集、用calc撑开总高度,禁用dynamic高度模式,v-for绑定新数组引用,滚动事件节流至16–32ms并预留上下各3条缓冲区。

uni-app虚拟列表必须用scroll-view手动实现,没有内置组件
uni-app官方没提供VirtualList或list-view这类开箱即用的虚拟列表组件——所谓“list-view”在文档里是过时残留项,实际未实现,真用了会报Component list-view not found。你得基于scroll-view自己搭骨架,核心是控制渲染范围+撑开滚动高度+动态偏移。
关键不是“有没有组件”,而是你能否把三件事做对:
-
scroll-view设固定height(不能100vh或100%),否则iOS微信里滚动事件不触发 - 用
transform: translateY()移动真实渲染的子集,而不是靠v-for全量挂载 - 总高度用
height: calc(单行高 * 总条数)撑开,让滚动条有合理长度
固定行高是性能底线,cell-height-mode="dynamic"慎用
所有手写或第三方虚拟列表(如z-paging)在小程序端的高性能前提,都是行高可预测。一旦启用cell-height-mode="dynamic",底层就得反复调用uni.createSelectorQuery()测高——这操作在滚动中触发,会导致严重错位、卡顿,甚至白屏。
如果你的列表项含图片、多行文本或条件样式,别硬扛“动态高”。可行替代方案:
- 统一用
aspect-ratio+object-fit约束图片,避免重排 - 文本截断用
line-clamp(H5支持)或text-overflow: ellipsis(小程序需固定行数) - 所有
view设height: 80rpx(举例),哪怕留空白,也比测高强
key写index等于埋雷,item.id只是基础要求
很多人以为只要:key="item.id"就安全了,其实漏掉更隐蔽的坑:当列表发生增删(比如点赞后局部刷新)、或数据源被filter/sort重排时,v-for仍可能复用错误的DOM节点,导致状态错乱(比如A项的开关状态跑到B项上)。
真正稳的做法:
- 渲染子集时,
v-for必须绑定到一个**新数组引用**(不能直接slice原数组后赋值给同一响应式字段) - 用
Object.freeze()冻结原始listData,避免Vue劫持带来额外开销 - 若需局部更新某一项,不要
this.listData[index] = newItem,改用splice并确保索引同步修正
滚动事件必须节流,但别用lodash.throttle
小程序逻辑层和渲染层分离,scroll事件在快速滚动时每秒能发上百次。不做节流,setData会堆积、超256KB限制、触发失败;但用lodash.throttle又引入额外包体积且不兼容小程序运行时。
轻量可靠的做法是手写时间窗口判断:
onScroll(e) {
const now = Date.now()
if (now - this.lastScrollTime < 16) return // 强制不低于60fps
this.lastScrollTime = now
const scrollTop = e.detail.scrollTop
const startIdx = Math.floor(scrollTop / this.itemHeight)
if (startIdx !== this.startIndex) {
this.startIndex = startIdx
this.visibleData = this.listData.slice(startIdx, startIdx + this.visibleCount)
}
}注意:这个节流粒度(16ms)比视觉可感知的帧率还紧,但scroll-view在iOS上本身就有延迟,太激进反而漏计算。实测16–32ms区间最稳。
最常被忽略的点:缓冲区数量。只渲染可视区域那几条?不行。至少上下各加3条,否则快速滚动时会看到空白闪动——这不是bug,是你没预留“预加载”的余量。



















