更新记录

1.5.1（2021-04-21）

1.新增自动显示点击返回顶部按钮
2.优化下拉刷新细节

1.5.0（2021-04-20）

1.在App-vue、微信小程序、QQ小程序、h5中使用wxs实现自定义下拉刷新，减少视图层与逻辑层通信折损，大幅提升性能。
2.简化自定义下拉刷新view的配置步骤，在page的data中无需定义一个过渡的refresherStatus变量，减少耦合。
3.修复在支付宝小程序、字节跳动小程序中的兼容问题。
4.修复在调用 scrollToBottom或者scrollIntoViewById方法后，下拉刷新无效的问题。
5.修复empty插槽页面加载后，网络请求前展示，导致闪一下的问题。
6.其他细节优化及调整。

平台兼容性

z-paging

【uni-app自动分页器】超简单，低耦合！仅需两步轻松完成完整分页逻辑(下拉刷新、上拉加载更多)，分页全自动处理。支持自定义加载更多的文字或整个view，自定义下拉刷新样式，自动管理空数据view，支持吸顶效果等。

功能&特点

• 【配置简单】仅需两步（绑定网络请求方法、绑定分页结果数组）轻松完成完整下拉刷新，上拉加载更多功能。
• 【低耦合，低侵入】分页自动管理。在page中无需处理任何分页相关逻辑，无需在data中定义任何分页相关变量，全由z-paging内部处理。
• 【超灵活，支持各种类型自定义】支持自定义下拉刷新，自定义上拉加载更多，自带自定义下拉刷新效果，及其他数十种自定义属性。
• 【功能丰富】支持自定义且自动管理空数据图，支持主题模式切换，支持本地分页，支持聊天分页模式，支持吸顶效果，支持内部scroll-view滚动与页面滚动，支持一键滚动到顶部等诸多功能。
• 【多平台兼容，细致，流畅】支持nvue，支持h5、app及各家小程序；在app-vue、h5、微信小程序上使用wxs实现下拉刷新，多处细节优化，给您精致流畅的体验。

反馈qq群(点击加群)：790460711

关于自动引入组件

z-paging 支持easycom组件规范，无需引用和注册组件即可直接使用，在正在运行的项目中导入z-paging可能会提示：Unknown custom element：<z-paging> - did you register the component corrently?...，此时需要重新运行项目即可。

平台兼容性

预览

自定义下拉刷新效果+分页演示	吸顶效果+分页演示

滑动切换选项卡+分页演示	聊天记录模式+分页演示

在线demo体验地址：

• http://www.zxlee.cn/github/uni-z-paging/demo/index.html

扫码体验

此组件已支持uni_modules，下载完整示例时组件在uni_modules目录下。

基本使用

• ①在<template> 中使用@query绑定js中分页请求的方法(z-paging会将计算好的pageNo和pageSize两个参数传递到此方法中)，然后通过:list.sync绑定列表for循环的list。
• ②在请求结果回调中，通过调用z-paging的complete()方法，将请求返回的数组传递给z-paging处理，如：this.$refs.paging.complete(服务器返回的数组);；若请求失败，调用：this.$refs.paging.complete(false);即可。
• 当tab切换或搜索时，可以通过this.$refs.paging.reload()刷新整个列表。

性能与建议

【总结】

• 如果项目列表item比较简单，分页数据量不是特别多，建议使用默认的「内置scroll-view滚动」。
• 如果项目列表item比较复杂，数据量多，且使用「内置scroll-view滚动」时卡顿明显，建议使用页面滚动。
• 如果是App项目，且对性能和细节有较高要求，建议在nvue中使用z-paging。

注意事项及常见问题

• 【使用内置scroll-view滚动时】z-paging必须有确定的高度！否则上拉加载更多将无法触发，请确保z-paging的所有父view有确定的高度！！
• 【使用内置scroll-view滚动时】请确保z-paging与同级的其他view的总高度不得超过屏幕宽度，以避免超出屏幕高度时页面的滚动与z-paging内部的滚动冲突，计算z-paging高度比较麻烦时，建议通过flex:1给z-paging设置样式，其父view需要开启flex。
• 【使用内置scroll-view滚动时】如果设置了z-paging的height为100%（让z-paging的高度等于当前页面有效高度），则它的父view高度也必须为100%(或者其他确定的高度)，若z-paging的所有父节点高度都为100%，则同时也必须设置page{height:100%}才有效果，page{height:100%}建议写在App.vue中。(因为page默认没有确定的高度，如果page未设置确定的高度，则其内部的所有view设置height:100%都是无效的，因为未设置确定高度则代表着这个view会无限长高，因此子view即使设置了height:100%，也同样是无限长高，无法限制其高度小于或等于当前页面有效的高度)。
• 【使用页面滚动时】使用z-paging内置的scroll-view滚动性能不及使用页面的滚动。若您要使用页面的滚动，请勿固定z-paging的高度，并且必须设置use-page-scroll为true，否则将导致页面无法滚动。
• 【使用横向滑动切换tab时】z-paging默认会禁止所有touchmove事件冒泡以避免下拉刷新冲突，这将导致使用滑动切换tab时无法横向切换，若您需要横向切换功能，请设置touchmove-propagation-enabled为true以允许冒泡；若此时下拉刷新是页面也跟着下拉，需要在pages.json中设置页面的"disableScroll":true或在page的根节点中添加@touchmove.stop.prevent，详情可查看demo。
• 【出现实际上有更多数据，而显示没有更多数据时】默认的pageSize(每页显示数量)为10，如果您服务端不需要传pageSize(例如有默认的pageSize：8)，则您需要将默认的pageSize改成您与后端约定好的（8），若没有修改，则z-paging会认为传给服务端的pageSize是10，而服务端只返回了8条，因此会直接判定为没有更多数据。
• 【若页面无法滚动】请检查z-paging是否有固定的高度；若您想使用页面滚动而非z-paging内置的scroll-view的滚动，请设置use-page-scroll为true。

