資料格 - 列分組

根據某些欄位值將您的列分組。

適用於當您需要根據重複的欄位值和/或自訂函數來分組列時。在以下範例中，電影根據其製作公司分組

分組條件

初始化列分組

開始使用此功能的最簡單方法是將其模型提供給 initialState 屬性

<DataGridPremium
  initialState={{
    rowGrouping: {
      model: ['company', 'director'],
    },
  }}
/>

基本參數是您要檢查重複值的欄位。此範例將所有公司名稱相同的電影分組，然後再將導演名稱相同的電影分組。

受控列分組

如果您需要控制用於分組的條件狀態，請使用 rowGroupingModel 屬性。您可以使用 onRowGroupingModelChange 屬性來監聽分組條件的變更並相應地更新屬性。

分組欄

單一分組欄

預設情況下，資料格將顯示單一欄位，其中包含所有分組欄位。如果您有多個分組條件，則此欄位名稱將設定為「群組」。

多個分組欄

若要為每個分組條件顯示一個欄位，請將 rowGroupingColumnMode 屬性設定為 multiple。

自訂分組欄

若要自訂分組欄的呈現方式，請使用 groupingColDef 屬性。您可以覆寫 headerName 或 GridColDef 介面的任何屬性，但 field、type 以及與內嵌編輯相關的屬性除外。

預設情況下，當使用物件格式時，屬性將套用於所有分組欄。這表示如果您將 rowGroupingColumnMode 設定為 multiple，則所有欄位都將共用相同的 groupingColDef 屬性。

如果您希望覆寫特定分組欄的屬性，或根據目前的分組條件套用不同的覆寫，您可以將回呼函數傳遞給 groupingColDef，而不是包含其設定的物件。回呼會針對每個分組欄呼叫，並接收各欄位的「欄位」作為參數。

使用自訂儲存格渲染器分組列

預設情況下，當列依具有自訂儲存格組件 (GridColDef['renderCell']) 的欄位分組時，相同的自訂儲存格組件會用於分組欄中。

您可以選擇退出此預設行為，方法是在分組列的 renderCell 中傳回 params.value

const ratingColDef: GridColDef = {
  // ...
  renderCell: (params) => {
    if (params.rowNode.type === 'group') {
      return params.value;
    }

    return (
      // ...
    );
  },
};

顯示葉節點的值

預設情況下，分組列在其分組欄的儲存格中不顯示任何值。這些儲存格稱為「葉節點」。

如果您想要顯示某些值，您可以為 groupingColDef 提供 leafField 屬性。

隱藏後代計數

使用 groupingColDef 的 hideDescendantCount 屬性來隱藏分組列的後代數量。

隱藏分組欄

預設情況下，用於分組列的欄位保持可見。例如，如果您依 "director" 分組，則會有兩個標題為 Director 的欄位

• 分組欄（您從中分組列的欄位）
• 您可以在其上切換群組的分組欄

若要自動隱藏分組欄，請使用 useKeepGroupedColumnsHidden 實用工具 Hook。當 Hook 新增至模型時，會自動隱藏欄位，並在從模型中移除時顯示欄位。

以下是關於如何將 columnVisibilityModel 或 initialState 與 useKeepGroupedColumnsHidden Hook 搭配使用的兩個範例。您可以混合使用這兩個範例以同時支援兩者。

// Usage with the initial state
const apiRef = useGridApiRef();

const initialState = useKeepGroupedColumnsHidden({
  apiRef,
  initialState: {
    rowGrouping: {
      model: ['company'],
    },
    columns: {
      // Other hidden columns
      columnVisibilityModel: { gross: false },
    },
  },
});

return <DataGridPremium {...data} apiRef={apiRef} initialState={initialState} />;

// Usage with the controlled model
const apiRef = useGridApiRef();

const [rowGroupingModel, setRowGroupingModel] = React.useState([
  'company',
  'director',
]);

const initialState = useKeepGroupedColumnsHidden({
  apiRef,
  rowGroupingModel,
});

return (
  <DataGridPremium
    {...data}
    apiRef={apiRef}
    initialState={initialState}
    rowGroupingModel={rowGroupingModel}
  />
);

停用列分組

適用於所有欄位

您可以將 disableRowGrouping 屬性設定為 true 來停用列分組。

即使提供了模型，它也會停用所有與列分組相關的功能。

適用於某些欄位

如果您需要停用特定欄位上的分組，請將各欄位定義 (GridColDef) 上的 groupable 屬性設定為 false。在以下範例中，director 欄位無法分組。在所有範例中，title 和 gross 欄位都無法分組。

以程式設計方式分組不可分組的欄位

若要在不可分組的欄位（在欄位定義中具有 groupable: false 的欄位）上以程式設計方式套用列分組，您可以透過以下其中一種方式提供列分組模型

1. 將 rowGrouping.model 傳遞至 initialState 屬性。這將使用提供的模型初始化分組。
2. 提供 rowGroupingModel 屬性。這將使用提供的模型控制分組。
3. 呼叫 API 方法 setRowGroupingModel。這將使用提供的模型設定彙總。

在以下範例中，欄位 company 無法從 UI 分組，但會傳遞 rowGroupingModel 屬性以產生唯讀列群組。

