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

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

# Pagination 分页

按页浏览较多的数据。


## 基础用法

`total` 是完整结果的总条数，而不是当前页条数。页码从 1 开始，非受控用法由组件管理当前页。


12345

basic.tsx

复制代码

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

export function PaginationBasic() {
  return <Pagination total={50} />;
}
```

展开代码

越界页码会限制到有效范围。`total={0}` 时仍显示第 1 页，前后翻页按钮均禁用。


## 示例

### 按钮样式

通过 `variant` 选择描边或无边框的分页按钮。


描边（默认）

123

无边框

123

variants.tsx

复制代码

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

export function PaginationVariants() {
  return (
    <Grid columns={1} gap={16}>
      <Flex direction="column" gap={8}>
        <Text tone="muted">描边（默认）</Text>
        <Pagination aria-label="描边分页" total={30} defaultCurrent={2} />
      </Flex>
      <Flex direction="column" gap={8}>
        <Text tone="muted">无边框</Text>
        <Pagination aria-label="无边框分页" total={30} defaultCurrent={2} variant="ghost" />
      </Flex>
    </Grid>
  );
}
```

展开代码

### 不同尺寸

通过 `size` 设置分页按钮尺寸。


小

123

中（默认）

123

大

123

sizes.tsx

复制代码

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

export function PaginationSizes() {
  return (
    <Grid columns={1} gap={16}>
      <Flex direction="column" gap={8}>
        <Text tone="muted">小</Text>
        <Pagination aria-label="小尺寸分页" total={30} defaultCurrent={2} size="sm" />
      </Flex>
      <Flex direction="column" gap={8}>
        <Text tone="muted">中（默认）</Text>
        <Pagination aria-label="中尺寸分页" total={30} defaultCurrent={2} size="md" />
      </Flex>
      <Flex direction="column" gap={8}>
        <Text tone="muted">大</Text>
        <Pagination aria-label="大尺寸分页" total={30} defaultCurrent={2} size="lg" />
      </Flex>
    </Grid>
  );
}
```

展开代码

### 数据控制

加载远程数据时，同时控制 `current` 和 `pageSize`，在 `onChange` 中一起更新。数据请求由应用发起；下面用当前页和数据范围展示状态变化。


1-10 / 240 条1234…24跳至

第 1 页，每页 10 条

controlled.tsx

复制代码

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

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

  return (
    <Flex direction="column" gap={16}>
      <Pagination
        total={240}
        {...pagination}
        showTotal={(total, [start, end]) => `${start}-${end} / ${total} 条`}
        showSizeChanger
        showQuickJumper
        onChange={(current, pageSize) => setPagination({ current, pageSize })}
      />
      <Text tone="muted" role="status">
        第 {pagination.current} 页，每页 {pagination.pageSize} 条
      </Text>
    </Flex>
  );
}
```

展开代码

改变每页条数会尽量保留当前数据位置：每页 10 条的第 3 页切换到每页 20 条，会进入第 2 页。外部属性变化不会额外触发 `onChange`。

### 简洁模式

设置 `simple`，只显示当前页和前后翻页操作。


3 / 24

simple.tsx

复制代码

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

export function PaginationSimple() {
  return <Pagination total={240} defaultCurrent={3} simple />;
}
```

展开代码

### 禁用状态

通过 `disabled` 禁止切换分页。


12345

states.tsx

复制代码

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

export function PaginationStates() {
  return <Pagination total={50} defaultCurrent={2} disabled />;
}
```

展开代码


## API

### 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>` 属性。
