一个功能完备的uni-app滚动视图组件，支持自定义下拉刷新、上拉加载更多和虚拟列表（Virtual List）功能。

更新记录

1.0.0（2025-12-04） 下载此版本

初始功能

---

平台兼容性

uni-app(4.66)

Vue2	Vue3	Chrome	Safari	app-vue	app-nvue	Android	iOS	鸿蒙
√	-	-	-	-	-	-	-	-

微信小程序	支付宝小程序	抖音小程序	百度小程序	快手小程序	京东小程序	鸿蒙元服务	QQ小程序	飞书小程序	快应用-华为	快应用-联盟
-	-	-	-	-	-	-	-	-	-	-

liaction-sv

一个功能完备的uni-app滚动视图组件，支持自定义下拉刷新、上拉加载更多和虚拟列表（Virtual List）功能。

功能特性

• ✨ 自定义下拉刷新
• 📱 上拉加载更多
• 🔝 返回顶部按钮
• 🎨 可配置的加载图标和文字
• 🔄 支持外部调用刷新和加载更多方法
• 📋 支持虚拟列表（Virtual List）功能

基本用法

安装组件

通过uni_modules方式引入组件。

使用示例

<template>
  <view class="container">
    <liaction-sv ref="scrollView" @refresh="onRefresh" @loadMore="onLoadMore" :enableRefresher="true" :enableLoadingMore="true">
      <!-- 内容区域 -->
      <view v-for="(item, index) in list" :key="index" class="list-item">
        <text>{{ item }}</text>
      </view>
    </liaction-sv>
  </view>
</template>

<script>
export default {
  data() {
    return {
      list: []
    };
  },
  methods: {
    // 下拉刷新
    onRefresh() {
      // 模拟数据获取
      setTimeout(() => {
        this.list = ['Item 1', 'Item 2', 'Item 3', 'Item 4', 'Item 5'];
        // 结束刷新
        this.$refs.scrollView.finishRefresh();
      }, 1000);
    },
    // 上拉加载更多
    onLoadMore() {
      // 模拟数据获取
      setTimeout(() => {
        this.list = [...this.list, 'More Item 1', 'More Item 2', 'More Item 3'];
        // 结束加载，传入false表示没有更多数据
        this.$refs.scrollView.finishLoadMore(true);
      }, 1000);
    }
  }
};
</script>

<style>
.container {
  width: 100%;
  height: 100vh;
}

.list-item {
  padding: 20px;
  border-bottom: 1px solid #eee;
}
</style>

虚拟列表使用说明

固定高度模式

当设置 itemHeight 为固定值时，组件会使用固定高度模式，性能最优：

<liaction-sv :enableVirtualList="true" :itemHeight="60" :dataSource="list">
  <template #virtual-list="{ data }">
    <!-- 虚拟列表项内容 -->
  </template>
</liaction-sv>

自动高度模式

当 itemHeight 设为 0 时，组件会启用自动高度模式，自动测量每个列表项的实际高度：

<liaction-sv :enableVirtualList="true" :itemHeight="0" :dataSource="list">
  <template #virtual-list="{ data }">
    <!-- 虚拟列表项内容，高度不固定 -->
  </template>
</liaction-sv>

属性说明

属性名	类型	默认值	说明
showHeader	Boolean	false	是否显示头部区域
showFooter	Boolean	false	是否显示底部区域
enableRefresher	Boolean	false	是否启用下拉刷新
enableLoadingMore	Boolean	false	是否启用上拉加载更多
enableVirtualList	Boolean	false	是否启用虚拟列表功能
itemHeight	Number	0	虚拟列表项高度（设置为0时启用自动高度计算）
dataSource	Array	[]	虚拟列表数据源
showFixedArea	Boolean	false	是否显示右下角固定区域
showBackTop	Boolean	false	是否显示返回顶部按钮
showScrollbar	Boolean	false	是否显示滚动条
loadingText	String	'加载中...'	上拉加载时显示的文本
noMoreText	String	'没有更多数据了'	没有更多数据时显示的文本
refresherTextPulling	String	'下拉刷新'	下拉过程中显示的文本
refresherTextRelease	String	'松手刷新'	准备刷新时显示的文本
refresherTextRefreshing	String	'刷新中...'	刷新过程中显示的文本
loadingIconColor	String	'#666'	加载图标的默认颜色
refresherIconColor	String	''	下拉刷新图标的颜色，优先级高于loadingIconColor
loadingMoreIconColor	String	''	上拉加载图标的颜色，优先级高于loadingIconColor

方法说明

方法名	参数	说明
scrollToTop	-	滚动到顶部
scrollTo	{ scrollTop: Number }	滚动到指定位置
startRefresh	refresherText?: String	开始下拉刷新，可传入自定义刷新文本
finishRefresh	-	结束下拉刷新
startLoadMore	loadingText?: String	开始上拉加载更多，可传入自定义加载文本
finishLoadMore	hasMore?: Boolean	结束上拉加载更多，传入false表示没有更多数据
measureItemHeight	(index: Number, height: Number)	手动测量并更新列表项高度（主要用于自动高度模式）

事件说明

事件名	说明
scrolltoupper	滚动到顶部时触发
scrolltolower	滚动到底部时触发
refresherpulling	下拉刷新过程中触发
refresherrefresh	下拉刷新开始时触发
refresherrestore	下拉刷新结束时触发
refresherabort	下拉刷新中止时触发
scroll	滚动时触发，返回滚动事件对象
refresh	下拉刷新开始时触发，与refresherrefresh相同
loadMore	上拉加载开始时触发，与scrolltolower相同

组件结构

<liaction-sv>
  <template #header>
    <!-- 自定义头部内容 -->
  </template>

  <!-- 主体内容区域 -->

  <template #virtual-list="{ data }">
    <!-- 虚拟列表项内容 -->
    <!-- data 格式: [{ item: dataItem, index: originalIndex }, ...] -->
  </template>

  <template #footer>
    <!-- 自定义底部内容 -->
  </template>

  <template #backTop>
    <!-- 自定义返回顶部按钮内容 -->
  </template>

  <template #beforeBackTop>
    <!-- 返回顶部按钮上方的固定区域 -->
  </template>

  <template #afterBackTop>
    <!-- 返回顶部按钮下方的固定区域 -->
  </template>
</liaction-sv>

注意事项

• 组件基于scroll-view，请遵循scroll-view规范
• 默认不启用下拉刷新和上拉加载更多功能,可当普通scroll-view用

虚拟列表注意事项

1. 性能优化：
   • 优先使用固定高度模式（设置itemHeight为固定值），性能最优
   • 自动高度模式会带来一定的性能开销，建议仅在列表项高度差异较大时使用
   • 建议数据源item数量较大时使用虚拟列表，否则普通列表性能更好

外部调用示例

// 开始下拉刷新
this.$refs.scrollView.startRefresh('正在刷新...');

// 结束下拉刷新
this.$refs.scrollView.finishRefresh();

// 开始上拉加载更多
this.$refs.scrollView.startLoadMore('正在加载更多...');

// 结束上拉加载更多（有更多数据）
this.$refs.scrollView.finishLoadMore(true);

// 结束上拉加载更多（没有更多数据）
this.$refs.scrollView.finishLoadMore(false);

// 滚动到顶部
this.$refs.scrollView.scrollToTop();

// 滚动到指定位置
this.$refs.scrollView.scrollTo({ scrollTop: 200 });

许可证

MIT