z-paging文档

# Methods

调用方式

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

注意

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

# 数据刷新&处理方法

方法名 说明 参数
reload 重新加载分页数据，pageNo恢复为默认值，相当于下拉刷新的效果

(触发reload后相关配置可查阅reload相关配置)

 参数1(非必填):(传true或false，默认为false)reload时是否展示下拉刷新动画，默认为否
2.5.3 返回值(return): Promise(resolve({totalList, noMore}), reject)获取本次操作请求结束后的【总列表】和【是否有更多数据】
refresh 2.0.4 刷新列表数据，pageNo和pageSize不会重置，列表数据会重新从服务端获取。

(必须保证@query绑定的方法中的pageNo和pageSize和传给服务端的一致)

 2.5.3 返回值(return):Promise(resolve({totalList, noMore}), reject)获取本次操作请求结束后的【总列表】和【是否有更多数据】
refreshToPage 2.5.9 刷新列表数据至指定页。

(必须保证@query绑定的方法中的pageNo和pageSize和传给服务端的一致)

 参数1(必填):目标页数，例如目标页数=5时则代表刷新列表至第5页，此时pageNo会变为5，列表会展示前5页的数据
2.5.3 返回值(return):Promise(resolve({totalList, noMore}), reject)获取本次操作请求结束后的【总列表】和【是否有更多数据】
complete 请求结束(成功或者失败)调用此方法，将请求的结果传递给z-paging处理，会自动判断是否有更多数据(当通过complete传进去的数组长度小于pageSize时，则判定为没有更多了)。

(全局错误处理：当请求失败时，也必须调用complete，可在封装的全局网络请求错误的地方书写：uni.$emit('z-paging-error-emit','请求失败原因(可选，v2.6.3之后支持)'); 即可将当前加载中状态的z-paging设置为请求失败状态，无需在每个页面中写this.$refs.paging.complete(false))

2.1.9(全局complete：当请求成功时，可在封装的全局网络请求成功的地方书写：uni.$emit('z-paging-complete-emit',请求结果数组); 则无需在每个页面中写this.$refs.paging.complete(请求结果数组))。对于下方的completeByXXX，需使用uni.$emit('z-paging-complete-emit',{type:xxx,list:请求结果数组,rule:对应方法completeByXXX中参数2的值});，例如，需要全局表示completeByTotal则写法为uni.$emit('z-paging-complete-emit',{type:'total',list:请求结果数组,rule:total的值})。附type枚举值：'total'、'nomore'、'key'。
ps：若当前页面(组件示例)中调用了z-paging的complete及相关方法，则当次全局complete将失效，以避免重复添加数据的问题

(特别注意：全局emit的规则为：当z-paging接收到错误或完成的全局emit事件时，若当前状态为"加载中"，则处理对应的错误或完成事件。因此若您的项目可能存在多个z-paging实例同时处于"加载中"状态，不建议使用全局emit处理，否则将可能导致数据错乱！)

 参数1(必填):请求结果数组；
参数2(非必填):是否请求成功，不填默认为true。

请求失败时直接调用：this.$refs.paging.complete(false); 即可；如果只是想表达请求结束，则调用：this.$refs.paging.complete(); 即可


2.5.3 返回值(return): Promise(resolve({totalList, noMore}), reject)获取本次操作请求结束后的【总列表】和【是否有更多数据】
completeByTotal 2.0.6 【通过total判断是否有更多数据】请求结束(成功或者失败)调用此方法，将请求的结果传递给z-paging处理

(将此方法替换complete方法即可，此方法为complete方法的功能扩展，遵循complete原有规则)

 参数1(必填):请求结果数组；
参数2(必填):total(列表总长度)
参数3(非必填):是否请求成功，不填默认为true
2.5.3 返回值(return): Promise(resolve({totalList, noMore}), reject)获取本次操作请求结束后的【总列表】和【是否有更多数据】
completeByNoMore 1.9.2 【自行判断是否有更多数据】请求结束(成功或者失败)调用此方法，将请求的结果传递给z-paging处理

(将此方法替换complete方法即可，此方法为complete方法的功能扩展，遵循complete原有规则)

 参数1(必填):请求结果数组；
