10 万条数据滚动不卡?聊聊我写的虚拟列表组件 vue-virtualize

中后台最常见的长列表场景:用户列表、日志流水、订单记录,动辄几万条。直接 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...

二、核心原理:撑高 + 定位 + 只渲染窗口

虚拟列表的三板斧:

  1. 外层可滚动容器 ,固定高度,overflow-y: auto。
  2. 内部一个撑高元素(spacer) ,高度 = items.length × itemSize,让滚动条「看起来」有 10 万条那么长。
  3. 只渲染 [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
})

三个关键点:

  1. buffer(overscan) :视口外多渲染几项。否则快速滚动时,新的项还没渲染出来,会出现白屏。buffer 默认 6,就是上下各多渲染 6 项。
  2. 每项绝对定位 + top 计算 :因为 spacer 是 position: relative,子项绝对定位的 top 就是它在整个列表中的真实偏移,渲染窗口怎么滑都对得上。
  3. 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 里写清楚了这一点,避免误导。

六、踩过的坑

  1. key 用 index 的坑 。第一版图省事全用 index 当 key,结果列表项里放了带 v-model 的输入框,滚动后输入框的值串位了。加了 keyField 才修好。
  2. 构建类型产物 。.vue 组件的 defineProps<Props>() 用 vite 打包声明文件会报「无法命名」错误,最终 vite build 出 JS/CSS + vue-tsc 单独出 .d.ts,稳(这块在 vue-crud-schemas 那篇也提过,是组件库打包的通用坑)。
  3. 滚动事件要节流吗? 我实测下来,scroll 里只做一次 scrollTop 赋值 + computed 重算(几十项),远没到需要节流的量级,加节流反而引入延迟。性能瓶颈在 DOM 数量,不在计算。

写在最后

虚拟列表是「面试高频 + 工作刚需」的典型。原理不复杂,但把它封装成类型安全、带 overscan、自适应、可定位的组件,需要抠不少细节。这个库源自我做数据中台时的列表优化,希望能帮到被长列表折磨的人。

欢迎 star、提 issue、一起完善。

相关推荐
zhanlang021716 分钟前
HTML 零基础入门到企业实战【第七章 7.5】表单验证基础属性:required、maxlength、placeholder
前端·html
涛涛ing25 分钟前
为了快 30 倍,我把构建工具换成了 Rust,结果团队差点连班都加不了
前端
parade岁月1 小时前
SolidJS 2.0 正式发布:异步成为响应式的一部分
前端
lcy_241 小时前
防抖节流、并发控制、指数退避重试——我把它收进了一个库 async-concurrency-kit
前端
程序员大阳1 小时前
副队长Vue3教程(5)--事件绑定 v-on
前端·javascript·vue.js·vue3·事件绑定·v-on
艾莉丝努力练剑1 小时前
【AI大模型接入SDK】C++的SessionManager 线程安全
java·开发语言·前端·c++·人工智能·学习·安全
泯泷2 小时前
Vercel AI SDK 6 完整教程系列 - 第二部分:结构化数据与工具调用
前端·javascript
OpenTiny社区3 小时前
我用Vue 100%复制DeepSeek开源的网页App,代码更少,功能还更多!
前端·vue.js·github
MyBili3 小时前
Chrome开发者工具入门:从看懂页面到高效调试
前端·chrome·谷歌浏览器·开发工具·chrome devtools·网页调式·网络请求分析