# 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不会重置,列表数据会重新从服务端获取。 (调用此方法时会自动触发queryList,假设此时已经分页请求到了第5页,则这次请求的pageNo = 1,pageSize = 50。因为此方法是刷新前面所有已加载的列表数据,也就是前50条的数据。刷新完成后继续滚动到底部,此时pageNo会继续累加,也就是从6开始) (必须保证@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,可在封装的全局网络请求错误的地方书写: 2.1.9(全局complete:当请求成功时,可在封装的全局网络请求成功的地方书写: (特别注意:全局emit的规则为:当z-paging接收到错误或完成的全局emit事件时,若当前状态为"加载中",则处理对应的错误或完成事件。因此若您的项目可能存在多个z-paging实例同时处于"加载中"状态,不建议使用全局emit处理,否则将可能导致数据错乱!) | 参数1(必填) :请求结果数组;参数2(非必填) :是否请求成功,不填默认为true。请求失败时直接调用: 2.5.3 返回值(return) : Promise(resolve({totalList, noMore}), reject) 获取本次操作请求结束后的【总列表】和【是否没有更多数据】 |
completeByTotal 2.0.6 | 【通过total判断是否有更多数据】请求结束(成功或者失败)调用此方法,将请求的结果传递给z-paging处理 (将此方法替换 | 参数1(必填) :请求结果数组;参数2(必填) :total(列表总长度)参数3(非必填) :是否请求成功,不填默认为true2.5.3 返回值(return) : Promise(resolve({totalList, noMore}), reject) 获取本次操作请求结束后的【总列表】和【是否没有更多数据】 |
completeByNoMore 1.9.2 | 【自行判断是否有更多数据】请求结束(成功或者失败)调用此方法,将请求的结果传递给z-paging处理 (将此方法替换 | 参数1(必填) :请求结果数组;参数2(必填) :是否没有更多数据,若为true则代表没有更多数据了(v2.5.1 之前的版本与此相反)参数3(非必填) :是否请求成功,不填默认为true2.5.3 返回值(return) : Promise(resolve({totalList, noMore}), reject) 获取本次操作请求结束后的【总列表】和【是否没有更多数据】 |
completeByError 2.6.3 | 【通过方法传入请求失败原因】请求失败调用此方法,将请求失败原因传递给z-paging展示 (将此方法替换 | 参数1(必填) :请求失败原因;返回值(return) : Promise(resolve({totalList, noMore}), reject) 获取本次操作请求结束后的【总列表】和【是否没有更多数据】 |
completeByKey 1.6.4 | 【保证数据一致】请求结束(成功或者失败)调用此方法,将请求的结果传递给z-paging处理 (关于数据一致性,请查看demo中 (将此方法替换 | 参数1(必填) :请求结果数组;参数2(必填) :dataKey,需与:data-key绑定的一致;参数3(非必填) :是否请求成功,不填默认为true2.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高度未能正确计算导致异常时手动更新其高度 | - |
closeF2 2.7.7 | 手动关闭二楼 | - |
# 底部加载更多相关方法
方法名 | 说明 | 参数 |
---|---|---|
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开始 |
updateVirtualListRender 2.7.11 | 手动触发虚拟列表渲染更新,可用于解决例如修改了虚拟列表数组中元素,但展示未更新的情况 | - |
# 本地分页相关方法
方法名 | 说明 | 参数 |
---|---|---|
setLocalPaging | 设置本地分页,请求结束(成功或者失败)调用此方法,将请求的结果传递给z-paging作分页处理 (若调用了此方法,则上拉加载更多时内部会自动分页,不会触发@query所绑定的事件) | 参数1(必填) :请求结果数组;参数2(非必填) :是否请求成功,不填默认为true2.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中有效,若此方法无效,请使用 | 参数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或虚拟列表2.7.8中有效)(在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 | 获取当前版本号 | - |