@neosjs/virtualscroller
虚拟滚动容器。通过固定的 itemSize 计算可视窗口,只渲染可视区域内的元素并用 spacer 占位撑起滚动条,支持垂直、水平与双向(表格)三种方向、延迟渲染、懒加载与加载骨架。
安装
sh
pnpm add @neosjs/virtualscrollersh
npm i @neosjs/virtualscrollersh
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
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| items | Array | — | 数据数组,both 方向时为二维数组 |
| item-size | number | number[] | 0 | 单项尺寸(px),both 方向时为 [行高, 列宽] |
| orientation | 'vertical' | 'horizontal' | 'both' | 'vertical' | 滚动方向 |
| scroll-height | string | — | 容器高度,如 '300px'、'100vh' |
| scroll-width | string | — | 容器宽度 |
| delay | number | 0 | 滚动到渲染的延迟(ms),用于降低快速滚动时的渲染频率 |
| resize-delay | number | 10 | 窗口尺寸变化后重新计算的延迟(ms) |
| num-tolerated-items | number | — | 视口两侧预渲染的容忍项数量,不传时按视口项数的一半自动计算 |
| lazy | boolean | false | 是否开启懒加载 |
| step | number | 0 | 每页项数,开启后按页触发懒加载 |
| loading | boolean | false | 懒加载模式下显示加载状态 |
| show-loader | boolean | false | 加载时是否显示加载指示区域 |
| loader-disabled | boolean | false | 是否禁用加载指示区域 |
| show-spacer | boolean | true | 是否渲染占位元素以撑起滚动条 |
| inline | boolean | false | 是否以内联方式设置容器高度为父元素高度 |
| append-only | boolean | false | 仅追加模式,滚动到顶部时不重渲染前面的内容(适合聊天记录) |
| auto-size | boolean | false | 是否根据内容自适应尺寸 |
| disabled | boolean | false | 禁用虚拟滚动,直接渲染全部内容 |
| columns | Array | — | 列数据(水平/双向滚动时使用) |
| tabindex | number | 0 | 容器的 tabindex |
| id | string | — | 容器 id |
| style | object | — | 容器内联样式 |
| class | string | — | 容器类名 |
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
| 插槽名 | 参数 | 说明 |
|---|---|---|
| item | item: 数据项, options: { index, count, first, last, even, odd } | 渲染可视区域内的每一项 |
| content | 见下方 | 完全接管内容渲染(含 items、contentRef、contentStyle、spacerStyle、vertical/horizontal/both 等) |
| loader | options: { 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 } |