u

code/g3soft-libs/docs/content/ui/data/pagination.md

@@ -0,0 +1,118 @@
+---
+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`，键盘用户不会误触。