z-paging
工具活跃维护uni-app 高性能下拉刷新与上拉加载组件。支持全平台兼容(iOS、Android、鸿蒙Next、H5及各家小程序),vue&nvue、vue2&vue3、js&ts,使用 wxs+renderjs 实现高性能渲染,支持虚拟列表流畅渲染百万级数据。
★ 1,438🕒 最近更新 2026-07
开发工具分页下拉刷新上拉加载虚拟列表uni-app多端
特性
- 下拉刷新 + 上拉加载完整方案
- 虚拟列表,流畅渲染百万级数据
- 全平台兼容(H5/App/鸿蒙/各家小程序)
- vue & nvue 双支持,vue2 & vue3 双支持
- wxs + renderjs 高性能渲染
- 自定义下拉刷新动画与上拉加载样式
- 聊天分页模式(IM 聊天列表场景)
- 自动管理空数据图
- 吸顶效果与一键返回顶部
- 本地分页(无需网络请求)
- 国际化支持
- 主题模式切换
详细文档
z-paging — uni-app 高性能下拉刷新与上拉加载组件#
资源概述#
z-paging 是 uni-app 生态中最流行的分页解决方案,提供完整的下拉刷新、上拉加载更多功能。开发者仅需两步(绑定网络请求方法 + 绑定分页结果数组)即可完成完整分页逻辑,无需在页面中管理任何分页相关变量。
GitHub Stars: 1,438 · Forks: 100 · 语言: JavaScript · 许可证: MIT
核心特性#
- ✅ 配置极简:两步完成完整分页(绑定请求方法 + 绑定列表数组)
- ✅ 低耦合低侵入:分页由组件内部管理,页面无需定义分页变量
- ✅ 全平台兼容:H5、App(iOS/Android)、鸿蒙 Next、微信/支付宝/百度/抖音/QQ 等各家小程序
- ✅ 高性能:app-vue/h5/微信小程序/QQ 小程序上使用 wxs + renderjs 从视图层实现下拉刷新;支持虚拟列表,流畅渲染百万级列表
- ✅ 超灵活:支持自定义下拉刷新/上拉加载样式、全屏布局或自由容器、内置自动分页或手动处理
- ✅ 功能丰富:聊天分页模式、本地分页、国际化、主题切换、吸顶效果、最后更新时间、空数据图自动管理等
环境要求#
- uni-app 项目(支持 vue2/vue3、js/ts)
- HBuilderX 或 CLI 项目均可
设计规范#
分页架构#
z-paging 采用组件化封装 + 事件驱动的分页模式:
- @query 事件:组件自动触发(首次加载、下拉刷新、上拉触底),回调参数包含
pageNo和pageSize - :list 绑定:开发者请求到数据后,通过
this.$refs.paging.complete(data)完成数据注入,组件自动追加到列表 - 自动状态管理:组件内部维护
loading、finished、error、empty等状态,开发者无需关心
性能优化策略#
| 平台 | 渲染方案 | 说明 |
|---|---|---|
| App-Vue / H5 | renderjs | 视图层直接处理下拉刷新,避免跨线程通信 |
| 微信小程序 | wxs | 视图层响应手势,丝滑的下拉动画 |
| 其他小程序 | JS 模拟 | 使用 scroll-view + JS 监听滚动 |
虚拟列表#
z-paging 内置虚拟列表支持,对于大数据量列表(1万+条),仅渲染可视区域内的元素,大幅提升滚动性能:
<z-paging ref="paging" :virtual-list-col="2" @query="queryList">
<view v-for="item in dataList" :key="item.id">
{{ item.name }}
</view>
</z-paging>
审核规范#
z-paging 是纯前端 UI 组件,不涉及平台审核。组件编译产物为标准小程序代码,兼容各平台规范。
开发指南#
快速上手#
# 方式1: npm 安装
npm install z-paging
# 方式2: uni_modules 安装(推荐)
# 从 DCloud 插件市场导入:https://ext.dcloud.net.cn/plugin?name=z-paging
基础用法#
<template>
<z-paging ref="paging" @query="queryList">
<!-- 列表内容 -->
<view v-for="item in dataList" :key="item.id" class="item">
<text>{{ item.title }}</text>
<text class="desc">{{ item.description }}</text>
</view>
</z-paging>
</template>
<script>
export default {
data() {
return {
dataList: []
}
},
methods: {
// z-paging 自动调用此方法(首次加载、下拉刷新、上拉加载)
queryList(pageNo, pageSize) {
// 发起网络请求
uni.request({
url: 'https://api.example.com/list',
data: { page: pageNo, size: pageSize },
success: (res) => {
// 将请求结果传给 z-paging
this.$refs.paging.complete(res.data.list)
},
fail: () => {
// 请求失败处理
this.$refs.paging.complete(false)
}
})
}
}
}
</script>
自定义下拉刷新#
<template>
<z-paging
ref="paging"
:refresher-enable="true"
:custom-refresher="true"
@query="queryList"
>
<!-- 自定义下拉刷新视图 -->
<template #refresher="{ state }">
<view class="custom-refresher">
<text v-if="state === 0">下拉刷新</text>
<text v-if="state === 1">松开立即刷新</text>
<text v-if="state === 2">刷新中...</text>
</view>
</template>
<!-- 列表内容 -->
<view v-for="item in dataList" :key="item.id">
{{ item.name }}
</view>
</z-paging>
</template>
聊天分页模式#
<template>
<!-- 聊天模式:新消息插入顶部,自动滚动到底部 -->
<z-paging
ref="paging"
:use-chat-record-mode="true"
@query="queryList"
>
<view v-for="msg in chatList" :key="msg.id" class="chat-item">
<text>{{ msg.content }}</text>
</view>
</z-paging>
</template>
常见陷阱#
- complete() 必须调用:网络请求无论成功失败,必须调用
this.$refs.paging.complete()传回结果,否则组件会一直处于 loading 状态 - 请求失败传 false:请求失败时调用
this.$refs.paging.complete(false)可让组件显示错误提示并允许重试 - 虚拟列表 key 必填:使用虚拟列表时
v-for的:key必须是唯一且稳定的 ID,不能用 index - nvue 兼容性:nvue 模式下部分自定义动画效果受限,需查阅文档中的兼容性表格
- scroll-view 冲突:页面中如果有多个 scroll-view,需注意 z-paging 默认使用自身的滚动容器,避免嵌套滚动冲突
- pages.json 配置:如果使用页面原生下拉刷新(
enablePullDownRefresh: true),需要关闭 z-paging 的内置下拉刷新,避免冲突
生态资源#
配套框架#
- uni-app:z-paging 的唯一宿主框架
- Vue 2 / Vue 3:同时支持选项式 API 和组合式 API
- nvue:支持 App 端 weex 渲染
关联资源#
- uni-ui:DCloud 官方组件库,部分组件(如 uni-list)可与 z-paging 配合使用
- wot-design-uni / nutui-uniapp:第三方 UI 库的列表组件可与 z-paging 组合
社区#
- 官方文档:https://z-paging.zxlee.cn
- 在线 Demo:https://demo.z-paging.zxlee.cn
- DCloud 插件市场:https://ext.dcloud.net.cn/plugin?name=z-paging
- GitHub 仓库:https://github.com/SmileZXLee/uni-z-paging
- 官方 QQ 群:343409055
版本更新#
- 最后代码推送:2026-07-10(持续活跃)
- npm 版本数:74 个版本(自 2021 年持续迭代)
- 当前主要版本:2.8.8
- 近期方向:
- 鸿蒙 Next 平台适配
- 虚拟列表性能优化
- 更多自定义动画效果
- TypeScript 类型定义完善
- 维护状态:活跃维护中,作者持续响应 Issue 和 PR





