数据表格 - 分页

轻松地对行进行分页，并且只获取您需要的内容。

启用分页

默认的分页行为取决于您的计划

社区计划

对于社区数据表格，分页默认启用且无法禁用。

<DataGrid {...data} loading={loading} />

<DataGrid {...data} loading={loading} />

按 Enter 开始编辑

Pro 和 Premium

对于 Pro 和 Premium 数据表格，分页默认禁用；使用 pagination 属性启用它。

<DataGridPremium
  pagination
  rows={rows}
  columns={columns}
  slots={{ toolbar: CustomToolbar }}
  autoPageSize
/>

<DataGridPremium
  pagination
  rows={rows}
  columns={columns}
  slots={{ toolbar: CustomToolbar }}
  autoPageSize
/>

按 Enter 开始编辑

页面大小

Data Grid（MIT 许可证）限制为最多 100 行的页面。如果您想要更大的页面，您需要升级到 Pro 计划或更高级别。

默认情况下，每个页面包含 100 行。用户可以通过页脚中的选择器更改页面大小。

页面大小选项

您可以使用 pageSizeOptions 属性自定义 “每页行数” 选择器中显示的选项。您应该提供一个项目数组，每个项目应为以下类型之一

number，每个数字将用于选项的标签和值。
```
<DataGrid pageSizeOptions={[5, 10, 25]}>
```
object，value 和 label 键将分别用于选项的值和标签。将 value 定义为 -1 以显示所有结果。
```
<DataGrid pageSizeOptions={[10, 100, { value: 1000, label: '1,000' }, { value: -1, label: 'All' }]}>
```

<DataGrid
  {...data}
  loading={loading}
  initialState={{
    ...data.initialState,
    pagination: { paginationModel: { pageSize: 5 } },
  }}
  pageSizeOptions={[5, 10, 25, { value: -1, label: 'All' }]}
/>

<DataGrid
  {...data}
  loading={loading}
  initialState={{
    ...data.initialState,
    pagination: { paginationModel: { pageSize: 5 } },
  }}
  pageSizeOptions={[5, 10, 25, { value: -1, label: 'All' }]}
/>

按 Enter 开始编辑

自动页面大小

使用 autoPageSize 属性自动缩放 pageSize 以匹配容器高度和无需垂直滚动条即可显示的最大行数。

容器的高度

分页模型

分页模型是一个对象，包含当前页面和页面大小。默认值为 { page: 0, pageSize: 100 }。要更改默认值，使其由 paginationModel 属性控制，或使用 initialState.pagination.paginationModel 初始化自定义值。

初始化分页模型

要在不控制分页模型的情况下初始化它，请将 paginationModel 提供给 initialState 属性。如果您没有为其中一个属性提供值，则将使用默认值。

<DataGrid
  initialState={{
    pagination: {
      paginationModel: { pageSize: 25, page: 0 },
    },
  }}
/>

<DataGrid
  {...data}
  loading={loading}
  initialState={{
    ...data.initialState,
    pagination: {
      ...data.initialState?.pagination,
      paginationModel: {
        pageSize: 25,
        /* page: 0 // default value will be used if not passed */
      },
    },
  }}
/>

<DataGrid
  {...data}
  loading={loading}
  initialState={{
    ...data.initialState,
    pagination: {
      ...data.initialState?.pagination,
      paginationModel: {
        pageSize: 25,
        /* page: 0 // default value will be used if not passed */
      },
    },
  }}
/>

按 Enter 开始编辑

受控分页模型

传递 paginationModel 属性以控制网格的大小和当前页面。您可以使用 onPaginationModelChange 属性来监听 paginationModel 的更改并相应地更新属性。

const [paginationModel, setPaginationModel] = React.useState({
  pageSize: 25,
  page: 0,
});

<DataGrid
  paginationModel={paginationModel}
  onPaginationModelChange={setPaginationModel}
/>;

<DataGrid
  paginationModel={paginationModel}
  onPaginationModelChange={setPaginationModel}
  {...data}
  loading={loading}
/>

<DataGrid
  paginationModel={paginationModel}
  onPaginationModelChange={setPaginationModel}
  {...data}
  loading={loading}
/>

按 Enter 开始编辑

服务端分页

默认情况下，分页在客户端处理。这意味着您必须将所有页面的行提供给数据表格。如果您的数据集太大，并且您想按需获取页面，则可以使用服务端分页。

