更新记录

1.0.0（2026-03-19） 下载此版本

首次发布

平台兼容性

uni-app(4.45)

uni-app x(4.45)

uni-virtual-list（长列表虚拟滚动）

解决了什么问题

• 解决列表卡顿：10万+数据不再一次性渲染，滚动更流畅
• 内存占用显著下降：只渲染可视区域 + 缓冲区，常见场景内存占用可降低90%+
• 跨端通用：uni-app / uni-app x，适配鸿蒙Next + Android + iOS（同时兼容H5/小程序）

说明：虚拟列表的核心前提是 item高度固定（或可稳定估算）。如果你的 item 高度完全不固定，请先改成固定行高/卡片高度，或使用“分页/分组”的方式降低一次性渲染量。

安装

将插件导入项目后，会生成目录：uni_modules/uni-virtual-list/

组件使用：

• uni_modules/uni-virtual-list/components/uni-virtual-list/uni-virtual-list.vue

示例工程：

• uni_modules/uni-virtual-list/example/（可直接运行）

快速使用

<template>
  <uni-virtual-list
    :list="list"
    :item-height="itemHeight"
    :height="listHeight"
    :buffer="8"
    :lower-threshold="200"
    refresher-enabled
    @refresherrefresh="onRefresh"
    @loadmore="onLoadMore"
  >
    <template #default="{ item, index }">
      <view class="row">
        <text class="idx">{{ index }}</text>
        <text class="txt">{{ item.title }}</text>
      </view>
    </template>
  </uni-virtual-list>
</template>

<script>
export default {
  data() {
    return {
      list: [],
      itemHeight: 88, // px（建议固定）
      listHeight: 600 // px（建议明确给定，或用uni.getSystemInfoSync计算）
    }
  },
  methods: {
    async onRefresh() {
      // 下拉刷新：你可以重置数据
      // this.list = await fetchFirstPage()
      this.$refs?.vlist?.finishRefresh?.()
    },
    async onLoadMore() {
      // 上拉加载：你可以追加数据
      // this.list.push(...await fetchNextPage())
    }
  }
}
</script>

Props

• list: Array 数据源
• itemHeight: Number 单个item高度（px，必填）
• height: Number|String 容器高度（px 或 xxxpx，建议必填）
• buffer: Number 上下缓冲渲染条数（默认 6）
• lowerThreshold: Number 触底阈值（默认 80，单位px）
• refresherEnabled: Boolean 是否开启下拉刷新（默认 false）
• refresherTriggered: Boolean 外部控制刷新状态（可选）

Events

• scroll: (e) => void 原始滚动事件
• refresherrefresh: 下拉刷新触发
• loadmore: 触底触发（上拉加载）

性能建议（很关键）

• item高度固定：强烈建议固定 itemHeight
• 减少item内部复杂度：避免每条item里大量图片/阴影/复杂布局
• 把重逻辑放到数据层：不要在渲染时做复杂计算
• 合理设置buffer：一般 6~12 即可，过大反而增内存

License

MIT（见 license.md）