0 Fork 0

Files

T

2026-10-09 17:32:14 +08:00

4.2 KiB

Raw Blame History

title, description

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

Pagination 分页器

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

何时使用

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

基础用法

每页条数

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

快速跳转与总条数

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

只有一页时隐藏

与列表联动

<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）

类型定义

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，键盘用户不会误触。

4.2 KiB Raw Blame History Unescape Escape