# 分页 · Pagination

- 页面: https://jiguang132.com/zh/resources/astryx/docs/pagination
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

分页用于导航场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

## 安装与前置条件

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

- **分页 · 样式变化 / 分页 / 样式 1**：首先体验这个示例，再查看代码理解组件的组合方式。
- **分页 · 分页 2**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **分页 · 尺寸变化 / 分页 3**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **分页 · 分页 4**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

## API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

## Pagination

Pagination lets users step through pages of content. Place it below a table, list, or card grid so users can move forward and backward through results. Pick a variant to match the context: numbered pages for data tables, a count for large lists, compact for tight spaces, or dots for carousels.

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| page * | number |  | 当前页码（从 1 开始）。第 1 页为首页。 |
| onChange * | (page: number) => void |  | 页码变化时调用。 |
| changeAction | (page: number) => void \| Promise<void> |  | 页码变化时的异步操作。在 onChange 之后触发，使用 React transitions 实现内置加载状态。 |
| totalItems | number |  | 总项目数。用于计算页数。同时提供时优先于 totalPages。 |
| totalPages | number |  | 总页数。当你知道页数但不知道项目数时使用。 |
| hasMore | boolean |  | 当前页之后是否还有更多页。用于总数未知的游标分页。 |
| pageSize | number | 10 | 每页项目数。强制转换为正整数；非有限值回退到默认值。 |
| pageSizeOptions | number[] |  | 可用的每页大小选项。提供时显示每页大小选择器下拉菜单。 |
| onPageSizeChange | (pageSize: number) => void |  | 每页大小变化时调用。自动重置到第 1 页。 |
| variant | 'pages' \| 'count' \| 'compact' \| 'dots' \| 'input' \| 'none' | 'pages' | 控制上一页/下一页按钮之间显示内容的视觉变体。'pages' 显示带省略号的页码按钮，'count' 显示 'X-Y of Z' 文本，'compact' 显示 'Page X of Y'，'dots' 显示点指示器，'input' 显示带前置标签的可编辑页码框——'Page [ n ] / N'——默认两侧带首页/末页按钮，'none' 仅显示上一页/下一页按钮。 |
| pageLabel | string |  | 'input' 变体中可编辑框前显示的名词，如 'Page' 或 'Row'。导航始终基于页码（通过 onChange）；此项仅用于重新标注。默认为本地化的 'Page'。 |
| hasFirstLast | boolean | true | 是否显示首页/末页（«/»）双箭头按钮，位于上一页/下一页两侧。仅适用于 'input' 变体；当页数未知（游标/hasMore 分页）时省略。 |
| step | number | 1 | 上一页/下一页按钮每次点击前进的页数。会被限制在有效页码范围内，因此超出范围的步进会落在首页/末页。大于 1 时，按钮的无障碍名称会反映跨步页数。非整数或小于 1 的值回退为 1。 |
| siblingCount | number | 1 | 当前页两侧显示的页码按钮数量。仅在 variant='pages' 时生效。 |
| size | 'sm' \| 'md' | 'md' | 分页控件的尺寸。 |
| isDisabled | boolean | false | 组件是否禁用。 |
| label | string | 'Pagination' | 导航地标的无障碍标签。 |
| xstyle | StyleXStyles |  | 用于布局自定义（外边距、定位、尺寸）的 StyleX 样式。必须是 stylex.create() 的值，而非内联样式对象如 style={{}}。 |

### 使用建议

- Place pagination below the content it controls so users see results before navigating.
- Use the pages variant for data tables where users need to jump to a specific page.
- Use the count variant with a page size selector when users need to control how many items they see at once.
- Use the dots variant for carousels and walkthroughs where the total is small and position matters more than a number.
- Pass totalItems when the total is known so users can see how much content remains.
- 避免：Show pagination when all items fit on a single page; there is nothing to paginate.
- 避免：Use the dots variant for more than about 10 pages; the dots become too small to be useful.
- 避免：Place pagination above the content; users expect it at the bottom.

### 主题 API

```json
{
  "targets": [
    {
      "className": "astryx-pagination",
      "visualProps": [
        "size",
        "variant"
      ]
    },
    {
      "className": "astryx-pagination-dot",
      "visualProps": [
        "size"
      ],
      "states": [
        "active"
      ]
    },
    {
      "className": "astryx-pagination-input-label",
      "visualProps": [
        "size"
      ]
    },
    {
      "className": "astryx-pagination-input-total",
      "visualProps": [
        "size"
      ]
    }
  ]
}
```

### 组件结构

- **Pagination**: Navigation landmark containing the current paging controls and optional page-size selector.
- **Page-size selector**: Optional Selector for choosing how many items appear per page.
- **First/last buttons**: Optional Button controls that jump to the first or last known page.
- **Previous/next buttons**: Button controls that move backward or forward through the pages.
- **Page number button**: Button for one directly selectable page in the numbered presentation.
- **Ellipsis**: Visual omission marker between non-adjacent page-number buttons.
- **Count readout**: Text showing the current item range and total item count.
- **Compact readout**: Text showing the current page and total page count.
- **Dot**: Page indicator control that reflects and changes the active page.
- **Page input label**: Leading visible label for the editable page-number field.
- **Page input**: NumberInput used to enter a page directly.
- **Page input total**: Trailing text showing the known total page count.


## 完整示例的额外依赖

部分示例使用独立图标包。示例清单中的每条安装命令包含该示例实际需要的依赖；若要运行本页全部示例，还需安装：

```bash
npm install @heroicons/react@2.2.0
```

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt