Vue Virtual Scroll Plugin

一个基于 TypeScript + Vue 3 + Vite + Vitest + pnpm 的通用虚拟滚动组件库，示例 UI 使用 Element Plus。组件只负责虚拟滚动，具体内容完全由使用者通过插槽填充。

功能

| 功能 | 状态 | | --- | --- | | 固定高度虚拟列表 | 已支持 | | 可配置缓冲区 | 已支持 | | 滚动到指定下标 | 已支持 | | TypeScript 类型 | 已支持 | | Vue 3 组件 | 已支持 | | 通用插槽内容 | 已支持 | | Element Plus 示例 | 已支持 | | 动态高度 | 计划中 | | React 适配 | 计划中 |

安装

从 npm 安装：

pnpm add virtual-scroll-plugin

或使用 npm：

npm install virtual-scroll-plugin

使用

<script setup lang="ts">
import { ref } from "vue";
import { ElButton } from "element-plus";
import "element-plus/dist/index.css";
import { VirtualList, type VirtualListExpose } from "virtual-scroll-plugin";
import "virtual-scroll-plugin/style.css";

const listRef = ref<VirtualListExpose | null>(null);
const items = Array.from({ length: 10000 }, (_, index) => ({
  id: index,
  name: `Item ${index}`,
}));
</script>

<template>
  <button type="button" @click="listRef?.scrollToIndex(5000)">
    跳转
  </button>

  <VirtualList
    ref="listRef"
    container-class="list"
    :items="items"
    item-key="id"
    :item-height="40"
    :buffer="8"
  >
    <template #default="{ index, item, isScrolling }">
      <div class="row">
        <span>#{{ index }}</span>
        <span>{{ item.name }}</span>
        <el-tag size="small">
          {{ isScrolling ? "滚动中" : "稳定" }}
        </el-tag>
      </div>
    </template>
  </VirtualList>
</template>

<style scoped>
.list {
  height: 400px;
}
</style>

主入口导出：

import VirtualScrollPlugin, { VirtualList, calculateRange } from "virtual-scroll-plugin";

也可以全局注册：

import { createApp } from "vue";
import VirtualScrollPlugin from "virtual-scroll-plugin";
import "virtual-scroll-plugin/style.css";

createApp(App).use(VirtualScrollPlugin).mount("#app");

API

VirtualList Props

| 参数 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | items | unknown[] | 否 | 无 | 数据源；传入后 total 自动使用 items.length | | total | number | 否 | 无 | 数据总数；不传 items 时使用 | | itemHeight | number | 是 | 无 | 每一项高度 | | buffer | number | 否 | 5 | 上下额外渲染数量 | | tag | string | 否 | div | 外层滚动容器标签 | | itemTag | string | 否 | div | 每一项标签 | | itemKey | string \| function | 否 | 下标 | 每一项的 key | | containerClass | unknown | 否 | 空 | 外层容器 class | | itemClass | unknown | 否 | 空 | 每一项 class |

默认插槽

| 参数 | 说明 | | --- | --- | | index | 当前真实数据下标 | | item | items[index]，未传 items 时为 undefined | | isScrolling | 当前是否处于滚动中 |

VirtualList 事件与方法

| 名称 | 说明 | | --- | --- | | range-change | 渲染范围变化时触发 | | scrollToIndex(index) | 滚动到指定下标 | | refresh() | 手动刷新容器高度和滚动位置 | | getRange() | 获取当前范围 |

Element Plus 结合方式

VirtualList 不直接绑定 Element Plus，但可以在默认插槽中使用任意 Element Plus 组件，例如 el-tag、el-button、el-card。这样组件库保持轻量，同时业务 UI 可以完全使用 Element Plus。

本地开发

pnpm install
pnpm dev
pnpm test
pnpm build

开发示例入口是根目录 index.html，运行 pnpm dev 后访问 Vite 输出的本地地址。示例页面使用 Vue 3 和 Element Plus。

发布到 npm

发布前检查：

pnpm test
pnpm build
pnpm publish --dry-run

登录 npm：

pnpm config set registry https://registry.npmjs.org/
pnpm login
pnpm whoami

正式发布：

pnpm publish --otp=你的6位验证码

后续发布新版本：

pnpm version patch
pnpm publish --otp=你的6位验证码

版本升级建议：

| 改动类型 | 命令 | 示例 | | --- | --- | --- | | 修复 bug | pnpm version patch | 0.1.0 -> 0.1.1 | | 新增功能 | pnpm version minor | 0.1.1 -> 0.2.0 | | 破坏性改动 | pnpm version major | 0.2.0 -> 1.0.0 |

License

MIT