更新记录

1.0.1（2025-08-01）

1. 初次上传虚拟列表组件

平台兼容性

uni-app(4.75)

uni-app x(4.75)

下面是为你这段 uni-app 微信小程序虚拟滚动列表组件 <VirtualList /> 编写的一份Markdown 使用说明文档，结构清晰，适合放在项目 README 或 Wiki。

📦 VirtualList 虚拟列表组件

基于 uni-app + Vue 3 + UTS 开发的高性能虚拟滚动列表组件。 适用于微信小程序等移动端大数据列表场景，仅渲染可视区域，大幅减少节点数，提升性能。

✨ 功能特点

• 支持超大数据量（例如 1 万条以上）平滑滚动
• 自动计算缓冲区大小
• 支持自定义单项高度
• 提供 startIndex 与 list，方便自定义渲染
• 使用 scroll-view 实现原生流畅滚动体验

🔧 属性（Props）

🧩 插槽（Slots）

📦 示例代码

下面示例演示如何使用 <VirtualList /> 渲染一个包含 1 万条数据的列表，每行高度 80px。

模板

<template>
  <VirtualList :listData="myList" :itemHeight="80">
    <template #default="{ list, startIndex }">
      <view v-for="(item, index) in list" :key="item.id">
        <view
          style="height: 80px; border-bottom: 1px solid #eee; display: flex; align-items: center; padding: 0 12px;">
          <text>{{ startIndex + index }} - {{ item.id }} - {{ item.name }}</text>
        </view>
      </view>
    </template>
  </VirtualList>
</template>

脚本

<script setup lang="uts">
const items = Array.from({ length: 10000 }, (_, i) => ({
  id: i + 1,
  name: `测试项 ${i + 1}`
}))

const myList = ref(items)
</script>

样式

<style scoped>
.item {
  height: 80px;
  border-bottom: 1px solid #eee;
  display: flex;
  align-items: center;
  padding: 0 12px;
}
</style>

📌 提示

✅ itemHeight 必须与实际 item 高度保持一致，否则滚动错位 ✅ 大列表场景建议固定高度布局（如外层高度 100%） ✅ 可通过 bufferSize 手动调整缓冲区大小（更大更平滑，但占用内存更高）

⚙️ 内部工作机制

• 根据 scrollTop 和 itemHeight 计算当前可视区域
• 根据视口高度动态决定缓冲区行数
• 只渲染视口 + 缓冲区内的部分列表项
• 通过 translateY 实现虚拟定位

📞 联系

如需定制或优化可留言或提 Issue ✏️

如果还想，我也可以帮你写一份更完整的 API 文档 + 源码注释 或 中英双语版本，要的话直接告诉我！ 🚀