数据表格 - 行分组

根据某些列值对行进行分组。

当您需要根据重复的列值和/或自定义函数对行进行分组时使用。在以下示例中，电影根据其制作公司进行分组

分组条件

初始化行分组

开始使用此功能的最简单方法是将模型提供给 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 应用于此分组列的叶节点。

如果您想渲染叶节点，但将排序和筛选应用于列的分组条件，您可以通过将 groupingColDef 的 mainGroupingCriteria 属性设置为等于分组条件来强制执行此操作。

在以下示例中

• 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