参数2(必填):是否没有更多数据，若为true则代表没有更多数据了(v2.5.1之前的版本与此相反)
参数3(非必填):是否请求成功，不填默认为true
2.5.3 返回值(return): Promise(resolve({totalList, noMore}), reject)获取本次操作请求结束后的【总列表】和【是否有更多数据】
completeByError 2.6.3 【通过方法传入请求失败原因】请求失败调用此方法，将请求失败原因传递给z-paging展示

(将此方法替换complete(false)方法即可，此方法为complete(false)方法的功能扩展，遵循complete(false)原有规则)

 参数1(必填):请求失败原因；
返回值(return): Promise(resolve({totalList, noMore}), reject)获取本次操作请求结束后的【总列表】和【是否有更多数据】
completeByKey 1.6.4 【保证数据一致】请求结束(成功或者失败)调用此方法，将请求的结果传递给z-paging处理

(关于数据一致性，请查看demo中consistency-demo.vue文件)

(将此方法替换complete方法即可，此方法为complete方法的功能扩展，遵循complete原有规则)

 参数1(必填):请求结果数组；
参数2(必填):dataKey，需与:data-key绑定的一致；
参数3(非必填):是否请求成功，不填默认为true
2.5.3 返回值(return): Promise(resolve({totalList, noMore}), reject)获取本次操作请求结束后的【总列表】和【是否有更多数据】
clear 2.1.0 清空分页数据，pageNo恢复为默认值。 -
addDataFromTop 从顶部添加数据，不会影响分页的pageNo和pageSize 参数1(必填):需要添加的数据，可以是一条数据或一组数据；
参数2(非必填):是否滚动到顶部，不填默认为true；
参数3(非必填):是否使用动画滚动到顶部，不填默认为true
resetTotalData 不推荐

(建议使用v-model代替:list.sync，则无需调用此方法)

重新设置列表数据，调用此方法不会影响pageNo和pageSize，也不会触发请求。适用场景：当需要删除列表中某一项时，将删除对应项后的数组通过此方法传递给z-paging。		 参数1(必填):修改后的列表数组

# 下拉刷新相关方法

方法名 说明 参数
endRefresh 2.1.0 终止下拉刷新状态 -
updateCustomRefresherHeight 2.6.1 手动更新自定义下拉刷新view高度，常用于某些情况下使用slot="refresher"插入的view高度未能正确计算导致异常时手动更新其高度 -

# 底部加载更多相关方法

方法名 说明 参数
doLoadMore 手动触发上拉加载更多(非必须，可依据具体需求使用，例如当z-paging未确定高度时，内部的scroll-view会无限增高，此时z-paging无法得知是否滚动到底部，您可以在页面的onReachBottom中手动调用此方法触发上拉加载更多) 2.3.0 参数1(非必填):触发加载更多的来源类型，有click和toBottom两种类型，分别代表由点击事件触发和由滚动到底部触发，默认为click

# 页面滚动&布局相关方法

方法名 说明 参数
updatePageScrollTop 当使用页面滚动并且自定义下拉刷新时，请在页面的onPageScroll中调用此方法，告知z-paging当前的pageScrollTop，否则会导致在任意位置都可以下拉刷新(若引入了mixins，则不需要调用此方法) 参数1(必填):从page的onPageScroll中获取的scrollTop
updatePageScrollTopHeight 在使用页面滚动并且设置了slot="top"时，默认初次加载会自动获取其高度，并使内部容器下移，当slot="top"的view高度动态改变时，在其高度需要更新时调用此方法 -
updatePageScrollBottomHeight 在使用页面滚动并且设置了slot="bottom"时，默认初次加载会自动获取其高度，并使内部容器下移，当slot="bottom"的view高度动态改变时，在其高度需要更新时调用此方法 -
updateLeftAndRightWidth 2.3.5 更新slot="left"和slot="right"宽度，当slot="left"或slot="right"宽度动态改变后调用
updateFixedLayout 2.6.5 更新fixed模式下z-paging的布局，在onShow时候调用，以修复在iOS+h5+tabbar+fixed+底部有安全区域的设备中从tabbar页面跳转到无tabbar页面后返回，底部有一段空白区域的问题 -

# 虚拟列表相关方法