<DataGrid
  rows={rows}
  {...data}
  rowCount={rowCount}
  loading={isLoading}
  pageSizeOptions={[5]}
  paginationModel={paginationModel}
  sortModel={sortModel}
  filterModel={filterModel}
  paginationMode="server"
  sortingMode="server"
  filterMode="server"
  onPaginationModelChange={setPaginationModel}
  onSortModelChange={setSortModel}
  onFilterModelChange={setFilterModel}
/>

<DataGrid
  rows={rows}
  {...data}
  rowCount={rowCount}
  loading={isLoading}
  pageSizeOptions={[5]}
  paginationModel={paginationModel}
  sortModel={sortModel}
  filterModel={filterModel}
  paginationMode="server"
  sortingMode="server"
  filterMode="server"
  onPaginationModelChange={setPaginationModel}
  onSortModelChange={setSortModel}
  onFilterModelChange={setFilterModel}
/>

按 Enter 开始编辑

一般来说，服务端分页可以分为两种类型

基于索引的分页
基于游标的分页

基于索引的分页

基于索引的分页使用 page 和 pageSize 从服务器逐页获取数据。

要启用服务端分页，您需要

将 paginationMode 属性设置为 server
使用 onPaginationModelChange 属性来响应页面更改并从服务器加载数据

服务端分页可以根据总行数或 rowCount 的可用性进一步细分为子类型。

数据表格使用 rowCount 来计算页数，并在页脚中显示有关分页当前状态的信息。您可以通过以下方式之一提供 rowCount

初始化。 使用 initialState.pagination.rowCount 属性初始化 rowCount。
控制。 将 rowCount 属性与 onRowCountChange 一起使用以控制 rowCount，并在行数更新时反映更改。
使用 API 设置。 在网格初始化后，使用 apiRef.current.setRowCount 方法设置 rowCount。

关于服务端 rowCount 的可用性，可能存在三种不同的可能性

行数可用（已知）
行数不可用（未知）
行数可用但不准确，可能会在稍后更新（估计）

您可以配置 rowCount、paginationMeta.hasNextPage 和 estimatedRowCount 属性来处理上述场景。

	`rowCount`	`paginationMeta.hasNextPage`	`estimatedRowCount`
已知行数	`数字`	—	—
未知行数	`-1`	`布尔值`	—
估计行数	`-1`	`布尔值`	`数字`

已知行数

按照上表中的说明，将属性传递给数据表格，以处理实际行数已知的情况，如以下示例所示。

<DataGrid
  rows={rows}
  {...data}
  rowCount={rowCount}
  loading={isLoading}
  pageSizeOptions={[5]}
  paginationModel={paginationModel}
  paginationMode="server"
  onPaginationModelChange={setPaginationModel}
/>

<DataGrid
  rows={rows}
  {...data}
  rowCount={rowCount}
  loading={isLoading}
  pageSizeOptions={[5]}
  paginationModel={paginationModel}
  paginationMode="server"
  onPaginationModelChange={setPaginationModel}
/>

按 Enter 开始编辑

如果值 rowCount 在加载期间变为 undefined，它将把页面重置为零。为避免此问题，您可以记忆化 rowCount 值，以确保它在加载期间不会更改

const rowCountRef = React.useRef(pageInfo?.totalRowCount || 0);

const rowCount = React.useMemo(() => {
  if (pageInfo?.totalRowCount !== undefined) {
    rowCountRef.current = pageInfo.totalRowCount;
  }
  return rowCountRef.current;
}, [pageInfo?.totalRowCount]);

<DataGrid rowCount={rowCount} />;

未知行数

按照上表中的说明，将属性传递给数据表格，以处理实际行数未知的情况，如以下示例所示。

<DataGrid
  apiRef={apiRef}
  rows={rows}
  {...data}
  initialState={{ ...data.initialState, pagination: { rowCount: -1 } }}
  paginationMeta={paginationMeta}
  loading={isLoading}
  pageSizeOptions={[5, 10, 25, 50]}
  paginationModel={paginationModel}
  paginationMode="server"
  onPaginationModelChange={setPaginationModel}
/>

<DataGrid
  apiRef={apiRef}
  rows={rows}
  {...data}
  initialState={{ ...data.initialState, pagination: { rowCount: -1 } }}
  paginationMeta={paginationMeta}
  loading={isLoading}
  pageSizeOptions={[5, 10, 25, 50]}
  paginationModel={paginationModel}
  paginationMode="server"
  onPaginationModelChange={setPaginationModel}
/>

按 Enter 开始编辑

如果 hasNextPage 变量的值在加载期间可能变为 undefined（如果它由某些外部获取钩子处理），从而导致不必要的计算，一种可能的解决方案是记忆化 paginationMeta

const paginationMetaRef = React.useRef<GridPaginationMeta>();

