更新记录

0.0.5（2026-03-30） 下载此版本

• 兼容多列表渲染情况

0.0.4（2026-02-28） 下载此版本

• 嵌套滚动模式适配微信小程序

0.0.3（2026-02-28） 下载此版本

• 增加嵌套滚动模式，支付页面滚动模式

平台兼容性

uni-app(4.55)

easy-virtual-list

一个支持 uniapp 的虚拟列表组件，兼容微信小程序、H5 和 APP 环境，同时支持 Vue2 和 Vue3。

功能特性

• ✅ 虚拟列表加载，优化性能
• ✅ 支持动态高度和固定高度
• ✅ 支持双列瀑布流布局
• ✅ 兼容微信小程序、H5、APP 环境
• ✅ 同时支持 Vue2 和 Vue3
• ✅ 支持加载状态和完成状态显示
• ✅ 智能数据追加，无缝衔接新数据

安装

npm install easy-virtual-list

使用方法

全局注册

import EasyVirtualList from 'easy-virtual-list'
Vue.use(EasyVirtualList)

局部引入

<template>
  <easy-virtual-list
    :list="dataList"
    :item-height="100"
    :mode="'single'"
    :loading="loading"
    :finished="finished"
    @loadMore="handleLoadMore"
  >
    <template #default="{ item, index }">
      <view class="item">{{ item.title }}</view>
    </template>
  </easy-virtual-list>
</template>

<script>
import EasyVirtualList from 'easy-virtual-list'

export default {
  components: {
    EasyVirtualList
  },
  data() {
    return {
      dataList: [],
      loading: false,
      finished: false
    }
  },
  methods: {
    handleLoadMore() {
      if (this.loading || this.finished) return

      this.loading = true
      // 模拟加载数据
      setTimeout(() => {
        const newData = [] // 获取新数据
        this.dataList = [...this.dataList, ...newData]
        this.loading = false

        // 如果没有更多数据
        if (newData.length === 0) {
          this.finished = true
        }
      }, 1000)
    }
  }
}
</script>

自定义加载状态

<template>
  <easy-virtual-list
    :list="dataList"
    :loading="loading"
    :finished="finished"
    @loadMore="handleLoadMore"
  >
    <template #default="{ item, index }">
      <view class="item">{{ item.title }}</view>
    </template>

    <!-- 自定义加载状态 -->
    <template #loading>
      <view class="custom-loading">加载中...</view>
    </template>

    <!-- 自定义完成状态 -->
    <template #finished>
      <view class="custom-finished">没有更多了</view>
    </template>
  </easy-virtual-list>
</template>

Props

Events

Slots

使用说明

固定高度模式

当所有列表项高度相同时，设置 itemHeight 可以获得最佳性能：

<easy-virtual-list
  :list="dataList"
  :item-height="80"
  mode="single"
>
  <template #default="{ item }">
    <view style="height: 80px">{{ item.title }}</view>
  </template>
</easy-virtual-list>

动态高度模式

当列表项高度不固定时，设置 estimatedHeight 预估高度：

<easy-virtual-list
  :list="dataList"
  :estimated-height="100"
  mode="single"
>
  <template #default="{ item }">
    <view>{{ item.content }}</view>
  </template>
</easy-virtual-list>

瀑布流模式

双列瀑布流布局，适合图片列表：

<easy-virtual-list
  :list="dataList"
  :estimated-height="150"
  mode="waterfall"
>
  <template #default="{ item }">
    <view>
      <image :src="item.image" />
      <text>{{ item.title }}</text>
    </view>
  </template>
</easy-virtual-list>

注意事项

1. 动态高度模式下，组件会自动查询实际高度并更新，首次渲染可能会有轻微的位置调整
2. 瀑布流模式下，数据会根据高度自动分配到左右两列
3. 使用 loading 和 finished 属性可以控制加载状态的显示
4. 新数据通过数组追加的方式添加（[...oldList, ...newList]），组件会自动处理衔接
5. 微信小程序中，瀑布流模式的key使用了前缀（'left-'/'right-'）来避免slot重复警告
6. 使用 disableBounce 可以禁用iOS的滚动弹性效果，或者通过动态控制 behaviorShow 实现更灵活的控制

常见问题

微信小程序slot警告

如果遇到 "More than one slot named" 警告，这是因为瀑布流模式下左右两列都使用了默认slot。已通过为key添加前缀（'left-'/'right-'）来解决此问题。

iOS滚动弹性效果

如需禁用iOS的橡皮筋效果，可以：

1. 设置 disableBounce 为 true 完全禁用
2. 或使用组件内置的动态控制（滚动时启用，触底/触顶时禁用）

<!-- 完全禁用弹性效果（使用 overscroll-behavior-y: contain，保留滚动穿透） -->
<easy-virtual-list :disable-bounce="true" />

<!-- 使用内置动态控制（默认行为） -->
<easy-virtual-list />

注意：使用 overscroll-behavior-y: contain 可以禁用垂直方向的弹性效果，同时保留滚动穿透功能。

License

MIT