数据表格 - 列定义

定义你的列。

列通过 columns 属性定义，其类型为 GridColDef[]。

field 是唯一必需的属性，因为它作为列标识符。它也用于与 GridRowModel 值匹配。

interface GridColDef {
  /**
   * The column identifier. It's used to match with [[GridRowModel]] values.
   */
  field: string;
  …
}

提供内容

默认情况下，数据表格使用列的字段来获取其值。例如，字段为 name 的列将渲染存储在 row.name 中的值。但对于某些列，手动获取和格式化要渲染的值可能很有用。

值获取器

有时，列可能没有所需的值。你可以使用 GridColDef 的 valueGetter 属性来

转换值

const columns: GridColDef[] = [
  {
    field: 'taxRate',
    valueGetter: (value) => {
      if (!value) {
        return value;
      }
      // Convert the decimal value to a percentage
      return value * 100;
    },
  },
];

渲染不同字段的组合

const columns: GridColDef[] = [
  {
    field: 'fullName',
    valueGetter: (value, row) => {
      return `${row.firstName || ''} ${row.lastName || ''}`;
    },
  },
];

从复杂值派生值

const columns: GridColDef[] = [
  {
    field: 'profit',
    valueGetter: (value, row) => {
      if (!row.gross || !row.costs) {
        return null;
      }
      return row.gross - row.costs;
    },
  },
];

valueGetter 返回的值用于

筛选
排序
渲染（除非通过valueFormatter 或renderCell 进一步增强）

值格式化器

值格式化器允许你在显示之前转换值。常见的用例包括将 JavaScript Date 对象转换为日期字符串或将 Number 转换为格式化的数字（例如“1,000.50”）。

请注意，valueFormatter 返回的值仅用于渲染目的。筛选和排序基于原始值 (row[field]) 或 valueGetter 返回的值。

在以下演示中，valueGetter 用于将税率（例如 0.2）转换为十进制值（例如 20），而 valueFormatter 用于将其显示为百分比（例如 20%）。

渲染单元格

默认情况下，数据表格将值作为字符串渲染在单元格中。它按以下顺序解析渲染输出

renderCell() => ReactElement
valueFormatter() => string
valueGetter() => string
row[field]

列定义的 renderCell 方法类似于 valueFormatter。但是，它权衡了只能在单元格中渲染的能力，以换取允许返回 React 节点（而不是字符串）。

const columns: GridColDef[] = [
  {
    field: 'date',
    headerName: 'Year',
    renderCell: (params: GridRenderCellParams<any, Date>) => (
      <strong>
        {params.value.getFullYear()}
        <Button
          variant="contained"
          size="small"
          style={{ marginLeft: 16 }}
          tabIndex={params.hasFocus ? 0 : -1}
        >
          Open
        </Button>
      </strong>
    ),
  },
];

使单元格可访问

单元格内容不应在标签序列中，除非单元格被聚焦。你可以查看标签序列部分以获取更多信息。

在渲染器内部使用钩子

renderCell 属性是一个返回 React 节点的函数，而不是 React 组件。

如果你想在渲染器内部使用 React 钩子，你应该将它们包装在组件内部。

// ❌ Not valid
const column = {
  // ...other properties,
  renderCell: () => {
    const [count, setCount] = React.useState(0);

    return (
      <Button onClick={() => setCount((prev) => prev + 1)}>{count} click(s)</Button>
    );
  },
};

// ✅ Valid
const CountButton = () => {
  const [count, setCount] = React.useState(0);

  return (
    <Button onClick={() => setCount((prev) => prev + 1)}>{count} click(s)</Button>
  );
};

const column = {
  // ...other properties,
  renderCell: () => <CountButton />,
};

展开单元格渲染器

默认情况下，如果单元格的内容不适合单元格，数据表格会剪切单元格的内容并渲染省略号。作为一种解决方法，你可以创建一个单元格渲染器，它将允许在数据表格中查看单元格的完整内容。

列类型

为了方便列的配置，预定义了一些列类型。默认情况下，列被假定为保存字符串，因此将应用默认的列字符串类型。因此，列排序将使用字符串比较器，并且列内容将与单元格的左侧对齐。某些列类型要求其值具有特定类型。

以下是原生列类型及其所需的value类型

列类型	值类型
`'string'` (默认)	`字符串`
`'number'`	`数字`
`'date'`	`Date() 对象`
`'dateTime'`	`Date() 对象`
`'boolean'`	`布尔值`
`'singleSelect'`	`.valueOptions` 中的值
`'actions'`	不适用

转换类型

默认方法（例如筛选和排序）假设值的类型将与 type 中指定的列的类型匹配。例如，type: 'dateTime' 的列的值应存储为 Date() 对象。如果由于任何原因，你的数据类型不正确，你可以使用 valueGetter 将值解析为正确的类型。

{
  field: 'lastLogin',
  type: 'dateTime',
  valueGetter: (value) => value && new Date(value),
}

特殊属性

要使用大多数列类型，你只需在列定义中定义 type 属性。但是，某些类型需要设置其他属性才能使其正常工作

单选

如果列类型为 'singleSelect'，你还需要在相应的列定义中设置 valueOptions 属性。这些值是用于筛选和编辑的选项。

{
  field: 'country',
  type: 'singleSelect',
  valueOptions: ['United Kingdom', 'Spain', 'Brazil']
}

当为 valueOptions 使用对象值时，你需要为每个选项提供 value 和 label 属性。但是，你可以分别使用 getOptionValue 和 getOptionLabel 来自定义哪个属性用作值和标签。

// Without getOptionValue and getOptionLabel
{
  valueOptions: [
    { value: 'BR', label: 'Brazil' },
    { value: 'FR', label: 'France' }
  ]
}

// With getOptionValue and getOptionLabel
{
  getOptionValue: (value: any) => value.code,
  getOptionLabel: (value: any) => value.name,
  valueOptions: [
    { code: 'BR', name: 'Brazil' },
    { code: 'FR', name: 'France' }
  ]
}

操作

如果列类型为 'actions'，你需要提供一个 getActions 函数，该函数返回每个行可用的操作数组（React 元素）。你可以在返回的 React 元素上添加 showInMenu 属性，以指示数据表格将这些操作分组在行菜单中。

{
  field: 'actions',
  type: 'actions',
  getActions: (params: GridRowParams) => [
    <GridActionsCellItem icon={...} onClick={...} label="Delete" />,
    <GridActionsCellItem icon={...} onClick={...} label="Print" showInMenu />,
  ]
}

默认情况下，菜单中显示的操作将在单击时关闭菜单。但在某些情况下，你可能希望在单击操作后保持菜单打开。你可以通过将 closeMenuOnClick 属性设置为 false 来实现此目的。

在以下示例中，“删除”操作打开一个确认对话框，因此需要保持菜单挂载

诸如行分组或聚合之类的某些功能会创建自动生成的行。这些行也会调用诸如 valueGetter、valueFormatter 和 renderCell 之类的函数，如果你没有预料到这一点，可能会导致问题，因为 row 参数将是一个空对象，而 value 参数将是 undefined。如果我们以电影数据集为例，你可以使用 isAutogeneratedRow 检测自动生成的行

{
  field: 'title',
  valueGetter: (value, row) => {
    if (isAutogeneratedRow(row)) {
      return '[this is an autogenerated row]';
    }
    return `title: ${value}`;
  },
}

选择器

可见列

这些选择器不考虑隐藏列。

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)

定义的列

这些选择器考虑所有定义的列，包括隐藏的列。

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)

有关选择器以及如何在专用页面上使用它们的更多信息。