Data Grid - 狀態

初始化和讀取 Data Grid 的狀態。

初始化狀態

某些狀態鍵可以使用 initialState 屬性初始化。此屬性的格式與 apiRef.current.exportState() 的回傳值相同。

<DataGrid
  {...data}
  loading={loading}
  initialState={{
    ...data.initialState,
    filter: {
      filterModel: {
        items: [{ field: 'quantity', operator: '>', value: 10000 }],
      },
    },
    sorting: {
      sortModel: [{ field: 'desk', sort: 'asc' }],
    },
  }}
/>

<DataGrid
  {...data}
  loading={loading}
  initialState={{
    ...data.initialState,
    filter: {
      filterModel: {
        items: [{ field: 'quantity', operator: '>', value: 10000 }],
      },
    },
    sorting: {
      sortModel: [{ field: 'desk', sort: 'asc' }],
    },
  }}
/>

按下 Enter 開始編輯

存取狀態

狀態在 apiRef 物件上公開。

@mui/x-data-grid-pro 套件公開了一組狀態選擇器，這些選擇器將 apiRef.current.state 作為參數並回傳一個值。您可以使用它們從狀態中取得資料，而無需擔心其內部結構。

直接選擇器存取

使用選擇器的最簡單方法是以函數形式呼叫它，並以 apiRef 作為其第一個參數

const paginationModel = gridPaginationModelSelector(apiRef);

使用 apiRef.current.state 呼叫也可以，但當單個頁面上存在多個 Data Grid 實例時，可能會導致副作用。如果您仍然需要使用狀態呼叫它，請不要忘記傳遞實例 ID 作為範例

const paginationModel = gridPaginationModelSelector(
  apiRef.current.state,
  apiRef.current.instanceId,
);

使用 useGridSelector

如果您只需要在組件的渲染中存取狀態值，請使用 useGridSelector Hook。此 Hook 確保存在反應式綁定，以便在狀態變更時，使用此 Hook 的組件會重新渲染。

const paginationModel = useGridSelector(apiRef, gridPaginationModelSelector);

<DataGrid
  {...data}
  loading={loading}
  paginationModel={paginationModel}
  onPaginationModelChange={setPaginationModel}
  hideFooter
  slots={{
    toolbar: Toolbar,
  }}
/>

<DataGrid
  {...data}
  loading={loading}
  paginationModel={paginationModel}
  onPaginationModelChange={setPaginationModel}
  hideFooter
  slots={{
    toolbar: Toolbar,
  }}
/>

按下 Enter 開始編輯

選擇器目錄

某些選擇器尚未記錄。

彙總

gridAggregationLookupSelector

取得彙總結果作為查找表。

簽名

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

範例

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

gridAggregationModelSelector

取得彙總模型，其中包含每欄的彙總函數。如果欄不在模型中，則不會彙總。

簽名

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

範例

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

欄

gridColumnDefinitionsSelector

取得螢幕上渲染順序的欄定義陣列。

簽名

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

範例

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

gridColumnFieldsSelector

取得螢幕上渲染順序的欄欄位陣列。

簽名

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

範例

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

gridColumnLookupSelector

取得欄作為查找表（一個物件，其中包含欄位作為鍵，定義作為值）。

簽名

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

範例

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

gridColumnsStateSelector

取得欄狀態

簽名

gridColumnsStateSelector: (state: GridState) => GridColumnsState

範例

const columnsState = gridColumnsStateSelector(apiRef.current.state);

gridFilterableColumnDefinitionsSelector

取得可篩選的欄作為陣列。

簽名

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

範例

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

gridFilterableColumnLookupSelector

取得可篩選的欄作為查找表（一個物件，其中包含欄位作為鍵，定義作為值）。

簽名

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

範例

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

可見欄

gridColumnPositionsSelector

取得每個可見欄的左側位置（以像素為單位），相對於第一欄的左側。

簽名

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

範例

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

gridColumnVisibilityModelSelector

取得欄可見性模型，其中包含每欄的可見性狀態。如果欄未在模型中註冊，則為可見。

簽名

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

範例

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

gridColumnsTotalWidthSelector

取得所有可見欄的總寬度。

簽名

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

範例

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

gridPinnedColumnsSelector

取得可見的釘選欄模型。

簽名

gridPinnedColumnsSelector: (state: GridState) => GridPinnedColumnFields

範例

const pinnedColumns = gridPinnedColumnsSelector(apiRef.current.state);

gridVisibleColumnDefinitionsSelector

取得可見欄作為查找表（一個物件，其中包含欄位作為鍵，定義作為值）。

簽名

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

範例

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

gridVisibleColumnFieldsSelector

取得每個可見欄的欄位。

簽名

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

範例

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

