列指南

API

列定义指南

列定义 (Column defs) 是构建表格最重要的部分。它们负责：

构建将用于包括排序、过滤、分组等所有操作的 底层数据模型。
将数据模型格式化为将在表格中显示的内容。
创建 表头组 (header groups)、表头 (headers) 和 表尾 (footers)。
创建仅用于显示目的的列，例如操作按钮、复选框、展开器、迷你图等。

列定义类型

以下 “类型” 的列定义实际上并不是 TypeScript 类型，而更多是讨论和描述列定义总体类别的一种方式：

访问器列 (Accessor Columns) 访问器列具有底层数据模型，这意味着它们可以进行排序、过滤、分组等操作。
显示列 (Display Columns) 显示列没有数据模型，这意味着它们不能进行排序、过滤等操作，但它们可以用于在表格中显示任意内容，例如行操作按钮、复选框、展开器等。
分组列 (Grouping Columns) 分组列没有数据模型，所以它们也不能进行排序、过滤等操作，它们用于将其他列组合在一起。通常会为列组定义一个表头或表尾。

列助手 (Column Helpers)

虽然列定义归根结底只是普通对象，但表格核心会暴露一个 createColumnHelper 函数，当它用行类型调用时，会返回一个实用工具，用于以 尽可能最高的类型安全 创建不同类型的列定义。

以下是创建和使用列助手的示例：

// 定义你的行结构
type Person = {
  firstName: string
  lastName: string
  age: number
  visits: number
  status: string
  progress: number
}

const columnHelper = createColumnHelper<Person>()

// 创建一些列！
const defaultColumns = [
  // 显示列
  columnHelper.display({
    id: 'actions',
    cell: props => <RowActions row={props.row} />,
  }),
  // 分组列
  columnHelper.group({
    header: '姓名',
    footer: props => props.column.id,
    columns: [
      // 访问器列
      columnHelper.accessor('firstName', {
        cell: info => info.getValue(),
        footer: props => props.column.id,
      }),
      // 访问器列
      columnHelper.accessor(row => row.lastName, {
        id: 'lastName',
        cell: info => info.getValue(),
        header: () => <span>姓氏</span>,
        footer: props => props.column.id,
      }),
    ],
  }),
  // 分组列
  columnHelper.group({
    header: '信息',
    footer: props => props.column.id,
    columns: [
      // 访问器列
      columnHelper.accessor('age', {
        header: () => '年龄',
        footer: props => props.column.id,
      }),
      // 分组列
      columnHelper.group({
        header: '更多信息',
        columns: [
          // 访问器列
          columnHelper.accessor('visits', {
            header: () => <span>访问量</span>,
            footer: props => props.column.id,
          }),
          // 访问器列
          columnHelper.accessor('status', {
            header: '状态',
            footer: props => props.column.id,
          }),
          // 访问器列
          columnHelper.accessor('progress', {
            header: '资料进度',
            footer: props => props.column.id,
          }),
        ],
      }),
    ],
  }),
]

创建访问器列 (Creating Accessor Columns)

数据列的独特之处在于它们必须配置为从 data 数组中的每个项目提取原始值。

有 3 种方法可以做到这一点：

如果你的项目是对象，使用一个与你要提取的值相对应的 对象键。
如果你的项目是嵌套的数组，使用一个与你要提取的值相对应的 数组索引。
使用一个 访问器函数 (accessor function)，它返回你要提取的值。

对象键 (Object Keys)

如果你的每个项目都是一个具有以下形状的对象：

type Person = {
  firstName: string
  lastName: string
  age: number
  visits: number
  status: string
  progress: number
}

你可以像这样提取 firstName 值：

columnHelper.accessor('firstName')
// 或者
{
  accessorKey: 'firstName',
}

数组索引 (Array Indices)

如果你的每个项目都是一个具有以下形状的数组：

type Sales = [Date, number]

你可以像这样提取 number 值：

columnHelper.accessor(1)
// 或者
{
  accessorKey: 1,
}

访问器函数 (Accessor Functions)

如果你的每个项目都是一个具有以下形状的对象：

type Person = {
  firstName: string
  lastName: string
  age: number
  visits: number
  status: string
  progress: number
}

你可以像这样提取计算出的全名值：

columnHelper.accessor(row => `${row.firstName} ${row.lastName}`, {
  id: 'fullName',
})
// 或者
{
  id: 'fullName',
  accessorFn: row => `${row.firstName} ${row.lastName}`,
}

记住：被访问的值用于排序、过滤等，所以你会希望确保你的访问器函数返回一个可以有意义地操作的 原始值。如果你返回一个非原始值，如对象或数组，你需要适当的过滤/排序/分组函数来操作它们，甚至提供你自己的！

唯一的列 ID (Unique Column IDs)

列通过 3 种策略进行唯一标识：

如果使用 对象键 或 数组索引 定义访问器列，则使用相同的键或索引来唯一标识列。
- 对象键中的任何句点 (.) 都将替换为下划线 (_)。
如果使用 访问器函数 定义访问器列：
- 列的 id 属性将用于唯一标识列，或者
- 如果提供了一个原始的 string 表头，该表头字符串将用于唯一标识列。

一个简单的记忆方法： 如果你使用访问器函数定义列，要么提供一个字符串表头，要么提供一个唯一的 id 属性。

列格式化与渲染 (Column Formatting & Rendering)

默认情况下，列单元格将将其数据模型值显示为字符串。你可以通过提供自定义渲染实现来覆盖此行为。每个实现都提供了有关单元格、表头或表尾的相关信息，并返回你的框架适配器可以渲染的内容，例如 JSX/组件/字符串等。这将取决于你使用的适配器。

你有以下几种格式化器可用：

cell: 用于格式化单元格。
aggregatedCell: 用于聚合时格式化单元格。
header: 用于格式化表头。
footer: 用于格式化表尾。

单元格格式化 (Cell Formatting)

你可以通过向 cell 属性传递一个函数并使用 props.getValue() 函数访问单元格的值来提供自定义单元格格式化器：

columnHelper.accessor('firstName', {
  cell: props => <span>{props.getValue().toUpperCase()}</span>,
})

单元格格式化器还会提供 row 和 table 对象，允许你超越仅仅单元格值来定制单元格格式化。下面的示例提供了 firstName 作为访问器，但也显示了位于原始行对象上的带有前缀的用户 ID：

columnHelper.accessor('firstName', {
  cell: props => (
    <span>{`${props.row.original.id} - ${props.getValue()}`}</span>
  ),
})

聚合单元格格式化 (Aggregated Cell Formatting)

有关聚合单元格的更多信息，请参阅分组 (grouping)。

表头和表尾格式化 (Header & Footer Formatting)

表头和表尾无法访问行数据，但仍使用相同的概念来显示自定义内容。

Data 指南

表格实例指南