針對複雜分組值使用 groupingValueGetter

分組值必須是 string、number、null 或 undefined。如果您的儲存格值更複雜，請將 groupingValueGetter 屬性傳遞至欄位定義，以將其轉換為有效值。

const columns: GridColDef[] = [
  {
    field: 'composer',
    groupingValueGetter: (value) => value.name,
  },
  // ...
];

具有遺失群組的列

如果列的分組條件的分組鍵為 null 或 undefined，則資料格會認為此列沒有此群組的值，並將針對這些群組內嵌該列。

群組展開

預設情況下，所有群組最初都會顯示為摺疊狀態。您可以變更此行為，方法是設定 defaultGroupingExpansionDepth 屬性，以在載入資料時將所有群組展開至給定的深度。如果您想要展開整個樹狀結構，請設定 defaultGroupingExpansionDepth = -1

如果您想要根據更複雜的邏輯依預設展開群組，請使用 isGroupExpandedByDefault 屬性，此屬性是接收節點作為引數的回呼。定義後，此回呼將始終優先於 defaultGroupingExpansionDepth 屬性。

isGroupExpandedByDefault={
  node => node.groupingField === 'company' && node.groupingKey === '20th Century Fox'
}

在 apiRef 上使用 setRowChildrenExpansion 方法，以程式設計方式設定列的展開。變更列的展開會發出 rowExpansionChange 事件，監聽此事件以對展開變更做出反應。

自訂分組儲存格縮排

若要變更預設儲存格縮排，您可以使用 --DataGrid-cellOffsetMultiplier CSS 變數

<DataGridPremium
  sx={{
    // default value is 2
    '--DataGrid-cellOffsetMultiplier': 6,
  }}
/>

排序 / 篩選

單一分組欄

當使用 rowGroupingColumnMode = "single" 時，預設行為是

• 使用欄位的 sortComparator 排序每個分組條件
• 套用最上層分組條件的 filterOperators

如果您使用 groupingColDef 的 leafField 屬性來呈現葉節點，則排序和篩選將根據其原始欄位的 sortComparator 和 filterOperators 套用於葉節點。

您可以使用 groupingColDef 的 mainGroupingCriteria 屬性，強制篩選套用於另一個分組條件

多個分組欄

當使用 rowGroupingColumnMode = "multiple" 時，預設行為是套用每個分組欄的分組條件的 sortComparator 和 filterOperators。

如果您使用 groupingColDef 的 leafField 屬性在其中一個欄位上呈現葉節點，則排序和篩選將根據葉節點原始欄位的 sortComparator 和 filterOperators 套用於此分組欄的葉節點。

如果您想要呈現葉節點，但將排序和篩選套用於欄位的分組條件，您可以強制執行此操作，方法是將 mainGroupingCriteria 屬性 groupingColDef 設定為等於分組條件。

在以下範例中

• company 分組欄的排序和篩選會套用於 company 欄位
• 即使 director 分組欄具有葉節點，其排序和篩選仍會套用於 director 欄位

自動父項和子項選取

預設情況下，選取父列不會選取其子項。您可以使用 rowSelectionPropagation 屬性來覆寫此行為。

以下是其結構

type GridRowSelectionPropagation = {
  descendants?: boolean; // default: false
  parents?: boolean; // default: false
};

當 rowSelectionPropagation.descendants 設定為 true 時。

• 選取父項會自動選取其所有已篩選的後代。
• 取消選取父列會自動取消選取其所有已篩選的後代。

當 rowSelectionPropagation.parents 設定為 true 時。

• 選取父項的所有已篩選後代會自動選取父項。
• 取消選取已選取父項的後代會自動取消選取父項。

以下範例示範如何使用 rowSelectionPropagation 屬性。

取得群組中的列

您可以使用 apiRef.current.getRowGroupChildren 方法來取得群組中包含的所有列的 ID。它不會包含自動產生的列（即子群組列或彙總頁尾）。

const rows: GridRowId[] = apiRef.current.getRowGroupChildren({
  groupId: params.id,

  // If true, the rows will be in the order displayed on screen
  applySorting: true,

  // If true, only the rows matching the current filters will be returned
  applyFiltering: true,
});

如果您想要取得指定群組條件的群組的列 ID，請使用 getGroupRowIdFromPath

const rows = apiRef.current.getRowGroupChildren({
  groupId: getGroupRowIdFromPath([{ field: 'company', key: 'Disney Studios' }]),
});

列群組面板 🚧

透過此面板，您的使用者將能夠僅透過將欄位拖曳到面板內來控制哪些欄位用於分組。

v8 中的協助工具變更

具有列分組功能的資料格 v8 將改善協助工具，並將更符合 WAI-ARIA 撰寫實務。

您可以透過啟用 ariaV8 實驗性功能標誌來開始使用新的協助工具功能

<DataGridPremium experimentalFeatures={{ ariaV8: true }} />

完整範例

進階使用案例

如需更多進階使用案例，請參閱列分組範例。

apiRef

網格公開了一組方法，可使用命令式 apiRef 啟用所有這些功能。若要瞭解如何使用它，請查看API 物件區段。

API

• DataGrid
• DataGridPro
• DataGridPremium