当前位置：首页 > news >正文

uniapp下拉刷新+分页组件（z-paging 组件）

news 2025/7/8 12:25:01

z-paging 组件使用文档

简介

z-paging 是一个功能强大的列表分页组件，支持下拉刷新、上拉加载更多、自动管理分页等功能。本文档将详细介绍如何在项目中使用 z-paging 组件，特别是如何实现列表与页面一起滑动的效果。

基本用法

1. 基础配置

<template><z-paging ref="paging" v-model="dataList" @query="queryList"><!-- 列表内容 --><view v-for="(item, index) in dataList" :key="index">{{ item.title }}</view></z-paging>
</template><script>
export default {data() {return {dataList: []}},methods: {queryList(pageNo, pageSize) {// 请求接口获取数据this.$api.getList({ pageNo, pageSize }).then(res => {// 将请求结果通过complete方法传给z-pagingthis.$refs.paging.complete(res.data.list);}).catch(e => {// 请求失败，调用fail方法this.$refs.paging.fail();})}}
}
</script>

2. 页面滚动模式

要实现列表与页面一起滑动，需要设置 use-page-scroll 属性为 true：

<z-paging ref="paging" :use-page-scroll="true" v-model="dataList" @query="queryList"><!-- 列表内容 -->
</z-paging>

常用属性

属性名	类型	默认值	说明
use-page-scroll	Boolean	false	使用页面滚动，设为true时列表会和页面一起滑动
default-page-size	Number	10	默认每页数据量
auto	Boolean	true	是否自动调用查询接口
fixed	Boolean	true	是否使用fixed布局，若设置为false，则z-paging的父容器必须具有固定高度
safe-area-inset-bottom	Boolean	false	是否开启底部安全区域适配
refresher-enabled	Boolean	true	是否开启自定义下拉刷新
loading-more-enabled	Boolean	true	是否开启加载更多功能
show-loading-more-no-more-view	Boolean	true	是否显示没有更多数据的视图

常用方法

方法名	参数	说明
complete	(dataList)	请求结束(成功)调用此方法，将请求的结果传递给z-paging
completeByTotal	(dataList, total)	请求结束(成功)调用，将请求结果及总数传递给z-paging
reload	()	重新加载分页数据，pageNo会重置为1
refresh	()	触发下拉刷新
doLoadMore	()	手动触发上拉加载更多
scrollToTop	(animate = true)	滚动到顶部，animate为是否使用动画效果
fail	()	请求失败时调用此方法

常用事件

事件名	参数	说明
@query	(pageNo, pageSize)	列表需要请求数据时触发
@refresh	()	下拉刷新被触发
@load-more	()	上拉加载更多被触发

实现列表与页面一起滑动

要实现列表与页面一起滑动，同时保留加载更多功能，需要进行以下设置：

设置 use-page-scroll 属性为 true
移除容器的固定高度限制
确保父容器样式正确

示例代码

<template><view class="page-container"><z-paging ref="paging" :use-page-scroll="true":default-page-size="10":auto="true":safe-area-inset-bottom="true"v-model="dataList" @query="queryList"><!-- 列表内容 --><view class="list-container"><view class="list-item" v-for="(item, index) in dataList" :key="index">{{ item.title }}</view></view></z-paging></view>
</template><script>
export default {data() {return {dataList: []}},methods: {queryList(pageNo, pageSize) {// 模拟请求接口setTimeout(() => {const list = [];for (let i = 0; i < pageSize; i++) {const item = {id: (pageNo - 1) * pageSize + i + 1,title: `第${pageNo}页-第${i + 1}项`}list.push(item);}// 假设总数据量为50条const total = 50;this.$refs.paging.completeByTotal(list, total);}, 1000)}}
}
</script><style lang="scss" scoped>
.page-container {/* 不设置固定高度，允许内容随页面滚动 */width: 100%;position: relative;
}.list-container {padding: 10px;
}.list-item {background-color: #ffffff;padding: 15px;margin-bottom: 10px;border-radius: 5px;box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}
</style>

注意事项

使用 use-page-scroll="true" 时，需要在页面的 onPageScroll 生命周期中调用 updatePageScrollTop 方法：

onPageScroll(e) {this.$refs.paging.updatePageScrollTop(e.scrollTop);
}

使用页面滚动模式时，不要给容器设置固定高度，否则会影响滚动效果
如果有吸顶效果需求，可以配合 sticky 组件使用
在页面滚动模式下，如果有顶部或底部固定内容，需要设置适当的 padding 或 margin 避免内容被遮挡

高级用法

自定义下拉刷新样式

<z-paging ref="paging" v-model="dataList" @query="queryList"><template #refresher><view class="custom-refresher"><image class="refresh-icon" :src="refreshIcon" :style="{transform: `rotate(${refresherStatus * 30}deg)`}"></image><text>{{ refresherStatus === 1 ? '下拉刷新' : '释放更新' }}</text></view></template><!-- 列表内容 -->
</z-paging>

自定义空数据视图

<z-paging ref="paging" v-model="dataList" @query="queryList"><template #empty><view class="empty-view"><image src="/static/empty.png"></image><text>暂无数据</text><button @click="$refs.paging.reload()">重新加载</button></view></template><!-- 列表内容 -->
</z-paging>

聊天记录模式

<z-paging ref="paging" v-model="messageList" @query="queryMessageList" :use-chat-record-mode="true"><view class="chat-container"><view class="message-item" v-for="(item, index) in messageList" :key="index">{{ item.content }}</view></view>
</z-paging>