更新记录

1.0.1（2026-09-14） 下载此版本

1.新增 适配蒸汽模式(Vapor)：全局配置setZPXConfig在蒸汽模式下生效；空数据图在蒸汽模式及web端正确铺满居中；修复蒸汽模式下下拉刷新箭头与loading动画失效的问题；移除蒸汽模式已废弃的rebound、custom-nested-scroll、space等属性的使用。
2.新增 聊天记录模式：props：use-chat-record-mode、auto-hide-keyboard-when-chat、auto-adjust-position-when-chat、chat-adjust-position-offset、auto-to-bottom-when-chat、show-chat-loading-when-reload、chat-loading-more-default-as-loading；方法：addChatRecordData、doChatRecordLoadMore；events：@cellStyleChange、@keyboardHeightChange、@hidedKeyboard；slots：chatLoading、chatNoMore。
3.新增 props：default-theme-style、refresher-theme-style、loading-more-theme-style，支持black、white主题。
4.新增 props：refresher-default-img、refresher-pulling-img、refresher-refreshing-img、refresher-complete-img、refresher-refreshing-animated，支持自定义下拉刷新各状态图片。
5.新增 props：refresher-img-style、refresher-title-style、refresher-update-time-style，支持自定义下拉刷新图标及文字样式。
6.新增 props：safe-area-inset-bottom、bottom-bg-color，支持底部安全区域适配及slot="bottom"容器背景色。
7.新增 props：associative-container，蒸汽模式下用于替代custom-nested-scroll与外层滚动容器开启嵌套模式。
8.新增 下拉进入二楼：props：refresher-f2-enabled、refresher-f2-threshold、refresher-f2-duration、show-refresher-f2、refresher-go-f2-text；方法：goF2、closeF2；events：@refresherF2Change；slots：f2、refresherF2。
9.新增 demo：chat-demo聊天记录模式演示、f2-demo下拉进入二楼演示。
10.优化 下拉刷新箭头、成功图标及loading改为svg绘制，颜色随主题变化。
11.优化 demo全部改为组合式API写法，移除common-setup-demo。
12.优化 底部加载更多在没有内容时不再渲染，修复web端列表底部多出空白的问题。
13.优化 事件@refresh与@onRefresh等价，修复蒸汽模式下事件名大小写警告。

0.4.0（2026-06-11） 下载此版本

1.新增 props：refresher-complete-text、refresher-complete-delay、refresher-complete-duration，支持下拉刷新结束状态(complete状态)。
2.新增 props：layout-only，是否只使用基础布局，设置为true后将关闭mounted自动请求数据、关闭下拉刷新和滚动到底部加载更多，强制隐藏空数据图。
3.新增 方法：refresh，刷新列表数据，pageNo和pageSize不会重置，列表数据会重新从服务端获取。
4.新增 方法：endRefresh，直接结束下拉刷新状态。
5.新增 events：@onRefresh，自定义下拉刷新被触发。
6.新增 demo：common-setup-demo，普通模式演示(组合式API写法)。
7.优化 props注释统一为JSDoc格式。

0.3.6（2025-08-07） 下载此版本

1.新增 添加编译到鸿蒙Next的支持。
2.新增 @query新增from(触发来源)参数。
3.新增 slot=loading加载中插槽。
4.修复 在部分安卓平台数据为空时可能出现的Java数组越界的报错。
5.修复 在iOS平台下拉刷新箭头未变化的问题。
6.修复 refresherEnabled=false时下拉刷新报错的问题。
7.优化 修改下拉刷新和底部加载更多状态枚举类型为字符串类型。
8.优化 下拉刷新显示最后更新时间高度判断逻辑。

平台兼容性

uni-app x(5.0)

其他

z-paging-x

请注意，此插件仅支持uniappx！！！若您为uniapp项目请使用z-paging！

z-paging uniapp x版

反馈(点击)：114310688

z-paging-x文档

安装

方式1(推荐)：通过uni_modules安装，在插件市场中点击右上角【使用HbuilderX导入插件】即可。

方式2：通过npm安装

//若项目之前未使用npm管理依赖（项目根目录下无package.json文件），先在项目根目录执行命令初始化npm工程
npm init -y

// 安装
npm install z-paging-x --save
// 更新
npm update z-paging-x

基本使用

以下为组合式API(<script setup>)写法。蒸汽模式(Vapor)仅支持组合式API，推荐统一使用。

<template>
    <!-- v-model绑定的ref需通过as指定类型，否则App-Android(非蒸汽模式)下无法推导update:modelValue的参数类型 -->
    <z-paging-x ref="pagingX" v-model="(dataList as ListItem[])" @query="queryList">
        <template #top>
            <common-tabs :list="tabList" @change="tabChange" />
        </template>
        <list-item v-for="(item, index) in dataList" :key="index">
            <view class="list-item">
                <text class="list-item-title">{{item.title}}</text>
                <text class="list-item-type">{{item.detail}}</text>
            </view>
        </list-item>
    </z-paging-x>
</template>

<script setup lang="uts">
    import { requestList, ListItem } from '@/http/request.uts'

    // 与模板中ref="pagingX"同名，用于调用z-paging-x的方法
    const pagingX = ref<ZPagingXComponentPublicInstance | null>(null)

    const tabList = ref(['测试1', '测试2', '测试3', '测试4'] as string[])
    const tabIndex = ref(0)
    const dataList = ref<ListItem[]>([])

    const tabChange = (index: number) => {
        tabIndex.value = index
        // 刷新列表数据
        pagingX.value?.reload()
    }

    // @query所绑定的方法不要自己调用！！需要刷新列表数据时，只需要调用pagingX.value?.reload()即可
    const queryList = (pageNo: number, pageSize: number) => {
        // 此处请求仅为演示，请替换为自己项目中的请求
        requestList({
            pageNo: pageNo,
            pageSize: pageSize,
            type: tabIndex.value + 1
        }).then((res: UTSJSONObject) => {
            // 将请求结果通过complete传给z-paging处理，同时也代表请求结束，这一行必须调用
            pagingX.value?.complete(res['data'] as any[])
        })
    }
</script>

props

支持全局配置（非必须）

在main.uts中

import { setZPXConfig } from '@/uni_modules/z-paging-x/components/z-paging-x/config/index.uts'

setZPXConfig({
    //配置分页默认pageSize为15
    'default-page-size': 15,
    //配置空数据图默认描述文字为：空空如也~~
    'empty-text': '空空如也~~',
    //...
});

数据&布局配置

list-view&scroll-view相关配置

reload相关配置

下拉刷新配置

下拉进入二楼配置

建议在pages.json中将页面navigationStyle设置为custom并使用自定义导航栏，避免二楼被系统导航栏盖住。二楼内容通过slot="f2"传入，其容器高度与z-paging-x一致。

底部加载更多配置

空数据图配置

点击返回顶部配置

聊天记录模式配置

聊天记录模式下列表会被倒置，数组第0项(最新消息)显示在底部，滚动到视觉顶部会自动触发@query加载更多历史消息(from为load-more)，历史消息拼接到数组末尾，加载过程无闪动。complete传入的数据应为服务端返回的“新→旧”顺序(与真实IM接口及z-paging一致)。因为列表被倒置，每个列表项需要绑定@cellStyleChange回传的样式再倒置回来(见demo)。当第一页就没有更多数据(不满一页)时列表不倒置，消息从顶部开始排列。发送新消息请调用addChatRecordData。

events

methods

slots