中后台最常见的长列表场景:用户列表、日志流水、订单记录,动辄几万条。直接
v-for渲染,几万甚至十万个 DOM 节点,首屏白屏、滚动掉帧,体验直接崩掉。虚拟列表是标准解法:只渲染可视区,DOM 数量恒定,性能与数据量解耦 。我把它封装成一个零依赖的 Vue3 组件 vue-virtualize,这篇文章讲透它的原理和实现。
一、先看效果
10 万条数据,滚动丝滑,DOM 节点始终只有几十个:
vue
<script setup lang="ts">
import { ref } from 'vue'
import { VirtualList } from 'vue-virtualize'
const list = ref(Array.from({ length: 100000 }, (_, i) => ({ id: i, text: `第 ${i} 条数据` })))
const listRef = ref()
function jump() {
listRef.value?.scrollToIndex(50000, 'center') // 跳到第 50000 条
}
</script>
<template>
<button @click="jump">跳到第 50000 条</button>
<VirtualList ref="listRef" :items="list" :item-size="40" height="400px" :buffer="8" key-field="id">
<template #default="{ item, index }">
<div style="height: 40px; line-height: 40px; border-bottom: 1px solid #eee">
{{ index }}. {{ item.text }}
</div>
</template>
</VirtualList>
</template>
在线 demo:lcy-24.github.io/vue-virtual...
二、核心原理:撑高 + 定位 + 只渲染窗口
虚拟列表的三板斧:
- 外层可滚动容器 ,固定高度,
overflow-y: auto。 - 内部一个撑高元素(spacer) ,高度 =
items.length × itemSize,让滚动条「看起来」有 10 万条那么长。 - 只渲染
[start, end]区间的项,每项绝对定位到正确偏移。
vue
<template>
<div ref="containerRef" class="vv-list" :style="containerStyle" @scroll="onScroll">
<div class="vv-list__spacer" :style="{ height: totalHeight + 'px', position: 'relative', width: '100%' }">
<div v-for="vi in visibleItems" :key="..." class="vv-list__item" :style="vi.style">
<slot :item="vi.item" :index="vi.index" />
</div>
</div>
</div>
</template>
其中 totalHeight = items.length * itemSize,visibleItems 只包含 [start, end] 区间的项。
三、核心计算:滚动位置 → 起止索引
ts
const startIndex = computed(() =>
Math.max(0, Math.floor(scrollTop.value / props.itemSize) - props.buffer)
)
const endIndex = computed(() =>
Math.min(
props.items.length,
Math.ceil((scrollTop.value + viewportHeight.value) / props.itemSize) + props.buffer
)
)
const visibleItems = computed<VisibleItem[]>(() => {
const result: VisibleItem[] = []
for (let i = startIndex.value; i < endIndex.value; i++) {
result.push({
item: props.items[i],
index: i,
style: {
position: 'absolute',
top: `${i * props.itemSize}px`, // 绝对定位到正确偏移
height: `${props.itemSize}px`,
left: '0', right: '0',
},
})
}
return result
})
三个关键点:
buffer(overscan) :视口外多渲染几项。否则快速滚动时,新的项还没渲染出来,会出现白屏。buffer默认 6,就是上下各多渲染 6 项。- 每项绝对定位 +
top计算 :因为 spacer 是position: relative,子项绝对定位的top就是它在整个列表中的真实偏移,渲染窗口怎么滑都对得上。 keyField自定义 key :默认用index当 key,但如果列表项是「可交互、有内部状态」的组件,滚动时 index 会复用,导致状态串位。指定keyField="id",用真实 id 做 key 就能避免。
四、自适应视口 + 定位滚动
自适应 :容器高度可能变化(窗口缩放、布局调整),用 ResizeObserver 监听并重算 viewportHeight:
ts
onMounted(() => {
updateViewport()
if (typeof ResizeObserver !== 'undefined' && containerRef.value) {
resizeObserver = new ResizeObserver(updateViewport)
resizeObserver.observe(containerRef.value)
}
})
onBeforeUnmount(() => resizeObserver?.disconnect())
定位滚动 :这是普通 v-for 列表给不了的能力------精确跳到第 N 条:
ts
function scrollToIndex(index: number, align: 'start' | 'center' | 'end' = 'start') {
const el = containerRef.value
if (!el) return
const target = Math.min(Math.max(index, 0), props.items.length - 1)
let top = target * props.itemSize
if (align === 'center') top -= (el.clientHeight - props.itemSize) / 2
else if (align === 'end') top -= el.clientHeight - props.itemSize
el.scrollTop = Math.max(0, top)
}
固定高度下,第 N 条的偏移就是 N × itemSize,align 控制它在视口的哪个位置。通过 defineExpose 暴露出去,ref 就能调。
五、局限性:为什么是「固定高度」
这个组件是固定高度 虚拟列表(itemSize 恒定)。它覆盖了 80% 的场景------表格、日志、流水这类等高列表。但动态高度列表(如瀑布流、富文本卡片)需要测量每项高度,复杂度高一个量级,不在这个库的范围内。README 里写清楚了这一点,避免误导。
六、踩过的坑
key用 index 的坑 。第一版图省事全用index当 key,结果列表项里放了带v-model的输入框,滚动后输入框的值串位了。加了keyField才修好。- 构建类型产物 。
.vue组件的defineProps<Props>()用 vite 打包声明文件会报「无法命名」错误,最终vite build出 JS/CSS +vue-tsc单独出.d.ts,稳(这块在 vue-crud-schemas 那篇也提过,是组件库打包的通用坑)。 - 滚动事件要节流吗? 我实测下来,
scroll里只做一次scrollTop赋值 + computed 重算(几十项),远没到需要节流的量级,加节流反而引入延迟。性能瓶颈在 DOM 数量,不在计算。
写在最后
虚拟列表是「面试高频 + 工作刚需」的典型。原理不复杂,但把它封装成类型安全、带 overscan、自适应、可定位的组件,需要抠不少细节。这个库源自我做数据中台时的列表优化,希望能帮到被长列表折磨的人。
- 源码:github.com/lcy-24/vue-...
- npm:
npm install vue-virtualize - 在线 demo:lcy-24.github.io/vue-virtual...
欢迎 star、提 issue、一起完善。