方法名 说明 参数
doInsertVirtualListItem 2.5.9 在使用动态高度虚拟列表时，若在列表数组中需要插入某个item，需要调用此方法 参数1(必填):插入的数据项
参数2(必填):插入的cell位置，若为2，则插入的item在原list的index=1之后，从0开始
didUpdateVirtualListCell 2.4.0 在使用动态高度虚拟列表时，手动更新指定cell的缓存高度(当cell高度在初始化之后再次改变时调用) 参数1(必填):需要更新的cell在列表中的位置，从0开始
didDeleteVirtualListCell 2.4.0 在使用动态高度虚拟列表时，若删除了列表数组中的某个item，需要调用此方法以更新高度缓存数组 参数1(必填):需要更新的cell在列表中的位置，从0开始

# 本地分页相关方法

方法名 说明 参数
setLocalPaging 设置本地分页，请求结束(成功或者失败)调用此方法，将请求的结果传递给z-paging作分页处理

（若调用了此方法，则上拉加载更多时内部会自动分页，不会触发@query所绑定的事件）

 参数1(必填):请求结果数组；
参数2(非必填):是否请求成功，不填默认为true
2.5.3 返回值(return): Promise(resolve({totalList, noMore}), reject)获取本次操作请求结束后的【总列表】和【是否有更多数据】ps：仅从服务端获取数据时候触发；本地分页时不会触发此promise

# 聊天记录模式相关方法

方法名 说明 参数
doChatRecordLoadMore 手动触发滚动到顶部加载更多，聊天记录模式时有效 -
addChatRecordData 添加聊天记录，use-chat-record-mode为true时有效 参数1(必填):需要添加的聊天数据，可以是一条数据或一组数据；
参数2(非必填):是否滚动到底部，不填默认为true；
参数3(非必填):是否使用动画滚动到底部，不填默认为true

# 滚动到指定位置方法

方法名 说明 参数
scrollToTop 滚动到顶部 参数1(非必填):是否有动画效果，默认为是
scrollToBottom 滚动到底部 参数1(非必填):是否有动画效果，默认为是
scrollIntoViewById 滚动到指定view

(vue中有效，若此方法无效，请使用scrollIntoViewByNodeTop)

 参数1(必填)需要滚动到的view的id值，不包含"#"；
参数2(非必填):偏移量，单位为px，默认为0；
参数3(非必填):是否有动画效果，默认为否
scrollIntoViewByNodeTop 1.7.4 滚动到指定view

(vue中有效)

 参数1(必填):需要滚动的view的top值(通过uni.createSelectorQuery()获取)；
参数2(非必填):偏移量，单位为px，默认为0；
参数3(非必填):是否有动画效果，默认为否
scrollToY 2.1.0 滚动到指定view(与scrollIntoViewByNodeTop的不同之处在于，scrollToY传入的是view相对于屏幕的top值，而scrollIntoViewByNodeTop传入的top值并非是固定的，通过uni.createSelectorQuery()获取到的top会因列表滚动而改变)

(vue中有效)

 参数1(必填):需要滚动到的view的top值，单位为px；
参数2(非必填):偏移量，单位为px，默认为0；
参数3(非必填):是否有动画效果，默认为否
scrollIntoViewByIndex 滚动到指定view

(nvue中有效)(在nvue中的cell必须设置 :ref="`z-paging-${index}`")

 参数1(必填):需要滚动到的view的index(第几个)；
参数2(非必填):偏移量，单位为px，默认为0；
参数3(非必填):是否有动画效果，默认为否
scrollIntoViewByView 滚动到指定view

(nvue中有效)

 参数1(必填):需要滚动到的view(通过this.$refs.xxx获取)；
参数2(非必填):偏移量，单位为px，默认为0；
参数3(非必填):是否有动画效果，默认为否

# nvue独有方法

方法名 说明 参数
setListSpecialEffects或
setSpecialEffects 2.0.4		 设置nvue List的specialEffects 参数1(必填):参见https://uniapp.dcloud.io/component/list?id=listsetspecialeffects (opens new window)

# 缓存相关方法

方法名 说明 参数
updateCache 2.3.9 手动更新列表缓存数据，将自动截取v-model绑定的list中的前pageSize条覆盖缓存，请确保在list数据更新到预期结果后再调用此方法 -

# 获取版本号方法

方法名 说明 参数
getVersion 获取当前版本号 -

← Events →