const paginationMeta = React.useMemo(() => {
  if (
    hasNextPage !== undefined &&
    paginationMetaRef.current?.hasNextPage !== hasNextPage
  ) {
    paginationMetaRef.current = { hasNextPage };
  }
  return paginationMetaRef.current;
}, [hasNextPage]);

估计行数

估计行数可以被认为是 “已知行数” 和 “未知行数” 用例之间切换的混合方法。

最初，当设置了 estimatedRowCount 且 rowCount={-1} 时，数据表格的行为类似于 “未知行数” 用例，但在分页页脚中显示 estimatedRowCount 值。

如果加载的行数超过 estimatedRowCount，则数据表格将忽略 estimatedRowCount，并且行为与 “未知行数” 用例相同。

当 hasNextPage 返回 false 或 rowCount 设置为正数时，数据表格将切换到 “已知行数” 行为。

在以下示例中，实际行数为 1000，但数据表格最初提供的是 estimatedRowCount={100}。您可以通过按 “设置行数” 按钮将 rowCount 设置为实际行数。

<Button onClick={() => apiRef.current.setRowCount(1000)}>Set Row Count</Button>
<div style={{ height: 400 }}>
  <DataGrid
    apiRef={apiRef}
    rows={rows}
    {...data}
    initialState={{ ...data.initialState, pagination: { rowCount: -1 } }}
    estimatedRowCount={100}
    paginationMeta={paginationMeta}
    loading={isLoading}
    pageSizeOptions={[10, 25, 50, 100]}
    paginationModel={paginationModel}
    paginationMode="server"
    onPaginationModelChange={setPaginationModel}
  />
</div>

<Button onClick={() => apiRef.current.setRowCount(1000)}>Set Row Count</Button>
<div style={{ height: 400 }}>
  <DataGrid
    apiRef={apiRef}
    rows={rows}
    {...data}
    initialState={{ ...data.initialState, pagination: { rowCount: -1 } }}
    estimatedRowCount={100}
    paginationMeta={paginationMeta}
    loading={isLoading}
    pageSizeOptions={[10, 25, 50, 100]}
    paginationModel={paginationModel}
    paginationMode="server"
    onPaginationModelChange={setPaginationModel}
  />
</div>

按 Enter 开始编辑

🌍 估计行数的本地化

数据表格使用 Material UI 库中的 Table Pagination 组件，该组件不支持 estimated 行数。在 Table Pagination 组件原生支持之前，使本地化工作的一种解决方法是将 labelDisplayedRows 函数提供给 localeText.MuiTablePagination 属性，按照您感兴趣的语言环境进行操作。

网格将额外的变量 estimated 注入到 labelDisplayedRows 函数中，您可以使用该变量来容纳估计的行数。以下示例演示了如何在克罗地亚语 (hr-HR) 的分页页脚中显示估计的行数。

const labelDisplayedRows = ({ from, to, count, estimated }) => {
  if (!estimated) {
    return `${from}–${to} od ${count !== -1 ? count : `više nego ${to}`}`,
  }
  return `${from}–${to} od ${count !== -1 ? count : `više nego ${estimated > to ? estimated : to}`}`;
}

<DataGrid
  {...data}
  localeText={{
    MuiTablePagination: {
      labelDisplayedRows,
    },
  }}
/>

有关更多信息，请参阅本地化文档的翻译键部分。

基于游标的分页

您还可以处理具有基于游标的分页的服务器。为此，您只需跟踪与您获取的每个页面关联的下一个游标。

行数

已知未知估计

自定义分页 UI

您可以按照文档的组件部分自定义页脚中分页的渲染。

apiRef

数据表格公开了一组方法，可以使用命令式 apiRef 启用所有这些功能。要了解有关如何使用它的更多信息，请查看 API 对象部分。

setPage()

将显示的页面设置为 page 给定的值。

签名

setPage: (page: number) => void

setPageSize()

将显示的行数设置为 pageSize 给定的值。

签名

setPageSize: (pageSize: number) => void

setPaginationMeta()

将 paginationMeta 设置为新值。

签名

setPaginationMeta: (paginationMeta: GridPaginationMeta) => void

setPaginationModel()

将 paginationModel 设置为新值。

签名

setPaginationModel: (model: GridPaginationModel) => void

setRowCount()

将 rowCount 设置为新值。

签名

setRowCount: (rowCount: number) => void

选择器

gridPageCountSelector

如果启用了分页，则获取显示所有行所需的页数

签名

gridPageCountSelector: (apiRef: GridApiRef) => number
// or
gridPageCountSelector: (state: GridState, instanceId?: number) => number

