> Leaf UI 0.6.0 · Package: @ifhover/leaf-ui · Source: b30c3d3a8fa9c5e15d0d0522cebfbd33f60c6b06
> Browser documentation: https://ifhover.github.io/leaf-ui/v/0.6.0/components/pagination.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms-full.txt.

# Pagination 分页

按页浏览较多的数据。

## 基础用法

默认使用描边按钮，也可以通过 `variant="ghost"` 使用无边框按钮。


描边（默认）

12345

无边框

12345

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/pagination/basic.tsx"
import { Pagination, Space, Text } from '@ifhover/leaf-ui';

export function PaginationBasic() {
  return (
    <Space direction="vertical" align="center" size="lg">
      <Space direction="vertical" align="start" size="sm">
        <Text tone="muted">描边（默认）</Text>
        <Pagination total={50} defaultCurrent={2} />
      </Space>
      <Space direction="vertical" align="start" size="sm">
        <Text tone="muted">无边框</Text>
        <Pagination total={50} defaultCurrent={2} variant="ghost" />
      </Space>
    </Space>
  );
}
```

展开代码

## 不同尺寸

分别展示小、默认和大尺寸。


小尺寸

123

默认尺寸

123

大尺寸

123

sizes.tsx

复制代码

```tsx lineNumbers file="../../src/examples/pagination/sizes.tsx"
import { Pagination, Space, Text } from '@ifhover/leaf-ui';

export function PaginationSizes() {
  return (
    <Space direction="vertical" align="center" size="lg">
      <Space direction="vertical" align="start" size="sm">
        <Text tone="muted">小尺寸</Text>
        <Pagination total={30} defaultCurrent={2} size="sm" />
      </Space>
      <Space direction="vertical" align="start" size="sm">
        <Text tone="muted">默认尺寸</Text>
        <Pagination total={30} defaultCurrent={2} size="md" />
      </Space>
      <Space direction="vertical" align="start" size="sm">
        <Text tone="muted">大尺寸</Text>
        <Pagination total={30} defaultCurrent={2} size="lg" />
      </Space>
    </Space>
  );
}
```

展开代码

## 数据控制

同时控制页码和每页条数；开启统计、条数选择和页码跳转。


共 240 条1234…24跳至

controlled.tsx

复制代码

```tsx lineNumbers file="../../src/examples/pagination/controlled.tsx"
import { Pagination } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function PaginationControlled() {
  const [pagination, setPagination] = useState({ current: 1, pageSize: 10 });

  return (
    <Pagination
      total={240}
      {...pagination}
      showTotal
      showSizeChanger
      showQuickJumper
      onChange={(current, pageSize) => setPagination({ current, pageSize })}
    />
  );
}
```

展开代码

## 简洁与禁用

`simple` 只保留前后翻页和当前页信息；`disabled` 禁用所有操作。


简洁模式

3 / 24

禁用状态

12345

states.tsx

复制代码

```tsx lineNumbers file="../../src/examples/pagination/states.tsx"
import { Pagination, Space, Text } from '@ifhover/leaf-ui';

export function PaginationStates() {
  return (
    <Space direction="vertical" align="center" size="lg">
      <Space direction="vertical" align="start" size="sm">
        <Text tone="muted">简洁模式</Text>
        <Pagination total={240} defaultCurrent={3} simple />
      </Space>
      <Space direction="vertical" align="start" size="sm">
        <Text tone="muted">禁用状态</Text>
        <Pagination total={50} defaultCurrent={2} disabled />
      </Space>
    </Space>
  );
}
```

展开代码

## Pagination API

| 属性                 | 类型                                                                            | 默认值                 | 说明                                      |
| ------------------ | ----------------------------------------------------------------------------- | ------------------- | --------------------------------------- |
| `total`            | `number`                                                                      | 必填                  | 必需。数据总条数                                |
| `current`          | `number`                                                                      | —                   | 受控页码，从 1 开始                             |
| `defaultCurrent`   | `number`                                                                      | `1`                 | 非受控初始页码                                 |
| `pageSize`         | `number`                                                                      | —                   | 受控每页条数                                  |
| `defaultPageSize`  | `number`                                                                      | `10`                | 非受控初始每页条数                               |
| `onChange`         | `(page: number, pageSize: number) => void`                                    | —                   | 页码或条数实际变化时调用一次，同时返回两者                   |
| `showSizeChanger`  | `boolean`                                                                     | `false`             | 展示每页条数选择器                               |
| `pageSizeOptions`  | `readonly number[]`                                                           | `[10, 20, 50, 100]` | 可选每页条数；自动包含当前条数，忽略无效值并去重                |
| `showQuickJumper`  | `boolean`                                                                     | `false`             | 回车或离开分页区域时跳转；点击其他分页控件时以该操作为准            |
| `showTotal`        | `boolean \| ((total: number, range: readonly [number, number]) => ReactNode)` | `false`             | true 展示默认统计，也可传入函数自定义；range 为当前页首末条目的序号 |
| `simple`           | `boolean`                                                                     | `false`             | 只展示前后翻页和当前页 / 总页数                       |
| `disabled`         | `boolean`                                                                     | `false`             | 禁用交互。                                   |
| `hideOnSinglePage` | `boolean`                                                                     | `false`             | 总页数不足两页时隐藏                              |
| `size`             | `'sm' \| 'md' \| 'lg'`                                                        | `'md'`              | 页码按钮、条数选择器和跳转输入框的尺寸                     |
| `variant`          | `'outline' \| 'ghost'`                                                        | `'outline'`         | 按钮样式：描边 / 无边框                           |

组件同时支持 `aria-label`、`className`、`style` 等原生 `<nav>` 属性。

## 类型

```ts
import type { PaginationProps } from '@ifhover/leaf-ui';
```

## 使用说明

基础分页只需提供 `total`，组件自行管理页码和条数。加载远程数据时使用 `current` 和 `pageSize`，在 `onChange` 中一起更新并请求数据；`total` 应是完整结果的总条数，而非当前页条数。

改变每页条数时尽量保留当前数据位置，例如从每页 10 条的第 3 页切换到每页 20 条，会进入第 2 页。越界页码自动限制到有效范围；空数据保留第 1 页，前后按钮均禁用。外部属性变化不会额外触发 `onChange`。

`showTotal` 的默认统计跟随 ConfigProvider 的语言。需要展示当前数据范围时，可以传入渲染函数：

```tsx
<Pagination
  total={240}
  showTotal={(total, [start, end]) => `${start}–${end} / ${total} 条`}
/>
```