▶_MiniApp Toolkit

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 事件:组件自动触发(首次加载、下拉刷新、上拉触底),回调参数包含 pageNopageSize
  • :list 绑定:开发者请求到数据后,通过 this.$refs.paging.complete(data) 完成数据注入,组件自动追加到列表
  • 自动状态管理:组件内部维护 loadingfinishederrorempty 等状态,开发者无需关心

性能优化策略#

平台渲染方案说明
App-Vue / H5renderjs视图层直接处理下拉刷新,避免跨线程通信
微信小程序wxs视图层响应手势,丝滑的下拉动画
其他小程序JS 模拟使用 scroll-view + JS 监听滚动

虚拟列表#

z-paging 内置虚拟列表支持,对于大数据量列表(1万+条),仅渲染可视区域内的元素,大幅提升滚动性能:

code
<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 组件,不涉及平台审核。组件编译产物为标准小程序代码,兼容各平台规范。

开发指南#

快速上手#

code
# 方式1: npm 安装
npm install z-paging

# 方式2: uni_modules 安装(推荐)
# 从 DCloud 插件市场导入:https://ext.dcloud.net.cn/plugin?name=z-paging

基础用法#

code
<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>

自定义下拉刷新#

code
<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>

聊天分页模式#

code
<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>

常见陷阱#

  1. complete() 必须调用:网络请求无论成功失败,必须调用 this.$refs.paging.complete() 传回结果,否则组件会一直处于 loading 状态
  2. 请求失败传 false:请求失败时调用 this.$refs.paging.complete(false) 可让组件显示错误提示并允许重试
  3. 虚拟列表 key 必填:使用虚拟列表时 v-for:key 必须是唯一且稳定的 ID,不能用 index
  4. nvue 兼容性:nvue 模式下部分自定义动画效果受限,需查阅文档中的兼容性表格
  5. scroll-view 冲突:页面中如果有多个 scroll-view,需注意 z-paging 默认使用自身的滚动容器,避免嵌套滚动冲突
  6. 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 组合

社区#

版本更新#

  • 最后代码推送:2026-07-10(持续活跃)
  • npm 版本数:74 个版本(自 2021 年持续迭代)
  • 当前主要版本:2.8.8
  • 近期方向
    • 鸿蒙 Next 平台适配
    • 虚拟列表性能优化
    • 更多自定义动画效果
    • TypeScript 类型定义完善
  • 维护状态:活跃维护中,作者持续响应 Issue 和 PR

支持平台