<template>
    <view class="content">
        <z-paging ref="paging" @query="queryList" :list.sync="dataList">
            <!-- list数据，建议像下方这样在item外层套一个view，而非直接for循环item，因为slot插入有数量限制 -->
            <view>
                <view class="item" v-for="(item,index) in dataList">
                    <view class="item-title">{{item.title}}</view>
                </view>
            </view>
        </z-paging>
    </view>
</template>


    export default {
        data() {
            return {
                dataList: [],
            };
        },
        methods: {
            queryList(pageNo, pageSize) {
                //这里的pageNo和pageSize会自动计算好，直接传给服务器即可
                //这里的请求只是演示，请替换成自己的项目的网络请求，请在网络请求回调中
                //通过this.$refs.paging.complete(请求回来的数组);将请求结果传给z-paging
                this.$request.queryList(pageNo, pageSize, (data) => {
                    this.$refs.paging.complete(data);
                });
            },
        },
    };


<style scoped>
    /* 注意，父元素需要固定高度，z-paging的height:100%才会生效 */
    page {
        height: 100%;
    }
    .content {
        height: 100%;
    }
</style>

设置自定义emptyView组件

• 设置自定义emptyView组件，非必须。空数据时会自动展示空数据组件，不需要自己处理

<z-paging ref="paging" @query="queryList" :list.sync="dataList">
    <!-- 设置自己的emptyView组件，非必须。空数据时会自动展示空数据组件，不需要自己处理 -->
    <empty-view slot="empty"></empty-view>

    <view>
        <view class="item" v-for="(item,index) in dataList">
            <view class="item-title">{{item.title}}</view>
        </view>
    </view>
</z-paging>

自定义加载更多各个状态的描述文字

• 以修改【没有更多了】状态描述文字为例(将默认的"没有更多了"修改为"我也是有底线的！")

<z-paging ref="paging" loading-more-no-more-text="我也是有底线的！" @query="queryList" :list.sync="dataList">
    <!-- 设置自己的emptyView组件，非必须。空数据时会自动展示空数据组件，不需要自己处理 -->
    <empty-view slot="empty"></empty-view>

    <view>
        <view class="item" v-for="(item,index) in dataList">
            <view class="item-title">{{item.title}}</view>
        </view>
    </view>
</z-paging>

自定义下拉刷新view

• use-custom-refresher需要设置为true(默认为true)，此时将不会使用uni自带的下拉刷新，转为使用z-paging自定义的下拉刷新，通过slot可以插入开发者自定义的下拉刷新view。

<z-paging ref="paging" :refresher-threshold="80" :use-custom-refresher="true" @query="queryList" :list.sync="dataList" :refresher-status.sync="refresherStatus">
  <!-- 自定义下拉刷新view，若不设置，则使用z-paging自带的下拉刷新view -->
  <custom-refresher slot="refresher" :status="refresherStatus"></custom-refresher>
  <!-- 设置自定义emptyView组件，非必须。空数据时会自动展示空数据组件，不需要自己处理 -->
  <empty-view slot="empty"></empty-view>
  <!-- list数据，建议像下方这样在item外层套一个view，而非直接for循环item，因为slot插入有数量限制 -->
  <view>
    <view class="item" v-for="(item,index) in dataList" @click="itemClick(item)">
      <view class="item-title">{{item.title}}</view>
      <view class="item-detail">{{item.detail}}</view>
      <view class="item-line"></view>
    </view>
  </view>
</z-paging>

自定义加载更多各个状态的描述view

• 以修改【没有更多了】状态描述view为例

<z-paging ref="paging" @query="queryList" :list.sync="dataList">
    <view>
        <view class="item" v-for="(item,index) in dataList">
            <view class="item-title">{{item.title}}</view>
        </view>
    </view>
    <view style="background-color: red" slot="loadingMoreNoMore">这是完全自定义的没有更多数据view</view>
</z-paging

API

Props

Slot

Events

• 监听组件方法(自定义扩展，一般无需使用)

• 主动调用组件方法 (假设给z-paging设置ref="paging"，则通过this.$refs.paging.xxx()方式调用)

  注意：在Page的onLoad()方法中无法同步获取this.$refs，请加一个setTimeOut延时1毫秒或nextTick再调用(默认会在页面加载时自动调用reload()无须手动调用)