Pagination
pagination分页器 · 纯皮肤受控 + 页码区间算法(省略号)
用法
基础用法
受控组件：自行持有 page 状态，onPageChange 回写。点击页码 / 上下页切换。
tsx
const [page, setPage] = useState(1);
<Pagination page={page} total={10} onPageChange={setPage} />两侧省略
总页数较多时，当前页两侧之外自动折叠为省略号，首末页恒显。
tsx
<Pagination page={page} total={20} onPageChange={setPage} />首末页跳转
showFirstLast 显示「跳到首页 / 末页」双箭头按钮。
tsx
<Pagination page={page} total={20} onPageChange={setPage} showFirstLast />更宽窗口
siblingCount 控制当前页左右各显示的页码数，默认 1。
tsx
<Pagination page={page} total={20} onPageChange={setPage} siblingCount={2} />禁用态
disabled 禁用整个分页器，所有按钮不可点。
tsx
<Pagination page={page} total={10} onPageChange={setPage} disabled />何时用
列表/表格分页切换，已知总页数、点页码或上下页跳转。表达层级位置用 Breadcrumb；同层内容互斥切换用 Tabs。需要纯算法拿可见页码序列（自己渲染）可单独用导出的 getPaginationRange。
导入
ts
import { Pagination, getPaginationRange } from "@hulianui/ui"Props
分页器受控 only：必须由外部 state 持有 page 并在 onPageChange 里 setState。
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| page* | number | — | 当前页（1 起），受控 |
| total | number | — | 总页数（不是总条数）。与 totalItems 二选一，同传时以本项为准 |
| totalItems | number | — | 总条数（后端 data.total 的常见语义），与 pageSize 一起换算页数 |
| pageSize | number | 10 | 每页条数，仅在给了 totalItems 时参与算页数 |
| siblingCount | number | 1 | 当前页左右各显示的页码数 |
| showFirstLast | boolean | false | 是否显示「跳首页/末页」按钮 |
| showTotal | boolean ｜ (totalItems, [from, to]) => ReactNode | false | 左侧总数文案（默认「共 N 条」）。依赖 `totalItems`，只给 total 时静默不渲染 |
| showQuickJumper | boolean | false | 右侧「跳至 __ 页」输入框（回车/失焦提交，自动夹紧到合法范围） |
| disabled | boolean | false | 禁用整个分页器 |
Events
| 事件 | 类型 | 说明 |
|---|---|---|
| onPageChange* | (page: number) => void | 页码变更回调（点击页码/上下页/首末页时触发，已夹紧到 [1, total]） |
禁忌 / 坑
- [[pagination-range-single-gap-fill-not-ellipsis]]：页码序列由
getPaginationRange生成 —— 当两个展示页之间只隐藏了 1 页时直接补出那个页码，而不是显示「…」（省略号仅在 gap > 1 时出现），避免出现1 … 3这种只藏一页还占省略号的丑态。模型同 MUI usePagination。 - 组件不持有内部页码态，忘了在
onPageChange里更新page会点不动。 - `total` 是总页数，与几乎所有后端回的 `total`（总条数）语义相反。 接后端数据请走
totalItems+pageSize，别在调用处自己Math.ceil—— 两处各算一遍最容易在边界（0 条 / 整除）上分叉。两个 prop 同传会在 dev 下告警并以total为准。 total的语义修正留到 1.0 主版本一次性做，届时两个 prop 会合并为一个。新代码优先写totalItems。showTotal依赖totalItems—— 只给了total（页数）时算不出条数，本项静默不渲染而非报错。
相关
Playground
<Pagination page={page} total={10} onPageChange={setPage} />