Pagination
Pagination
两端统一 API、交互与演示，支持按容器宽度自适应布局。
基础示例
基础与双向绑定
外观与状态
五档尺寸与阴影
本组配置对照
| 配置 | 作用 | 相关示例 |
|---|---|---|
total | 数据总数（必填） | 五档尺寸与阴影、禁用与单页隐藏 |
show-page-size | 显示条数选择器 | 五档尺寸与阴影、禁用与单页隐藏 |
show-jumper | 完整模式显示独立跳转框；简洁模式已有页码输入 | 五档尺寸与阴影、禁用与单页隐藏 |
size | 所有内部控件尺寸 | 五档尺寸与阴影 |
elevation | 页码按钮阴影；true 使用 2 级 | 五档尺寸与阴影 |
disabled | 禁用所有交互 | 禁用与单页隐藏 |
禁用与单页隐藏
分页模式与信息
简洁模式
本组配置对照
| 配置 | 作用 | 相关示例 |
|---|---|---|
total | 数据总数（必填） | 简洁模式、更多页码与省略跳转、总数、每页条数与跳页 |
show-total | 显示总数 | 简洁模式、总数、每页条数与跳页 |
show-page-size | 显示条数选择器 | 简洁模式、总数、每页条数与跳页 |
responsive | 按容器宽度自动切换简洁模式 | 更多页码与省略跳转、总数、每页条数与跳页 |
simple | 显式启用简洁模式 | 简洁模式 |
default-value | 非受控初始页码 | 更多页码与省略跳转 |
更多页码与省略跳转
总数、每页条数与跳页
比较三种分页附加能力。更改页码或每页条数时观察对应输出，数据总数与自动修正另行说明。
条数、跳转与按钮
自定义分页按钮与样式
本组配置对照
| 配置 | 作用 | 相关示例 |
|---|---|---|
total | 数据总数（必填） | 自定义分页按钮与样式 |
default-value | 非受控初始页码 | 自定义分页按钮与样式 |
buffer-size | 当前页两侧的页码数 | 自定义分页按钮与样式 |
responsive | 按容器宽度自动切换简洁模式 | 自定义分页按钮与样式 |
page-item-style | 数字页码基础样式 | 自定义分页按钮与样式 |
active-page-item-style | 叠加到当前数字页码的样式 | 自定义分页按钮与样式 |
响应式与数据变化
容器宽度与窄屏布局
本组配置对照
| 配置 | 作用 | 相关示例 |
|---|---|---|
total | 数据总数（必填） | 容器宽度与窄屏布局、数据变化与自动调整、完整功能交互 |
show-total | 显示总数 | 容器宽度与窄屏布局、数据变化与自动调整、完整功能交互 |
show-page-size | 显示条数选择器 | 容器宽度与窄屏布局、数据变化与自动调整、完整功能交互 |
show-jumper | 完整模式显示独立跳转框；简洁模式已有页码输入 | 容器宽度与窄屏布局、完整功能交互 |
responsive | 按容器宽度自动切换简洁模式 | 容器宽度与窄屏布局 |
auto-adjust | 条数变化时保留首条位置；总数减少时修正越界页码 | 数据变化与自动调整 |
数据变化与自动调整
完整功能交互
阅读方向
继承最近的 dir="ltr|rtl"，支持运行时切换与局部覆盖。页码与上一页/下一页含义保持不变，默认前后图形跟随阅读方向。输入页码、禁用边界和选择不因方向切换而改变；自定义图形插槽由业务决定方向。
API
主值使用普通 v-model：modelValue 表示当前页码，从 1 开始；pageSize 仍独立控制每页条数。defaultValue 仅在创建时初始化非受控状态，之后修改不会重置当前值；初始化不触发 update:modelValue。提供 modelValue 时由父级控制，以受控值为准。
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| total | 数据总数（必填） | number | — |
| model-value | 当前页码，支持 v-model | number | — |
| default-value | 非受控初始页码 | number | 1 |
| page-size | 每页条数，支持 v-model:page-size | number | — |
| default-page-size | 非受控初始条数 | number | 10 |
| disabled | 禁用所有交互 | boolean | false |
| hide-on-single-page | 不足两页时隐藏 | boolean | false |
| simple | 显式启用简洁模式 | boolean | false |
| show-total | 显示总数 | boolean | false |
| show-more | 完整模式追加向后跳页按钮 | boolean | false |
| show-jumper | 完整模式显示独立跳转框；简洁模式已有页码输入 | boolean | false |
| show-page-size | 显示条数选择器 | boolean | false |
| page-size-options | 正整数条数选项 | number[] | [10, 20, 30, 40, 50] |
| page-size-props | 可选的条数 Select 受限配置；placement 默认 bottom-start，经 Select.triggerProps 交给 Trigger 自动定位；不能覆盖分页值、选项和尺寸 | PaginationPageSizeProps | — |
| size | 所有内部控件尺寸 | 'xs' / 'sm' / 'md' / 'lg' / 'xl' | 'md' |
| page-item-style | 数字页码基础样式 | CSSProperties | — |
| active-page-item-style | 叠加到当前数字页码的样式 | CSSProperties | — |
| base-size | 完整模式省略阈值的基础数 | number | 6 |
| buffer-size | 当前页两侧的页码数 | number | 2 |
| elevation | 页码按钮阴影；true 使用 2 级 | boolean / number | false |
| responsive | 按容器宽度自动切换简洁模式 | boolean | true |
| compact-breakpoint | 简洁模式的最大容器宽度，单位 px | number | 480 |
| auto-adjust | 条数变化时保留首条位置；总数减少时修正越界页码 | boolean | true |
Events
| Event | Description | Arguments |
|---|---|---|
| update:model-value | 请求更新页码 | number |
| change | 页码提交变化（与 update:modelValue 成对） | number |
| update:page-size | 请求更新条数 | number |
| page-size-change | 条数提交变化（与 update:page-size 成对） | number |
Slots
| Slot | Description | Scope |
|---|---|---|
| total | 总数 | { total: number } |
| page-item | 数字页码 | { page: number } |
| page-item-step | 上一页、下一页 | { type: 'previous' / 'next' } |
| page-item-ellipsis | 省略跳转按钮 | — |
| jumper-prepend | 独立跳转框前缀 | — |
| jumper-append | 独立跳转框后缀 | — |
Methods
| Method | Description |
|---|
行为说明
容器宽度不超过 compact-breakpoint 时自动使用简洁模式；桌面侧栏与移动端规则相同。保留总数和条数选择器，辅助控件换行，上一页、下一页按钮跟随 size，不再在窄屏强制放大（默认 36px）。设置 responsive=false 保留完整页码，极窄时仅页码列表横向滚动，不撑宽页面。
简洁模式的当前页输入框承担跳转功能，不重复展示独立 jumper。page-item、page-item-ellipsis、jumper-prepend、jumper-append 仅在完整模式的对应控件中渲染。
页码按钮支持 Tab、Enter、Space，当前页使用 aria-current=page。跳转框使用数字键盘提示，Enter 或失焦提交；空值、非数字、小数不跳转，整数越界限制到有效页码。禁用状态阻止所有提交。
auto-adjust 在条数改变时尽量保留原页面首条数据的位置，总数减少时限制到最后一页，零条数据时页码回到 1。受控模式只发出更新请求，显示由父组件决定；父组件同一批更新明确设置 modelValue 时优先遵循该值。
完整模式和简洁模式的“前往”输入框均显示当前页码。点击翻页、外部更新 modelValue 或切换每页条数触发页码调整时同步回显；非法输入恢复为当前页码。
PaginationPageSizeProps
每页条数选择器按已选文字与下拉箭头自适应宽度，两者之间仅保留条目间距，切换选项或语言时自动更新。可通过 --c-pagination-select-width 自定义宽度。弹出菜单仍按选项内容独立计算宽度。
两端支持相同配置：disabled?: boolean、placement?: 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end'、popupContainer?: string | HTMLElement | false、class?: string、style?: CSSProperties。外层 disabled 优先。默认 placement 为 bottom-start。
此配置不再透传任意 SelectProps/MenuProps。分页值、选项和尺寸分别使用 page-size、page-size-options、size。
类型定义
import type { PaginationProps, PaginationInstance, PaginationPageSizeProps } from '@cedar-design/ui'
样式变量
| Token | Default |
|---|---|
--c-pagination-text-color | var(--c-color-text-1) |
--c-pagination-font-size | var(--c-sys-font-size-md) |
--c-pagination-gap | var(--c-sys-space-5) |
--c-pagination-item-gap | var(--c-sys-space-2) |
--c-pagination-focus-space | 3px |
--c-pagination-size-xs | 24px |
--c-pagination-size-sm | 28px |
--c-pagination-size-md | 36px |
--c-pagination-size-lg | 44px |
--c-pagination-size-xl | 52px |
--c-pagination-item-padding | var(--c-sys-space-4) |
--c-pagination-item-border-radius | var(--c-sys-radius-md) |
--c-pagination-icon-size | 16px |
--c-pagination-input-width | 32px |
--c-pagination-select-width | max-content |
--c-pagination-touch-size | 44px |
--c-pagination-focus-width | 2px |
--c-pagination-focus-offset | 1px |
--c-pagination-focus-color | var(--c-color-primary) |
--c-pagination-item-background | transparent |
--c-pagination-hover-background | var(--c-color-fill-1) |
--c-pagination-active-background | var(--c-color-primary-light-1) |
--c-pagination-active-color | var(--c-color-primary) |
--c-pagination-disabled-color | var(--c-color-text-4) |
--c-pagination-disabled-background | var(--c-color-fill-1) |
方位语义与配置入口
普通使用无需配置方位：默认 bottom-start，空间不足时底层 Trigger 自动翻转和约束。pageSizeProps.placement 仅是条数 Select 的受限覆盖入口，链路为 Pagination → Select.triggerProps.placement → Trigger；不是分页器自身位置。