KB UI

Appearance

VirtualList 虚拟列表 ​

定高大数据量列表的窗口化渲染：只渲染可视区 + 缓冲区的项，滚动时复用 DOM，万级数据也能流畅滚动。

基础用法 ​

items 传完整数据源，itemHeight 与 height 必填；默认插槽 item 接收 { item, index }。

vue
<template>
  <KbVirtualList :items="list" :item-height="40" :height="240">
    <template #item="{ item, index }">
      <div class="row">{{ index }} - {{ item.name }}</div>
    </template>
  </KbVirtualList>
</template>

<script setup>
const list = Array.from({ length: 10000 }, (_, i) => ({ name: `Item ${i}` }))
</script>

下方为 40 条静态数据的演示（可滚动，视口外不渲染）：

0 - 条目 0
1 - 条目 1
2 - 条目 2
3 - 条目 3
4 - 条目 4
5 - 条目 5
6 - 条目 6
7 - 条目 7
8 - 条目 8
9 - 条目 9
10 - 条目 10
11 - 条目 11

缓冲区 ​

buffer 控制视口上下各额外渲染的项数，增大可减少快速滚动时的白屏（默认 4）。

vue
<KbVirtualList :items="list" :item-height="40" :height="240" :buffer="8">
  …
</KbVirtualList>

无限加载 ​

滚动接近底部（默认提前 8px）时触发 reachEnd，可在此追加下一页数据。

vue
<KbVirtualList
  :items="list"
  :item-height="40"
  :height="240"
  :reach-end-threshold="40"
  @reach-end="loadMore"
>
  …
</KbVirtualList>

空状态 ​

items 为空时渲染 empty 插槽（默认「暂无数据」）。

API ​

Props ​

属性类型默认值说明
itemsT[]—数据源
itemHeightnumber—单项高度（px），固定高度模式
heightnumber—可视区高度（px）
buffernumber4视口上下额外渲染的项数
reachEndThresholdnumber8触发 reachEnd 的提前量（px）

事件 ​

事件参数说明
scrollnumber滚动位置变化（scrollTop）
reachEnd—滚动到底部

插槽 ​

插槽参数说明
item{ item, index }每一项内容
empty—数据为空时的展示