JGuang
EN

分页

Pagination · Astryx

交互预览
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

分页 · Pagination

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

安装与前置条件

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

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

  • 分页 · 样式变化 / 分页 / 样式 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 实现内置加载状态。
totalItemsnumber总项目数。用于计算页数。同时提供时优先于 totalPages。
totalPagesnumber总页数。当你知道页数但不知道项目数时使用。
hasMoreboolean当前页之后是否还有更多页。用于总数未知的游标分页。
pageSizenumber10每页项目数。强制转换为正整数；非有限值回退到默认值。
pageSizeOptionsnumber[]可用的每页大小选项。提供时显示每页大小选择器下拉菜单。
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' 仅显示上一页/下一页按钮。
pageLabelstring'input' 变体中可编辑框前显示的名词，如 'Page' 或 'Row'。导航始终基于页码（通过 onChange）；此项仅用于重新标注。默认为本地化的 'Page'。
hasFirstLastbooleantrue是否显示首页/末页（«/»）双箭头按钮，位于上一页/下一页两侧。仅适用于 'input' 变体；当页数未知（游标/hasMore 分页）时省略。
stepnumber1上一页/下一页按钮每次点击前进的页数。会被限制在有效页码范围内，因此超出范围的步进会落在首页/末页。大于 1 时，按钮的无障碍名称会反映跨步页数。非整数或小于 1 的值回退为 1。
siblingCountnumber1当前页两侧显示的页码按钮数量。仅在 variant='pages' 时生效。
size'sm' | 'md''md'分页控件的尺寸。
isDisabledbooleanfalse组件是否禁用。
labelstring'Pagination'导航地标的无障碍标签。
xstyleStyleXStyles用于布局自定义（外边距、定位、尺寸）的 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

{
  "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.

完整示例的额外依赖

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

npm install @heroicons/react@2.2.0