# Events

# 数据处理相关事件

事件名 说明 回调参数
@query 下拉刷新或滚动到底部时会自动触发此方法。z-paging加载时也会触发(若要禁止,请设置:auto="false")。pageNo和pageSize会自动计算好,直接传给服务器即可。 参数1:pageNo(当前第几页);
参数2:pageSize(每页多少条)(pageSize必须与传给服务器的一致,如果需要修改pageSize,请通过:default-page-size="15"修改)
参数3 2.1.4:from(@query的触发来源:user-pull-down:用户主动下拉刷新;reload:通过reload触发;refresh:通过refresh触发;load-more:通过滚动到底部加载更多或点击底部加载更多触发)(v2.8.0及之前的版本的from是number类型,对应为:0,1,2,3)
@listChange 分页渲染的数组改变时触发 最终的分页数据数组

# 下拉刷新相关事件

事件名 说明 回调参数
@refresherStatusChange 自定义下拉刷新状态改变

(use-custom-refresher为false时无效)

【注:通过:refresher-status.sync绑定当前data中的指定变量亦可】
default:默认状态;
release-to-refresh:松手立即刷新;
loading:刷新中;
complete:刷新结束(默认情况下看不到此状态,如果需要展示刷新成功状态,请设置刷新结束以后延时收回的时间,如::refresher-complete-delay="200");
go-f2:松手进入二楼
(v2.8.0及之前的版本是number类型,对应为:0,1,2,3,4)
@refresherTouchstart 自定义下拉刷新下拉开始

(use-custom-refresher为false时无效)

【注:当需要更细致定制自定义下拉刷新时使用,如果只需监听下拉刷新各个状态改变,使用refresherStatusChange即可】

(nvue无效)

当前触摸开始的屏幕点的y值(单位px)
@refresherTouchmove 自定义下拉刷新下拉拖动中

(use-custom-refresher为false时无效)

【注:在使用wxs的平台上(微信小程序、QQ小程序、app-vue、h5),为减少wxs与js通信折损,此事件默认不触发,必须设置:watch-refresher-touchmove="true"方可使此事件被触发】
{pullingDistance: 下拉的距离, dy: 前后两次回调滑动距离的差值, viewHeight: refresh组件高度, rate:pullingDistance/viewHeight的比值}
@refresherTouchend 自定义下拉刷新下拉结束

(use-custom-refresher为false时无效)

【注:当需要更细致定制自定义下拉刷新时使用,如果只需监听下拉刷新各个状态改变,使用refresherStatusChange即可】

(nvue无效)

当前触摸结束分页内容下移的y值(单位px)
@refresherF2Change 2.7.7 下拉进入二楼状态改变 go-二楼开启 close-二楼关闭
@onRefresh 自定义下拉刷新被触发 -
@onRestore 自定义下拉刷新被复位 -

# 底部加载更多相关事件

事件名 说明 回调参数
@loadingStatusChange 底部加载更多状态改变 default:默认状态;
loading:加载中;
no-more:没有更多数据;
fail:加载失败
(v2.8.0及之前的版本是number类型,对应为:0,1,2,3)

# 空数据与加载失败相关事件

事件名 说明 回调参数
@emptyViewReload 1.8.0 点击了空数据图中的重新加载按钮 点击重新加载后是否进行reload操作,默认为是。
如果需要禁止reload事件,则在page的methods中书写:

emptyViewReload(e) {
    e(false);
    //处理自己的业务逻辑
}

@emptyViewClick 2.3.3 点击了空数据图view -
@isLoadFailedChange 2.5.0 z-paging请求失败状态改变 当前是否是请求失败状态,为true代表是,反之为否;默认状态为否

# 返回顶部按钮相关事件

事件名 说明 回调参数
@backToTopClick 2.6.1 点击了返回顶部按钮 点击返回顶部按钮后是否滚动到顶部,默认为是。
如果需要禁止滚动到顶部事件,则在page的methods中书写:

backToTopClick(e) {
    e(false);
    //处理自己的业务逻辑
}

# 虚拟列表&内置列表相关事件

事件名 说明 回调参数
@virtualListChange 2.2.7 虚拟列表当前渲染的数组改变时触发,在虚拟列表中只会渲染可见区域内+预加载页面的数据

(nvue无效)

虚拟列表当前渲染的数组
@innerCellClick 2.4.0 使用虚拟列表或内置列表时点击了cell

(nvue无效)

参数1:item;
参数2:index
@virtualPlaceholderTopHeight 2.7.12 虚拟列表顶部占位高度改变 虚拟列表顶部占位高度(单位:px)

# 聊天记录模式相关事件

事件名 说明 回调参数
@hidedKeyboard 2.3.6 在聊天记录模式下,触摸列表隐藏了键盘

(nvue无效)

-
@keyboardHeightChange 2.7.1 键盘高度改变

(聊天记录模式启用时才有效,如果在聊天记录模式页面需要监听键盘高度改变,请不要直接通过uni.onKeyboardHeightChange监听,否则可能导致z-paging内置的键盘高度改变监听失效。ps:H5、百度小程序、抖音小程序、飞书小程序不支持)

{height:0(键盘高度)}

# 滚动相关事件

事件名 说明 回调参数
@scroll z-paging列表滚动时触发

(此事件忠实地转发了scroll-view/list@scroll数据,此方法受内部节流影响可能无法100%监听到滚动到顶部和底部事件,若有相关需求请结合@scrolltoupper@scrolltolower综合判断,上述2个事件触发z-paging单独进行了进一步更严谨的判断)

(vue中) event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY}
(nvue中) event = {contentSize(列表的内容尺寸) = {width, height}, contentOffset(列表的偏移尺寸) = {x, y} , isDragging(用户是否正在拖动列表)}
@scrollTopChange scrollTop改变时触发,使用点击返回顶部时需要获取scrollTop时可使用此事件【注:通过:scroll-top.sync绑定当前data中的指定变量亦可】

(@scrolltoupper触发时,也会自动触发此方法,且scrollTop=0)

scrollTop
@scrolltolower z-paging内置的scroll-view滚动底部时触发 来源(toBottom滚动到底部;click点击了加载更多view)
@scrolltoupper z-paging内置的scroll-view滚动顶部时触发 -
@scrollend 2.7.3 z-paging内置的list滚动结束时触发

(仅nvue有效)

event = {contentSize(列表的内容尺寸) = {width, height}, contentOffset(列表的偏移尺寸) = {x, y} , isDragging(用户是否正在拖动列表)}

# 布局&交互相关事件

事件名 说明 回调参数
@contentHeightChanged 2.1.3 z-paging中内容高度改变时触发 改变后的高度
@touchDirectionChange 2.3.0 监听列表触摸方向改变

(nvue无效)

(必须同时设置:watch-touch-direction-change="true")

列表触摸的方向,有topbottom两种值,top代表用户将列表向上移动(scrollTop不断减小),bottom代表用户将列表向下移动(scrollTop不断增大)