---
title: Pagination 分页器
description: 页码、每页条数、快速跳转与总条数
---

# Pagination 分页器

`Pagination` 用来在长列表里翻页。它只负责「页码状态」，不关心数据请求——翻页后由你拿 `current` / `pageSize` 去拉数据。

## 何时使用

- 数据量较大、需要分页请求时；
- 需要在「每页条数」与「快速跳转」上给用户控制权时；
- 数据可以一次拉完（< 200 条）时，直接滚动加载可能体验更好。

## 基础用法

<demo vue="pagination/basic.vue" />

## 每页条数

`showSizeChanger` 显示每页条数下拉；`showSizeChange` 只在该值变化时触发，**先于** `change`。

<demo vue="pagination/size-changer.vue" />

## 快速跳转与总条数

<demo vue="pagination/quick-jumper.vue" />

`#showTotal` 插槽作用域是 `{ total, from, to }`：

<demo vue="pagination/total.vue" />

## 只有一页时隐藏

<demo vue="pagination/hide-on-single.vue" />

## 与列表联动

```vue
<script setup lang="ts">
const current = ref(1)
const pageSize = ref(20)

const { data } = await useFetch('/api/list', {
  query: computed(() => ({ page: current.value, size: pageSize.value })),
})
</script>

<template>
  <DataTable :rows="data.rows" />
  <G3Pagination v-model:current="current" v-model:page-size="pageSize" :total="data.total" show-size-changer show-total />
</template>
```

翻页后请记得把列表滚动回顶部（`scrollTo({ top: 0 })`），否则用户会看到「页码变了但内容没动」的错觉。

## API

### Props

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `current` | `number` | — | 当前页（`v-model:current`）。不传时内部维护，默认 1 |
| `pageSize` | `number` | — | 每页条数（`v-model:pageSize`）。不传时内部维护，默认 10 |
| `total` | `number` | `0` | 总条数 |
| `disabled` | `boolean` | `false` | 禁用整组 |
| `hideOnSinglePage` | `boolean` | `false` | 只有一页时隐藏整个分页器 |
| `showSizeChanger` | `boolean` | `false` | 显示每页条数选择器 |
| `pageSizeOptions` | `Array<number \| string>` | `[10, 20, 50, 100]` | 每页条数选项 |
| `showQuickJumper` | `boolean` | `false` | 显示快速跳转输入框 |
| `showTotal` | `boolean` | `false` | 显示总条数文案 |

### Events

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `update:current` | `(page: number)` | 当前页变化 |
| `update:pageSize` | `(size: number)` | 每页条数变化 |
| `change` | `(page: number, pageSize: number)` | 翻页与改每页条数都会触发 |
| `showSizeChange` | `(current: number, size: number)` | **仅**改每页条数时触发，先于 `change` |

### Slots

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `showTotal` | `{ total: number; from: number; to: number }` | 自定义总条数文案；`from` / `to` 是当前页的起止序号（`total` 为 0 时都是 0） |

### 类型定义

```ts
export interface PaginationProps {
  current?: number
  pageSize?: number
  total?: number
  disabled?: boolean
  hideOnSinglePage?: boolean
  showSizeChanger?: boolean
  pageSizeOptions?: Array<number | string>
  showQuickJumper?: boolean
  showTotal?: boolean
}

export interface PaginationTotalScope {
  total: number
  from: number
  to: number
}
```

## 实现说明

- **页码窗口算法**：总页数 ≤ 7 全部展开；否则固定首页与末页、当前页 ±1，并用省略号表示被折叠的部分。点省略号会向前/后跳 5 页：
  - 前面的省略号 → `max(1, current - 5)`
  - 后面的省略号 → `min(totalPages, current + 5)`
- **越界收敛但不回写**：受控值超出范围时只收敛**显示**（`clampPage`），不会 emit 新值——避免「父层给了 999，组件偷偷改成 10」这类难以排查的行为；
- 快速跳转只在回车时提交，输入非数字、超范围都会被忽略并清空输入框（点失焦也清空），避免残留一个「看起来有效其实没提交」的数字；
- 语义与无障碍：根节点 `role="navigation"`；当前页 `aria-current="page"`；上一页 / 下一页与省略号都有 `aria-label`（来自语言包，可随 `locale` 切换）；禁用状态用原生 `disabled`，键盘用户不会误触。