資料格 - 分頁

輕鬆為您的資料列分頁，並且只提取您需要的內容。

啟用分頁功能

預設分頁行為取決於您的方案

社群方案

對於社群資料格，分頁功能預設為啟用，且無法停用。

<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`	`布林值`	`數字`

已知資料列計數

如上表所述，將屬性傳遞至 Data Grid，以處理實際資料列計數已知的情況，如下列範例所示。

<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} />;

未知資料列計數

如上表所述，將屬性傳遞至 Data Grid，以處理實際資料列計數未知的情況，如下列範例所示。

<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 (如果它由某些外部提取 Hook 處理)，導致不必要的計算，一個可能的解決方案可能是記憶化 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} 時，Data Grid 的行為與「未知資料列計數」用例相同，但在分頁頁尾中顯示 estimatedRowCount 值。

如果載入的資料列數超過 estimatedRowCount，Data Grid 會忽略 estimatedRowCount，且行為與「未知資料列計數」用例相同。

當 hasNextPage 傳回 false 或 rowCount 設定為正數時，Data Grid 會切換到「已知資料列計數」行為。

在以下範例中，實際資料列計數為 1000，但 Data Grid 最初提供 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 鍵開始編輯

🌍 估計資料列計數的本地化

Data Grid 使用 Material UI 程式庫中的表格分頁元件，該元件不支援 estimated 資料列計數。在表格分頁元件原生支援此功能之前，使本地化運作的權宜之計是將 labelDisplayedRows 函式提供給 localeText.MuiTablePagination 屬性，根據您感興趣的地區設定。

Grid 會將額外的變數 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

Data Grid 公開了一組方法，可使用命令式 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)

關於選取器以及如何使用它們的更多資訊，請參閱專用頁面