更新记录

1.0.0（2026-11-12） 下载此版本

首发版本，功能对齐 z-paging 2.8.8。

新增

• 全自动分页管理：@query + complete 系列方法，pageNo/pageSize 自动计算
• 自定义下拉刷新：default/release-to-refresh/loading/complete 状态机、增量阻尼算法、角度限制、松手吸附与回弹动画、震动、最后更新时间
• 底部加载更多：default/loading/no-more/fail 四态、flower/circle 双图标、no-more 分割线、hideNoMoreInside/hideNoMoreByLimit/insideMore
• 空数据图：空数据/加载失败双态、重新加载按钮、slot 自定义
• 虚拟列表：fixed/dynamic 高度双模式（前缀和算法）、多列、预加载
• 聊天记录模式：scaleY(-1) 双重倒置、顶部加载更多、键盘适配
• 本地分页 setLocalPaging
• 列表缓存 useCache/cacheKey/cacheMode
• 国际化：zh-Hans/zh-Hant/en，全部文案 props 支持 i18n 对象写法
• 下拉进入二楼（F2）
• 返回顶部按钮、scrollToXXX 方法族、页面滚动模式
• slot 体系：default/top/bottom/left/right/refresher/refresherComplete/loadingMore×4/empty/loading/backToTop/cell/header/footer/chatLoading/chatNoMore/f2
• 全局配置（config + uni.$antPaging.config）与拦截器（query/fetch/language）
• 蒸汽模式（Vapor）兼容：全组合式 API、BEM 简单 class 选择器、无 wxs/renderjs，可运行于 uni-app x 蒸汽模式工程

与 z-paging 的差异

• 仅支持 vue3 组合式（不支持 vue2、不支持 nvue 渲染分支）
• 下拉刷新统一走 js touch 处理（不使用 wxs/renderjs，保证蒸汽模式与全平台一致性）

平台兼容性

uni-app(5.34)

其他

ant-paging 分页组件

ant-paging 是一个高性能全平台分页组件，功能与 z-paging 2.8.8（MIT 开源）一比一对齐，并在此基础上：

• ✅ 支持蒸汽模式（uni-app x Vapor，去虚拟 DOM 渲染引擎，HBuilderX 5.0+ 鸿蒙 / 5.11+ iOS / 5.21+ Android）
• ✅ 支持 App（鸿蒙/Android/iOS）、小程序（微信/支付宝/抖音/百度/QQ 等）、H5
• ✅ 全部采用 Vue3 组合式 API（<script setup>）+ BEM 简单 class 选择器编写，一份代码同时运行于普通 uni-app 与 uni-app x 蒸汽模式

快速上手

两步接入：绑定 v-model 列表 + 绑定 @query 请求方法：

<template>
    <ant-paging ref="paging" v-model="dataList" @query="queryList">
        <view v-for="(item, index) in dataList" :key="index">
            <text>{{ item.title }}</text>
        </view>
    </ant-paging>
</template>

<script setup>
import { ref } from 'vue'
const paging = ref(null)
const dataList = ref([])

const queryList = (pageNo, pageSize) => {
    // 此处请求服务器
    setTimeout(() => {
        const list = []
        for (let i = 0; i < pageSize; i++) {
            list.push({ title: `第${pageNo}页 第${i + 1}条` })
        }
        paging.value.complete(list)
    }, 500)
}
</script>

自定义下拉刷新图标（含 loading 图标）

四个状态图标均可自定义（传图片 url 或 base64）：

配套控制：

• refresher-img-style：图标尺寸/边距，如 :refresher-img-style="{ width: '40rpx', height: '40rpx' }"
• :refresher-refreshing-animated="true"：loading 图标是否旋转（默认 true；自定义图标为平滑旋转，内置菊花为模拟系统逐帧动效）

<ant-paging refresher-refreshing-text="正在刷新..."
    :refresher-refreshing-img="myLoadingIcon"
    :refresher-img-style="{ width: '40rpx', height: '40rpx' }" ... />

更彻底的自定义（文字+图标整体布局、lottie 等）请使用 slot="refresher"（作用域参数 refresherStatus），注意 slot 会整体替换默认刷新视图，与图片级自定义互斥。演示见 pages/paging/custom.vue。

蒸汽模式（Vapor）接入

1. 使用 HBuilderX（5.0+）打开 uni-app x 工程
2. manifest.json 可视化界面勾选蒸汽模式
3. 将 uni_modules/ant-paging 复制到工程 uni_modules 目录
4. 页面中直接使用 <ant-paging>（蒸汽模式支持弱类型 js 组件，本组件已按蒸汽模式约束编写：组合式 API / 简单 class 选择器 / 无 wxs / 样式隔离 2.0）

已验证

• HBuilderX 5.34 + 鸿蒙蒸汽目标编译通过（view.render compile target: nativecode），组件产物含 libentry.so 原生引用
• 编译验证工程见宿主项目 test/vapor-verify/（含 CLI 编译命令与开关说明）
• 已处理的蒸汽 CSS 兼容点：vh 单位（uvue 不支持）、animation steps()（APP 下降级 linear）——均通过条件编译，不影响 H5/小程序

核心功能

主要 API（对照 z-paging）

Props（180+，与 z-paging 同名同义）

常用：

完整 props 请参考源码 components/ant-paging/js/ant-paging-props.js（与 z-paging 文档一比一对齐）。

Events（30+）

Methods（40+，通过 ref 调用）

Slots（20 个）

default / top / bottom / left / right / refresher（作用域：refresherStatus）/ refresherComplete / refresherF2 / f2 / loadingMoreDefault / loadingMoreLoading / loadingMoreNoMore / loadingMoreFail / empty（作用域：isLoadFailed）/ loading / backToTop / cell（作用域：item, index）/ header / footer / chatLoading / chatNoMore

页面滚动模式

use-page-scroll 时在页面 setup 中调用一次 useAntPaging（内部自动注册 onPageScroll / onReachBottom / onPullDownRefresh 并转发给组件）：

<template>
    <ant-paging ref="paging" v-model="dataList" use-page-scroll @query="queryList">...</ant-paging>
</template>
<script setup>
import { ref } from 'vue'
import { useAntPaging } from '@/uni_modules/ant-paging/components/ant-paging/js/modules/use-ant-paging.js'
const paging = ref(null)
useAntPaging(paging)
</script>

全局配置

// main.js
uni.$antPaging = {
    config: {
        defaultPageSize: 20,
        auto: false
    }
}

或修改 components/ant-paging/js/ant-paging-config.js。

拦截器

uni.$antPagingInterceptor = null // 见 js/ant-paging-interceptor.js
// 在 App.vue / main.js:
import interceptor from '@/uni_modules/ant-paging/components/ant-paging/js/ant-paging-interceptor.js'
interceptor.handleQuery((pageNo, pageSize, from) => [pageNo, pageSize, from])

与 z-paging 的差异

平台兼容

许可

MIT。组件视觉素材（base64 图标）复用自 MIT 开源的 z-paging。