VirtualList（虚拟列表）

VirtualList 组件基于 TanStack Virtual 实现高性能虚拟滚动列表，适用于大数据量场景，支持自定义每一项的渲染。

基本用法

List length: 1000

Max count: 3000

1Item 1delete

2Item 2delete

3Item 3delete

4Item 4delete

5Item 5delete

6Item 6delete

7Item 7delete

8Item 8delete

9Item 9delete

10Item 10delete

11Item 11delete

1Item 1

2Item 2

3Item 3

4Item 4

<script setup lang="ts">
import type { VirtualListSlotData } from "@hoci/core";
import { ref } from "vue";

const MAX_COUNT = 3000;

const list = ref(Array.from({ length: 1000 }, (_, i) => ({
  name: `Item ${i + 1}`,
  value: i + 1
})));

function handleDelete(index: number) {
  list.value.splice(index, 1);
}

function appendBatch(num: number) {
  const oldLength = list.value.length;
  num = Math.min(num, MAX_COUNT - oldLength);
  list.value.push(...Array.from({ length: num }, (_, i) => ({
    name: `Item ${i + 1 + oldLength}`,
    value: i + 1 + oldLength
  })));
}

function handleScrollEnd() {
  appendBatch(100);
}
</script>

<template>
  <div class="w-120">
    <div class="flex gap-2">
      <div>List length: {{ list.length }}</div>
      <div>Max count: {{ MAX_COUNT }}</div>
    </div>
    <div class="flex gap-2 w-120">
      <button class="bg-blue-500 flex-1 text-white p-2 rounded-md hover:bg-blue-600 mb-4" @click="appendBatch(1)">
        append 1 item
      </button>
      <button class="bg-blue-500 flex-1 text-white p-2 rounded-md hover:bg-blue-600 mb-4" @click="appendBatch(10)">
        append 10 items
      </button>
      <button class="bg-blue-500 flex-1 text-white p-2 rounded-md hover:bg-blue-600 mb-4" @click="appendBatch(100)">
        append 100 items
      </button>
    </div>
    <hi-virtual-list
      :count="list.length"
      :estimate-size="40"
      class="overflow-y-auto w-120 h-100 border-1 border-solid border-#eee rounded-md"
      @scroll-end="handleScrollEnd"
    >
      <template #item="{ index, style }: VirtualListSlotData">
        <div
          :style="style"
          class="flex w-full space-x-4 justify-between items-center h-full p-4" :class="{
            'bg-white': index % 2 === 0,
            'bg-gray-50': index % 2 === 1,
          }"
        >
          <span class="text-center font-bold w-20 inline-block">{{ list[index].value }}</span>
          <span>{{ list[index].name }}</span>
          <span class="text-red-500 cursor-pointer" @click="handleDelete(index)">delete</span>
        </div>
      </template>
      <div class="absolute bottom-0 left-0 w-full">
        <div>add</div>
      </div>
    </hi-virtual-list>

    <hi-virtual-list
      :count="list.length"
      :estimate-size="200"
      horizontal
      class="overflow-x-auto w-full h-20 border-1 border-solid border-#eee rounded-md"
    >
      <template #item="{ index, style }: VirtualListSlotData">
        <div
          :style="style" class="flex flex-col items-center justify-center p-4" :class="{
            'bg-white': index % 2 === 0,
            'bg-gray-50': index % 2 === 1,
          }"
        >
          <span class="text-center">{{ list[index].value }}</span>
          <span>{{ list[index].name }}</span>
        </div>
      </template>
    </hi-virtual-list>
  </div>
</template>

Props(属性)

名称	类型	默认值	说明
count	number	0	列表总项数
estimate-size	number | (index:number)=>number	50	预估每项高度/宽度（支持函数）
horizontal	boolean	false	是否为横向滚动
options	object	{}	传递给虚拟化的其他参数

Slots(插槽)

名称	说明
item	渲染每一项，参数为 { index, style }

Events(事件)

事件名	说明	回调参数
scrollEnd	滚动到末尾时触发	无
scrollStart	滚动到开头时触发	无
scroll	滚动时触发	当前可见项的索引数组