gridVisiblePinnedColumnDefinitionsSelector

取得可見的釘選欄。

簽名

gridVisiblePinnedColumnDefinitionsSelector: (apiRef: GridApiRef) => { left: GridStateColDef[]; right: GridStateColDef[] }
// or
gridVisiblePinnedColumnDefinitionsSelector: (state: GridState, instanceId?: number) => { left: GridStateColDef[]; right: GridStateColDef[] }

範例

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

篩選

gridExpandedRowCountSelector

取得篩選過程後可存取的列數。

簽名

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

範例

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

gridExpandedSortedRowEntriesSelector

取得篩選過程後可存取的列的 ID 和模型。不包含摺疊的子項。

簽名

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

範例

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

gridExpandedSortedRowIdsSelector

取得篩選過程後可存取的列的 ID。不包含摺疊的子項。

簽名

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

範例

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

gridFilterModelSelector

取得目前的篩選模型。

簽名

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

範例

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

gridFilteredDescendantRowCountSelector

取得篩選過程後可存取的子代列數。

簽名

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

範例

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

gridFilteredRowCountSelector

取得篩選過程後可存取的列數。包含頂層和子代列。

簽名

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

範例

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

gridFilteredSortedRowEntriesSelector

取得篩選過程後可存取的列的 ID 和模型。包含摺疊的子項。

簽名

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

範例

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

gridFilteredSortedRowIdsSelector

取得篩選過程後可存取的列的 ID。包含摺疊的子項。

簽名

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

範例

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

gridFilteredSortedTopLevelRowEntriesSelector

取得篩選過程後可存取的頂層列的 ID 和模型。

簽名

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

範例

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

gridFilteredTopLevelRowCountSelector

取得篩選過程後可存取的頂層列數。

簽名

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

範例

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

gridQuickFilterValuesSelector

取得目前的快速篩選值。

簽名

gridQuickFilterValuesSelector: (apiRef: GridApiRef) => any[] | undefined
// or
gridQuickFilterValuesSelector: (state: GridState, instanceId?: number) => any[] | undefined

範例

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

分頁

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)

排序

gridSortModelSelector

取得目前的排序模型。

簽名

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

範例

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

gridSortedRowEntriesSelector

取得排序過程後的列的 ID 和模型。

簽名

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

範例

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

gridSortedRowIdsSelector

取得排序過程後的列的 ID。

簽名

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

範例

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

虛擬化

gridVirtualizationColumnEnabledSelector

取得欄虛擬化的啟用狀態

簽名

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

範例

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

gridVirtualizationEnabledSelector

取得虛擬化的啟用狀態

簽名

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

範例

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

gridVirtualizationRowEnabledSelector

取得列虛擬化的啟用狀態

簽名

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

範例

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

gridVirtualizationSelector

取得欄狀態

簽名

gridVirtualizationSelector: (state: GridState) => GridVirtualizationState

範例

const virtualization = gridVirtualizationSelector(apiRef.current.state);

儲存和還原狀態

可以使用 apiRef.current.exportState() 匯出 Data Grid 的目前狀態。然後可以透過將回傳值傳遞給 initialState 屬性或 apiRef.current.restoreState() 方法來還原它。

請注意受控模型及其回調（例如，如果您使用 filterModel，則為 onFilterModelChange），因為 Data Grid 在還原狀態時會呼叫這些回調。但是，如果未定義回調，或者呼叫它沒有更新屬性值，則不會套用還原的值。

使用 initialState 還原狀態

您可以將 apiRef.current.exportState() 回傳的狀態傳遞給 initialState 屬性。

在下面的示範中，點擊重新建立第二個網格將使用第一個網格的目前狀態重新掛載第二個 Data Grid。

從外部儲存空間儲存和還原狀態

您可以使用 apiRef.current.exportState() 將狀態快照儲存到外部儲存空間（例如使用本機儲存空間或 Redux）。這樣，狀態可以在重新整理或導航到另一個頁面時持久保存。

在以下示範中，狀態會儲存到 localStorage，並在頁面重新整理時還原。這是透過監聽 beforeunload 事件來完成的。當組件卸載時，將改為使用 useLayoutEffect 清理函數。

使用 apiRef 還原狀態

您可以將 apiRef.current.exportState() 回傳的狀態傳遞給 apiRef.current.restoreState 方法。在下面的示範中，點擊儲存目前視圖將建立狀態中所做變更的快照，並考量初始狀態。您可以稍後在 Data Grid 上套用這些變更，方法是在自訂視圖選單中選取已儲存的視圖。

還原部分狀態

可以使用 apiRef.current.restoreState() 方法還原狀態的特定屬性。例如，僅還原釘選欄

apiRef.current.restoreState({
  pinnedColumns: ['brand'],
});