Pagination 分页

用于长列表和表格的数据分页浏览，可切换页码、调整每页条数或输入页码快速跳转。

何时使用

• 数据量较大，需要拆分为多个页面展示。
• 表格、列表或搜索结果需要保留当前页、每页条数等浏览状态。
• 需要在完整分页、简单分页和跳转输入之间按场景切换。

基础用法

共 120 条

• 1
• 2
• 3
• 4
• 5
• 12

当前第 2 页

<template>
  <x-pagination v-model:current="current" :total="120" show-total />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const current = ref(2);
</script>

受控页码和事件

共 240 条

• 1
• 2
• 3
• 4
• 5
• 24

10 条/页

当前：第 3 页，10 条/页

<template>
  <x-pagination
    v-model:current="current"
    v-model:page-size="pageSize"
    :total="240"
    show-total
    show-page-size
    :page-size-options="[10, 20, 40]"
    @change="handleCurrentChange"
    @page-size-change="handlePageSizeChange"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const current = ref(3);
const pageSize = ref(10);

const handleCurrentChange = (current: number) => {
  console.log('current:', current);
};

const handlePageSizeChange = (pageSize: number) => {
  console.log('pageSize:', pageSize);
};
</script>

每页条数

• 1
• 3
• 4
• 5
• 6
• 7
• 32

10 条/页

当前第 5 页，10 条/页

<template>
  <x-pagination
    v-model:current="current"
    v-model:page-size="pageSize"
    :total="320"
    show-page-size
    :page-size-options="[10, 20, 50, 100]"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const current = ref(5);
const pageSize = ref(10);
</script>

跳转输入

• 1
• 2
• 3
• 4
• 5
• 18

跳转至页

输入页码后跳转到第 1 页

<template>
  <x-pagination v-model:current="current" :total="180" show-jumper>
    <template #jumper-append>页</template>
  </x-pagination>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const current = ref(1);
</script>

简单模式

/12

适合空间较窄的工具栏或弹层

<template>
  <x-pagination v-model:current="current" :total="120" simple />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const current = ref(4);
</script>

更多页码和边界

• 1
• 16
• 17
• 18
• 19
• 20
• 50

省略号可快速跨页跳转

单页时分页被隐藏

<template>
  <x-pagination :total="500" :default-current="18" show-more />
  <x-pagination :total="8" hide-on-single-page />
</template>

尺寸和禁用

MiniSmallMediumLarge

共 120 条

• 1
• 2
• 3
• 4
• 5
• 12

10 条/页跳转至

共 120 条

• 1
• 2
• 3
• 4
• 5
• 12

10 条/页

<template>
  <x-radio-group v-model="size" type="button">
    <x-radio value="mini">Mini</x-radio>
    <x-radio value="small">Small</x-radio>
    <x-radio value="medium">Medium</x-radio>
    <x-radio value="large">Large</x-radio>
  </x-radio-group>
  <x-pagination :total="120" :size="size" show-total show-page-size show-jumper />
  <x-pagination :total="120" :default-current="3" disabled show-total show-page-size />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const size = ref<'mini' | 'small' | 'medium' | 'large'>('medium');
</script>

自定义内容

共 260 条记录

• 上一页
• P1
• ...
• P4
• P5
• P6
• P7
• P8
• ...
• P26
• 下一页

到第页

<template>
  <x-pagination v-model:current="current" :total="260" show-total show-jumper>
    <template #total="{ total }">共 {{ total }} 条记录</template>
    <template #page-item="{ page }">P{{ page }}</template>
    <template #page-item-step="{ type }">
      {{ type === 'previous' ? '上一页' : '下一页' }}
    </template>
    <template #page-item-ellipsis>...</template>
    <template #jumper-prepend>到第</template>
    <template #jumper-append>页</template>
  </x-pagination>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const current = ref(6);
</script>

使用说明

• 页码和每页条数会被限制在合法范围内；非法或清空的每页条数不会触发分页变更。
• 页码项、上一页、下一页和省略跳转支持键盘聚焦，可使用 Enter 或 Space 触发。
• 当 autoAdjust 为 true 时，改变每页条数或总页数减少会尽量保持数据位置连续，并自动修正当前页。

按需导入

import { Pagination } from 'x-next';

样式按需引入（base.css 为共享基础层，多个组件只需引入一次）：

import 'x-next/style/base.css';
import 'x-next/style/pagination.css';

Props

参数	说明	类型	默认值
total	数据总数	number	必填
current	当前页码	number	undefined
defaultCurrent	默认页码，非受控模式	number	1
pageSize	每页条数	number	undefined
defaultPageSize	默认每页条数，非受控模式	number	10
disabled	是否禁用	boolean	false
hideOnSinglePage	单页时是否隐藏	boolean	false
simple	是否为简单模式	boolean	false
showTotal	是否显示总数	boolean	false
showMore	是否显示更多按钮	boolean	false
showJumper	是否显示跳转输入	boolean	false
showPageSize	是否显示每页条数选择器	boolean	false
pageSizeOptions	每页条数选项，建议使用正整数	number[]	[10, 20, 30, 40, 50]
pageSizeProps	每页条数选择器 Props	SelectProps	-
size	分页尺寸	'mini' | 'small' | 'medium' | 'large'	跟随全局配置
pageItemStyle	页码按钮样式	CSSProperties	-
activePageItemStyle	当前页码按钮样式	CSSProperties	-
baseSize	显示省略的基础页码数	number	6
bufferSize	当前页左右显示页码个数	number	2
autoAdjust	改变每页条数或总页数时是否自动调整页码	boolean	true

Events

事件名	说明	回调参数
update:current	当前页码变化时触发	current: number
update:pageSize	每页条数变化时触发	pageSize: number
change	页码改变时触发	current: number
page-size-change	每页条数改变时触发	pageSize: number

Slots

插槽名	说明	参数
page-item	自定义页码按钮	{ page }
page-item-step	自定义上一页/下一页按钮	{ type }
page-item-ellipsis	自定义省略按钮	-
total	自定义总数内容	{ total }
jumper-prepend	自定义跳转输入前置内容	-
jumper-append	自定义跳转输入后置内容	-

无障碍

• 根节点是 role="navigation" 地标，带 aria-label（跟随 locale），读屏用户可以按地标快速定位。
• 忽略边框、当前页用 aria-current="page" 标注，上一页/下一页与省略号带 aria-label。
• 禁用时所有分页项（包括省略号）都不可聚焦、不响应键盘。
• 跳转输入框带无障碍名称（跟随 locale 的「跳转至」）。

已知限制

• total 必须是有限正数。传入 Infinity（「总数未知」）或 NaN 时，组件按 0 处理并只渲染一页，不会输出 Infinity 页码或卡死；需要「未知总数」的分页交互请在业务层另做实现。
• 当前页越界时只做渲染层钳制，除非开启 autoAdjust，否则不会向上同步事件。