Pagination 分页

页码导航。页码省略逻辑自动处理，布局可自由组合。

基础用法

<script setup>
import { ref } from 'vue'
const page = ref(1)
</script>

<template>
  <SrPagination v-model="page" :total="120" :page-size="10" />
</template>

当前第 1 页

布局可配

layout 是数组，顺序即渲染顺序：

共 120 条

<SrPagination :layout="['total', 'sizes', 'prev', 'pager', 'next', 'jumper']" />
<SrPagination :layout="['prev', 'pager', 'next']" />
<SrPagination :layout="['total', 'prev', 'pager', 'next']" />

传字符串也能用，但会有警告

为兼容早期写法，传 "prev, pager, next" 这样的字符串会被自动切分—— 但组件会在控制台给出警告并提示改成数组。

建议直接写数组：字符串少了引号就是另一个意思， 而且数组形式在编辑器里有类型提示与补全。

布局项	说明
total	总条数文本
sizes	每页条数选择器
prev / next	上一页 / 下一页
pager	页码
jumper	跳页输入框

顺序即顺序——把 jumper 放前面它就在最左边。

页码省略

页数多时自动折叠，四种情况分别处理：

情况	显示
总页数 ≤ pagerCount	全部显示
当前页靠前	右侧折叠（1 2 3 4 5 … 20）
当前页靠后	左侧折叠（1 … 16 17 18 19 20）
当前页居中	两侧都折叠（1 … 9 10 11 … 20）

<SrPagination :total="1000" :page-size="10" />
<SrPagination :total="1000" :page-size="10" :pager-count="9" />

拖动上面的页码到头尾看看省略逻辑——当前页永远可见， 这是省略算法的硬约束：把当前位置折进去的话，用户会不知道自己在哪。

每页条数

sizes 布局项启用每页条数选择器。切换后当前页会重新钳制—— 原来的页码可能已越过新的总页数。

当前第 1 页，每页 10 条

<SrPagination
  v-model="page"
  v-model:page-size="size"
  :total="200"
  :page-sizes="[10, 20, 50]"
/>

为什么切换每页条数要重算页码

假设当前在第 15 页、每页 10 条。若改成每页 100 条， 总页数从 20 变成 2——第 15 页根本不存在了。

不重算的话，组件会请求一个越界的页码，后端要么报错、要么返回空列表， 用户看到「没有数据」却不知道哪里出了问题。

单页隐藏

hideOnSinglePage 在只有一页时整体隐藏。

总 5 条、每页 10 条 —— 只有一个分页器被隐藏了

<SrPagination :total="5" :page-size="10" hide-on-single-page />

尺寸与禁用

<SrPagination size="sm" />
<SrPagination disabled />

Props

名称	类型	默认值	说明
modelValue	number	1	当前页码
pageSize	number	10	每页条数（配合 v-model:page-size）
total	number	0	总条数
pageSizes	number[]	[10, 20, 50, 100]	每页条数可选项
layout	string[]	['total', 'sizes', 'prev', 'pager', 'next', 'jumper']	布局项，顺序即顺序
size	'sm' | 'md'	'md'	尺寸
disabled	boolean	false	是否禁用
hideOnSinglePage	boolean	false	单页时是否隐藏
pagerCount	number	7	页码最多显示几个

事件

事件	参数	说明
update:modelValue	number	页码变化
update:pageSize	number	每页条数变化
change	{ page, pageSize }	任一项变化

无障碍

• 外层 <nav> 加 aria-label="分页"，读屏软件能快速定位
• 当前页带 aria-current="page"——这是唯一能让读屏用户知道 「我在第几页」的方式，不能只靠视觉高亮
• 上一页 / 下一页按钮在边界时用原生 disabled，而非仅靠样式变灰
• 键盘完全可用，且页码按钮有足够大的点击区（不小于 32px）