数据表格 - 单元格选择

允许用户选择单个单元格或单元格范围。

启用单元格选择

默认情况下，数据表格允许用户选择单个行。使用 Data Grid Premium，您可以应用 cellSelection 属性以允许用户选择单个单元格或单元格范围。

<DataGridPremium cellSelection />

选择单元格

应用 cellSelection 属性后，用户可以通过单击单元格来选择单个单元格，或者在单元格处于焦点时按下 Shift+Space。按住 Cmd (或 Windows 上的 Ctrl) 并单击单元格以选择多个单元格。按住 Cmd (或 Windows 上的 Ctrl) 并单击选定的单元格以取消选择。

要选择单元格范围，用户可以

单击一个单元格，将鼠标拖动到附近的单元格上，然后释放。
单击一个单元格，然后按住 Shift 并单击另一个单元格。如果单击第三个单元格，则选择将从上次单击的单元格重新开始。
使用箭头键将焦点放在一个单元格上，然后按住 Shift 并导航到另一个单元格——如果 Shift 被释放并再次按下，则选择将从上次聚焦的单元格重新开始。

尝试在下面的演示中执行各种操作以选择单元格——您可以切换行选择的开启和关闭，以查看这两个选择功能如何并行工作。

<Button sx={{ mb: 1 }} onClick={() => setRowSelection(!rowSelection)}>
  Toggle row selection
</Button>
<div style={{ height: 400 }}>
  <DataGridPremium
    rowSelection={rowSelection}
    checkboxSelection={rowSelection}
    cellSelection
    {...data}
  />
</div>

<Button sx={{ mb: 1 }} onClick={() => setRowSelection(!rowSelection)}>
  Toggle row selection
</Button>
<div style={{ height: 400 }}>
  <DataGridPremium
    rowSelection={rowSelection}
    checkboxSelection={rowSelection}
    cellSelection
    {...data}
  />
</div>

按 Enter 开始编辑

控制单元格选择

您可以使用 cellSelectionModel 属性控制选择哪些单元格。此属性接受一个对象，其键对应于包含所选单元格的行 ID。每个键的值本身也是一个对象，该对象具有作为键的列字段和作为其选择状态的布尔值。您可以将其设置为 true 以选择单元格或 false 以取消选择。从对象中删除该字段也会取消选择单元格。

// Selects the cell with field=name from row with id=1
<DataGridPremium cellSelectionModel={{ 1: { name: true } }} />

// Unselects the cell with field=name from row with id=1
<DataGridPremium cellSelectionModel={{ 1: { name: false } }} />

当进行新的选择时，传递给 onCellSelectionModelChange 属性的回调将使用更新后的模型进行调用。使用此值来更新当前模型。

以下演示展示了如何组合这些属性来创建一个类似 Excel 的公式字段——尝试通过选择多个单元格并在顶部的字段中输入新值来一次更新多个单元格。

选定的单元格值

自定义范围样式

当多个选定的单元格形成任何大小的连续范围时，以下类名将应用于边缘的单元格

MuiDataGrid-cell--rangeTop：应用于范围第一行中的所有单元格
MuiDataGrid-cell--rangeBottom：应用于范围最后一行中的所有单元格
MuiDataGrid-cell--rangeLeft：应用于范围第一列中的所有单元格
MuiDataGrid-cell--rangeRight：应用于范围最后一列中的所有单元格

您可以使用这些类来创建 CSS 选择器，以定位每个范围的特定角——例如，下面的演示在范围的外部添加了一个边框。

<StyledDataGridPremium rowSelection={false} cellSelection {...data} />

<StyledDataGridPremium rowSelection={false} cellSelection {...data} />

按 Enter 开始编辑

apiRef

数据表格通过 apiRef 对象公开了一组方法，这些方法用于单元格选择功能的实现。下面的参考描述了相关的功能。有关更多详细信息，请参阅 API 对象。

getCellSelectionModel()

返回一个包含单元格选择状态的对象。对象的键对应于行 ID。每个键的值也是一个对象，该对象具有作为键的列字段和作为其选择状态的布尔值。

签名

getCellSelectionModel: () => GridCellSelectionModel

getSelectedCellsAsArray()

返回一个仅包含选定单元格的数组。每个项目都是一个对象，其中包含单元格的 ID 和字段。

签名

getSelectedCellsAsArray: () => GridCellCoordinates[]

isCellSelected()

确定单元格是否被选中。

签名

isCellSelected: (id: GridRowId, field: GridColDef['field']) => boolean

selectCellRange()

选择由 start 和 end 坐标给定的范围内所有单元格。

签名

selectCellRange: (start: GridCellCoordinates, end: GridCellCoordinates, keepOtherSelected?: boolean) => void

setCellSelectionModel()

根据传递给 newModel 参数的值更新单元格选择模型。任何已选定的单元格都将被取消选择。

签名

setCellSelectionModel: (newModel: GridCellSelectionModel) => void