Skip to content

@neosjs/virtualscroller ​

虚拟滚动容器。通过固定的 itemSize 计算可视窗口,只渲染可视区域内的元素并用 spacer 占位撑起滚动条,支持垂直、水平与双向(表格)三种方向、延迟渲染、懒加载与加载骨架。

安装 ​

sh
pnpm add @neosjs/virtualscroller
sh
npm i @neosjs/virtualscroller
sh
yarn add @neosjs/virtualscroller

快速上手 ​

items 传入数据,itemSize 指定单项尺寸(px),用 item 插槽渲染每一项。

vue
<script setup lang="ts">
import { VirtualScroller } from '@neosjs/virtualscroller'
import { ref } from 'vue'

const items = ref(Array.from({ length: 10000 }, (_, i) => i))
</script>

<template>
  <VirtualScroller :items="items" :item-size="36" style="height: 300px">
    <template #item="{ item, options }">
      <div :style="{ height: '36px' }">
        {{ options.index }} - 第 {{ item }} 项
      </div>
    </template>
  </VirtualScroller>
</template>

方向 ​

  • orientation="vertical"(默认):垂直滚动,itemSize 为行高。
  • orientation="horizontal":水平滚动,itemSize 为列宽。
  • orientation="both":双向滚动(表格场景),items 为二维数组,itemSize 为 [行高, 列宽],可通过 columns 传入列数据。

懒加载 ​

lazy 开启后,滚动跨越加载边界时触发 lazy-load 事件,事件参数为 { first, last } 渲染区间;配合 show-loader 与 loader 插槽可显示加载占位。

vue
<VirtualScroller
  :items="items"
  :item-size="36"
  lazy
  :step="100"
  show-loader
  @lazy-load="onLazyLoad"
>
  <template #item="{ item }">
    <div :style="{ height: '36px' }">{{ item }}</div>
  </template>
</VirtualScroller>

Props ​

参数类型默认值说明
itemsArray—数据数组,both 方向时为二维数组
item-sizenumber | number[]0单项尺寸(px),both 方向时为 [行高, 列宽]
orientation'vertical' | 'horizontal' | 'both''vertical'滚动方向
scroll-heightstring—容器高度,如 '300px'、'100vh'
scroll-widthstring—容器宽度
delaynumber0滚动到渲染的延迟(ms),用于降低快速滚动时的渲染频率
resize-delaynumber10窗口尺寸变化后重新计算的延迟(ms)
num-tolerated-itemsnumber—视口两侧预渲染的容忍项数量,不传时按视口项数的一半自动计算
lazybooleanfalse是否开启懒加载
stepnumber0每页项数,开启后按页触发懒加载
loadingbooleanfalse懒加载模式下显示加载状态
show-loaderbooleanfalse加载时是否显示加载指示区域
loader-disabledbooleanfalse是否禁用加载指示区域
show-spacerbooleantrue是否渲染占位元素以撑起滚动条
inlinebooleanfalse是否以内联方式设置容器高度为父元素高度
append-onlybooleanfalse仅追加模式,滚动到顶部时不重渲染前面的内容(适合聊天记录)
auto-sizebooleanfalse是否根据内容自适应尺寸
disabledbooleanfalse禁用虚拟滚动,直接渲染全部内容
columnsArray—列数据(水平/双向滚动时使用)
tabindexnumber0容器的 tabindex
idstring—容器 id
styleobject—容器内联样式
classstring—容器类名

Emits ​

事件名参数说明
scroll(event: Event)滚动时触发
scroll-index-change(state: { first: number | { rows, cols }, last: number | { rows, cols } })渲染区间变化时触发
lazy-load(state: { first: number, last: number })需要加载新数据时触发
update:numToleratedItems(value: number)容忍项数量计算更新时触发

Slots ​

插槽名参数说明
itemitem: 数据项, options: { index, count, first, last, even, odd }渲染可视区域内的每一项
content见下方完全接管内容渲染(含 items、contentRef、contentStyle、spacerStyle、vertical/horizontal/both 等)
loaderoptions: { index, count, first, last, even, odd, numCols? }自定义加载占位内容
loadingicon—自定义加载图标
default—disabled 开启时直接渲染的默认内容

方法 ​

通过 ref 可调用以下方法:

方法名参数说明
scrollTo(options)滚动到指定位置,透传原生 Element.scrollTo 参数
scrollToIndex(index: number | number[], behavior?)滚动到指定索引,both 方向传 [行, 列]
scrollInView(index, to?: 'to-start' | 'to-end', behavior?)将指定项滚动到可视区域起始或末尾
getRenderedRange—获取当前渲染区间 { first, last, viewport }