示例

gridPageCountSelector(apiRef)
// or
gridPageCountSelector(state, apiRef.current.instanceId)

gridPageSelector

如果启用了分页，则获取要渲染的页面的索引

签名

gridPageSelector: (apiRef: GridApiRef) => number
// or
gridPageSelector: (state: GridState, instanceId?: number) => number

示例

gridPageSelector(apiRef)
// or
gridPageSelector(state, apiRef.current.instanceId)

gridPageSizeSelector

如果启用了分页，则获取单页上显示的最大行数

签名

gridPageSizeSelector: (apiRef: GridApiRef) => number
// or
gridPageSizeSelector: (state: GridState, instanceId?: number) => number

示例

gridPageSizeSelector(apiRef)
// or
gridPageSizeSelector(state, apiRef.current.instanceId)

gridPaginatedVisibleSortedGridRowEntriesSelector

如果启用了分页，则获取当前页中包含的每一行的 id 和模型。

签名

gridPaginatedVisibleSortedGridRowEntriesSelector: (apiRef: GridApiRef) => GridRowEntry<GridValidRowModel>[]
// or
gridPaginatedVisibleSortedGridRowEntriesSelector: (state: GridState, instanceId?: number) => GridRowEntry<GridValidRowModel>[]

示例

gridPaginatedVisibleSortedGridRowEntriesSelector(apiRef)
// or
gridPaginatedVisibleSortedGridRowEntriesSelector(state, apiRef.current.instanceId)

gridPaginatedVisibleSortedGridRowIdsSelector

如果启用了分页，则获取当前页中包含的每一行的 id。

签名

gridPaginatedVisibleSortedGridRowIdsSelector: (apiRef: GridApiRef) => GridRowId[]
// or
gridPaginatedVisibleSortedGridRowIdsSelector: (state: GridState, instanceId?: number) => GridRowId[]

示例

gridPaginatedVisibleSortedGridRowIdsSelector(apiRef)
// or
gridPaginatedVisibleSortedGridRowIdsSelector(state, apiRef.current.instanceId)

gridPaginationMetaSelector

获取分页元数据

签名

gridPaginationMetaSelector: (apiRef: GridApiRef) => GridPaginationMeta
// or
gridPaginationMetaSelector: (state: GridState, instanceId?: number) => GridPaginationMeta

示例

gridPaginationMetaSelector(apiRef)
// or
gridPaginationMetaSelector(state, apiRef.current.instanceId)

gridPaginationModelSelector

获取分页模型

签名

gridPaginationModelSelector: (apiRef: GridApiRef) => GridPaginationModel
// or
gridPaginationModelSelector: (state: GridState, instanceId?: number) => GridPaginationModel

示例

gridPaginationModelSelector(apiRef)
// or
gridPaginationModelSelector(state, apiRef.current.instanceId)

gridPaginationRowCountSelector

获取行数

签名

gridPaginationRowCountSelector: (apiRef: GridApiRef) => number
// or
gridPaginationRowCountSelector: (state: GridState, instanceId?: number) => number

示例

gridPaginationRowCountSelector(apiRef)
// or
gridPaginationRowCountSelector(state, apiRef.current.instanceId)

gridPaginationRowRangeSelector

如果启用了分页，则获取当前页中包含的第一行和最后一行索引。

签名

gridPaginationRowRangeSelector: (apiRef: GridApiRef) => { firstRowIndex: number; lastRowIndex: number } | null
// or
gridPaginationRowRangeSelector: (state: GridState, instanceId?: number) => { firstRowIndex: number; lastRowIndex: number } | null

示例

gridPaginationRowRangeSelector(apiRef)
// or
gridPaginationRowRangeSelector(state, apiRef.current.instanceId)

gridVisibleRowsSelector

获取筛选和排序后的行、范围和 rowIndex 查找表。不包含折叠的子项。

签名

gridVisibleRowsSelector: (apiRef: GridApiRef) => { rows: GridRowEntry<GridValidRowModel>[]; range: { firstRowIndex: number; lastRowIndex: number } | null; rowToIndexMap: Map<GridValidRowModel, number> }
// or
gridVisibleRowsSelector: (state: GridState, instanceId?: number) => { rows: GridRowEntry<GridValidRowModel>[]; range: { firstRowIndex: number; lastRowIndex: number } | null; rowToIndexMap: Map<GridValidRowModel, number> }

示例

gridVisibleRowsSelector(apiRef)
// or
gridVisibleRowsSelector(state, apiRef.current.instanceId)

有关选择器以及如何使用它们的更多信息，请访问专用页面