滚动列表组件 (c-scroll-list)

滚动列表组件封装了上拉加载、下拉刷新功能，适用于需要分页加载数据的列表场景，大幅简化了分页逻辑的处理。

基本用法

vue

<template>
    <view class="container">
        <c-scroll-list :api="api" :apiParams="apiParams" @load="load">
            <view v-for="(item, index) in list" :key="index" class="list-item">
                <text>{{ item.name }}</text>
                <text>{{ item.price }}</text>
            </view>
            <!-- 自定义空数据状态 -->
            <template #empty>
                <view class="empty">
                    <image src="/static/empty.png"></image>
                    <text>暂无数据</text>
                </view>
            </template>
        </c-scroll-list>
    </view>
</template>

<script>
export default {
    data() {
        return {
            api: this.$api.geiList(),
            apiParams: {
                pageNum: 1,
                pageSize: 10,
            },
            list: [],
            params: {
                pageNum: 1,
                pageSize: 10,
                keyword: "",
                category: "",
            },
        };
    },
    methods: {
        // 获取列表数据的方法
        getProductList() {},

        // 数据加载成功的回调
        load(data) {
            console.log("列表数据加载成功", data);
            this.list = data.list;
        },
    },
};
</script>

手动刷新

有时候我们需要在某些操作后手动刷新列表，可以通过 ref 来调用组件的内部方法。

vue

<template>
    <view class="container">
        <view class="filter">
            <input v-model="params.keyword" placeholder="搜索关键词" />
            <button @click="onSearch">搜索</button>
        </view>

        <c-scroll-list ref="scrollList" :apiParams="apiParams" @load="load">
            <!-- 列表内容... -->
        </c-scroll-list>
    </view>
</template>

<script>
export default {
    data() {
        return {
            api: this.$api.xxxx,
            apiParams: {
                pageNum: 1,
                pageSize: 10,
                keyword: "",
                category: "",
            },
        };
    },
    methods: {
        load(data) {
            // 获取列表数据...
            console.log("列表数据", data);
        },

        // 搜索按钮点击事件
        onSearch() {
            // 手动触发刷新
            this.$refs.scrollList.refresh();
        },
    },
};
</script>

属性说明

属性名	类型	默认值	说明
api	Function	-	请求列表数据的API方法，必须返回Promise
apiParams	Object	{}	请求参数，会作为参数传递给api方法
option	Object	{}	组件配置项，详见下方option配置

option配置项

属性名	类型	默认值	说明
page	Number	1	初始页码
size	Number	10	每页数据量
auto	Boolean	true	是否自动加载
field	String	''	数据字段名，如果接口返回的列表不在顶层，可通过此参数指定
height	Number	null	组件高度，单位upx，不设置则自动计算
disabled	Boolean	false	是否禁用上拉加载和下拉刷新
background	String	''	背景颜色
emptyImage	String	''	自定义空数据图片，不设置则使用内置图片
offsetBottom	Number	0	底部高度补偿，单位upx
pullDownSpeed	Number	0.5	下拉速率
lowerThreshold	Number	40	距离底部多远时触发上拉加载，单位px
refresherThreshold	Number	60	下拉多少距离触发下拉刷新，单位px
refreshDelayed	Number	800	刷新延迟时间，单位ms
refreshFinishDelayed	Number	200	刷新完成后的延迟时间，单位ms
safeArea	Boolean	false	是否开启安全区域适配
emptyTextColor	String	"#82848a"	空提示文字颜色
loadTextColor	String	"#82848a"	上拉加载文字颜色
loadIconColor	String	"#82848a"	上拉加载图标颜色
refresherTextColor	String	"#82848a"	下拉刷新文字颜色
refresherIconColor	String	"#82848a"	下拉刷新图标颜色
emptyText	String	"暂无列表~"	空数据提示文字
loadingText	String	"正在加载中~"	加载中文字
loadFailText	String	"加载失败~"	加载失败文字
noMoreText	String	"没有更多~"	没有更多文字
refreshingText	String	"正在刷新~"	正在刷新文字
refreshFailText	String	"刷新失败~"	刷新失败文字
refreshSuccessText	String	"刷新成功~"	刷新成功文字
pulldownText	String	"下拉刷新~"	下拉中的文字
pulldownFinishText	String	"松开刷新~"	下拉完成的文字

事件说明

事件名	说明	回调参数
init	组件初始化完成时触发	rect: Object (组件尺寸信息)
load	数据加载完成时触发	`{ list, count, otherData }`
loadSuccess	数据加载成功时触发	list: Array (列表数据)
loadFail	数据加载失败时触发	-
refreshSuccess	刷新成功时触发	list: Array (列表数据)
refreshError	刷新失败时触发	-
refreshStop	下拉刷新中断时触发	-
scroll	滚动时触发	e: Object (滚动事件对象)
scrolltolower	滚动到底部时触发	e: Object (滚动事件对象)
touchStart	触摸开始时触发	e: Object (触摸事件对象)
touchMove	触摸移动时触发	e: Object (触摸事件对象)
touchEnd	触摸结束时触发	e: Object (触摸事件对象)

方法

方法名	说明	参数
load	加载数据	state (Boolean): 是否重置数据，默认true
refresh	刷新数据，会重置到第一页	-
initList	初始化列表	state (Boolean): 是否仅刷新数据状态 resetOrder (Boolean): 是否清空数据 type (String): 加载类型，可选值为"load"或"refresh"

插槽

插槽名	说明	作用域参数
default	一般为列表内容	-
empty	自定义空数据状态	-
pulldown	自定义下拉刷新状态	-
pullup	自定义上拉加载状态	-

注意事项

api 方法必须返回 Promise，且 resolve 的数据格式需包含 list 和 total 字段
如果接口返回的数据结构不是 {list, total}，可以通过 option.field 指定数据字段
组件内部会自动处理分页逻辑，无需在外部进行数据拼接
修改 apiParams 参数后，需要手动调用 refresh() 方法刷新列表
组件默认高度会自动计算，如需固定高度可通过 option.height 属性设置

滚动列表组件 (c-scroll-list) ​

基本用法 ​

手动刷新 ​

属性说明 ​

option配置项 ​

事件说明 ​

方法 ​

插槽 ​

注意事项 ​

滚动列表组件 (c-scroll-list)

基本用法

手动刷新

属性说明

option配置项

事件说明

方法

插槽

注意事项