Pagination 分页

17:06

说明

分页器由「上一页 / 下一页」按钮和中间的「当前页 / 总页数」文本组成：v-model 绑定当前页，total 与 page-size 计算总页数（ceil(total / pageSize)）。翻页时回写 v-model 并派发 change({ type, current })，到达首页或末页时对应按钮自动置灰禁用。

兼容性

平台	支持情况
App	✅ 支持（页码文本在 text 上显式声明颜色与字号，规避 App 端 text 不继承父级样式的问题）
H5	✅ 支持
微信小程序	✅ 支持

示例

基础用法

v-model 绑定当前页码，total 和 page-size 计算总页数。

查看源码

<template>
    <ux-pagination v-model="current" :total="50" :page-size="5"></ux-pagination>
</template>

<script setup lang="uts">
const current = ref<number>(1);
</script>

图标按钮

show-icon 显示左右箭头图标按钮。

查看源码

<template>
    <ux-pagination v-model="current" :total="50" :page-size="5" show-icon></ux-pagination>
</template>

<script setup lang="uts">
const current = ref<number>(1);
</script>

自定义文字

通过 prev-text 和 next-text 自定义按钮文字。

查看源码

<template>
    <ux-pagination v-model="current" :total="50" :page-size="5" prev-text="Prev" next-text="Next"></ux-pagination>
</template>

<script setup lang="uts">
const current = ref<number>(1);
</script>

自定义样式

通过 custom-style 自定义分页器容器样式。

查看源码

<template>
    <ux-pagination v-model="current" :total="50" :page-size="5" show-icon :custom-style="customStyle"></ux-pagination>
</template>

<script setup lang="uts">
import { createStyle } from '@/uni_modules/uview-pro-x';

const current = ref<number>(1);

const customStyle = computed<UTSJSONObject>((): UTSJSONObject => {
    const style = createStyle();
    style['backgroundColor'] = '#f5f5f5';
    style['paddingTop'] = '10px';
    style['paddingBottom'] = '10px';
    style['paddingLeft'] = '10px';
    style['paddingRight'] = '10px';
    style['borderRadius'] = '6px';
    return style;
});
</script>

监听变化

监听 change 事件获取分页方向和当前页码。

查看源码

<template>
    <ux-pagination v-model="current" :total="50" :page-size="5" show-icon @change="onChange"></ux-pagination>
    <text class="result">当前页: {{ current }} / {{ totalPages }}</text>
</template>

<script setup lang="uts">
const current = ref<number>(1);
const totalPages = Math.ceil(50 / 5);

function onChange(payload: UTSJSONObject): void {
    const page = payload['current'] as number;
    const type = payload['type'] as string;
    uni.showToast({ title: type + ' → ' + page, icon: 'none' });
}
</script>

<style scoped>
.result {
    margin-top: 10px;
    font-size: 13px;
    color: #909399;
}
</style>

API

Props

属性	说明	类型	默认值	版本
customStyle	自定义根节点样式	UTSJSONObject	-	-
customClass	自定义根节点样式类	string	''	-
modelValue	当前页码，配合 v-model 双向绑定	number	1	-
prevText	上一页按钮文字，默认取语言包 uPagination.prevText	string	''	-
nextText	下一页按钮文字，默认取语言包 uPagination.nextText	string	''	-
total	数据总条数，用于计算总页数	number	0	-
pageSize	每页条数	number	10	-
showIcon	是否用图标替代文字按钮	boolean	false	-
prevIcon	上一页图标名	string	'arrow-left'	-
nextIcon	下一页图标名	string	'arrow-right'	-

Events

事件名	说明	回调参数	版本
change	页码变化时触发，payload 含 type（prev / next）与 current（新页码）	payload: UTSJSONObject	-

Slots

插槽名	说明	版本
default	中间页码文本区，默认显示「当前页 / 总页数」	-

注意事项

1. 页码不会自动钳制在有效范围内：翻页只是 ±1，仅靠按钮 disabled 拦截；若 total / page-size 变化使总页数变小而当前页偏大，current 不会自动回退。
2. page-size <= 0 时按 10 计算总页数；total <= 0 时总页数为 0，此时 current（≥1）已不小于总页数，下一页按钮会直接禁用。
3. 必须用 v-model（或 :model-value + @update:model-value）绑定页码；change 的 payload 是 UTSJSONObject，取 current / type 需 as 断言（见示例）。
4. show-icon 为 true 时按钮显示 prev-icon / next-icon 图标，prev-text / next-text 不再显示。
5. 默认按钮文字取语言包 uPagination.prevText / nextText（上一页 / 下一页），传入 prev-text / next-text 后覆盖。
6. 中间的「当前页 / 总页数」区域是默认插槽，可整体替换。