Pagination

提供页码导航，帮助用户在多页数据之间切换，适合表格、列表和搜索结果。

我们正在让 SnowUI 组件成为 AI 对话中可直接操作的界面。目前对话交互能力仍在建设中；本页展示网站用法，支持的对话平台与组件版本将在验证后公布。 AI 对话内生成和使用 SnowUI 界面完全免费，不属于项目，不占项目或开发者席位额度，无需 SnowUI 注册、激活或付费证明。

如何使用

用于多页内容导航。DataTable 场景与其渲染状态连接；页码变化与数据请求是不同责任，不能假定组件自动发请求。

page 从 1 开始，total 表示总页数，不是数据条数；onPageChange 连接页面状态。
pageSizeOptions 配置每页条数选择，pageSize 可绑定；数据请求和总页数计算由页面或 DataTable 负责。
根导航默认名称随LocaleProvider更新，显式ariaLabel优先；不改变页码、每页条数与业务请求责任。

导入

import { Pagination } from '@snowui-design-system/components';

用法

长范围

响应式

变体

宽度模式

每页数量位置

不可用页面

API 参考

属性	类型	默认值	示例	描述
`page`	`number`	`1`	`page={42}`	当前页，从 1 开始
`total`	`number`	`1`	`total={42}`	总页数
`disabled`	`boolean`	`false`	`disabled`	禁用整个 Pagination
`disabledPages`	`number[]`	`[]`	`disabledPages={[2, 5]}`	禁用指定页码；上一页 / 下一页会跳过连续禁用页，指向该方向最近的可用页
`ariaLabel`	`string`	`—`	`ariaLabel="Example"`	根导航区域的无障碍标签；省略时随LocaleProvider更新，显式ariaLabel优先
`variant`	`PaginationVariant`	`"outline"`	`variant="gray"`	普通页与前后页的按钮样式；当前页使用对应的强调搭配
`responsive`	`PaginationResponsive`	`"auto"`	`responsive="none"`	`auto` 根据容器宽度自动选择完整页码、省略页码与最小前后页；`none` 保持静态页码窗口与原有换行行为
`widthMode`	`PaginationWidthMode`	`"fill"`	`widthMode={value}`	`auto` 在完整页码可容纳时按剩余空间判断，`hug` 保持内容宽度，`fill` 始终等宽填充；fill 模式含省略号时也填满可用宽度；hug 保持内容宽度
`gap`	`string \| number`	`—`	`gap="Example"`	页码、prev、next 之间的首选间距；数字按 px 处理，有效下限为 4 CSS px，较大值保留。默认使用 gap-1。
`pageSize`	`number`	`20`	`pageSize={42}`	当前每页条数；选择后组件自行更新绑定值，仅在 `pageSizeOptions` 非空时显示选择器
`pageSizeOptions`	`number[]`	`[]`	`pageSizeOptions={[10, 20, 50]}`	可选的每页条数；非正数会被忽略，重复项会被去重
`pageSizeGap`	`string \| number`	`16`	`pageSizeGap="Example"`	pageSize 与分页按钮组之间的独立首选间距；数字按 px 处理，有效下限为 4 CSS px，较大值保留
`pageSizeAriaLabel`	`string`	`—`	`pageSizeAriaLabel="Example"`	每页条数选择器的无障碍名称；默认随 LocaleProvider 使用中文“每页条数”或英文“Items per page”
`onPageChange`	`(page: number) => void`	`—`	`onPageChange={(page) => currentPage = page}`	可点击页码变化时触发
`onPageSizeChange`	`(pageSize: number) => void`	`—`	`onPageSizeChange={(size) => pageSize = size}`	每页条数变化时触发
`children`	`Snippet`	`—`	`<Pagination><Button as="current" /><Button as="page" /></Pagination>`	角色样式模板
`parts`	`ComponentPartsOf<{ Button: typeof Button; Listbox: typeof Listbox; MenuItem: typeof MenuItem; }>`	`—`	`parts={{ Button: { radius: 12 } }}`	统一配置内置页码按钮、每页条数 Listbox 与选项；显式 children 角色模板不读取父级 parts，自行配置 Props。