列定义指南

注意：本指南是关于为你的表格设置列定义，而不是关于实际的column对象，这些对象是在表格实例中生成的。

列定义是构建表格最重要的一部分。它们负责

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

列定义类型

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

访问器列
- 访问器列具有底层数据模型，这意味着它们可以进行排序、筛选、分组等操作。
显示列
- 显示列没有数据模型，这意味着它们不能进行排序、筛选等操作，但它们可以用于在表格中显示任意内容，例如行操作按钮、复选框、展开器等。
分组列
- 分组列没有数据模型，因此它们也不能进行排序、筛选等操作，并且用于将其他列分组在一起。通常为列组定义表头或表尾。

列助手

虽然列定义最终只是普通的 JavaScript 对象，但表格核心公开了一个 createColumnHelper 函数，当使用行类型调用时，它返回一个用于创建具有最高类型安全性的不同列定义类型的实用程序。

这是一个创建和使用列助手的示例

tsx

// Define your row shape
type Person = {
  firstName: string
  lastName: string
  age: number
  visits: number
  status: string
  progress: number
}

const columnHelper = createColumnHelper<Person>()

// Make some columns!
const defaultColumns = [
  // Display Column
  columnHelper.display({
    id: 'actions',
    cell: props => <RowActions row={props.row} />,
  }),
  // Grouping Column
  columnHelper.group({
    header: 'Name',
    footer: props => props.column.id,
    columns: [
      // Accessor Column
      columnHelper.accessor('firstName', {
        cell: info => info.getValue(),
        footer: props => props.column.id,
      }),
      // Accessor Column
      columnHelper.accessor(row => row.lastName, {
        id: 'lastName',
        cell: info => info.getValue(),
        header: () => <span>Last Name</span>,
        footer: props => props.column.id,
      }),
    ],
  }),
  // Grouping Column
  columnHelper.group({
    header: 'Info',
    footer: props => props.column.id,
    columns: [
      // Accessor Column
      columnHelper.accessor('age', {
        header: () => 'Age',
        footer: props => props.column.id,
      }),
      // Grouping Column
      columnHelper.group({
        header: 'More Info',
        columns: [
          // Accessor Column
          columnHelper.accessor('visits', {
            header: () => <span>Visits</span>,
            footer: props => props.column.id,
          }),
          // Accessor Column
          columnHelper.accessor('status', {
            header: 'Status',
            footer: props => props.column.id,
          }),
          // Accessor Column
          columnHelper.accessor('progress', {
            header: 'Profile Progress',
            footer: props => props.column.id,
          }),
        ],
      }),
    ],
  }),
]

// Define your row shape
type Person = {
  firstName: string
  lastName: string
  age: number
  visits: number
  status: string
  progress: number
}

const columnHelper = createColumnHelper<Person>()

// Make some columns!
const defaultColumns = [
  // Display Column
  columnHelper.display({
    id: 'actions',
    cell: props => <RowActions row={props.row} />,
  }),
  // Grouping Column
  columnHelper.group({
    header: 'Name',
    footer: props => props.column.id,
    columns: [
      // Accessor Column
      columnHelper.accessor('firstName', {
        cell: info => info.getValue(),
        footer: props => props.column.id,
      }),
      // Accessor Column
      columnHelper.accessor(row => row.lastName, {
        id: 'lastName',
        cell: info => info.getValue(),
        header: () => <span>Last Name</span>,
        footer: props => props.column.id,
      }),
    ],
  }),
  // Grouping Column
  columnHelper.group({
    header: 'Info',
    footer: props => props.column.id,
    columns: [
      // Accessor Column
      columnHelper.accessor('age', {
        header: () => 'Age',
        footer: props => props.column.id,
      }),
      // Grouping Column
      columnHelper.group({
        header: 'More Info',
        columns: [
          // Accessor Column
          columnHelper.accessor('visits', {
            header: () => <span>Visits</span>,
            footer: props => props.column.id,
          }),
          // Accessor Column
          columnHelper.accessor('status', {
            header: 'Status',
            footer: props => props.column.id,
          }),
          // Accessor Column
          columnHelper.accessor('progress', {
            header: 'Profile Progress',
            footer: props => props.column.id,
          }),
        ],
      }),
    ],
  }),
]

创建访问器列

数据列的独特之处在于，必须对其进行配置，以便为你的 data 数组中的每个项目提取原始值。

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

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

对象键

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

tsx

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

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

你可以像这样提取 firstName 值

tsx


columnHelper.accessor('firstName')

// OR

{
  accessorKey: 'firstName',
}


columnHelper.accessor('firstName')

// OR

{
  accessorKey: 'firstName',
}

深层键

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

tsx

type Person = {
  name: {
    first: string
    last: string
  }
  info: {
    age: number
    visits: number
  }
}

type Person = {
  name: {
    first: string
    last: string
  }
  info: {
    age: number
    visits: number
  }
}

你可以像这样提取 first 值

tsx

columnHelper.accessor('name.first', {
  id: 'firstName',
})

// OR

{
  accessorKey: 'name.first',
  id: 'firstName',
}

columnHelper.accessor('name.first', {
  id: 'firstName',
})

// OR

{
  accessorKey: 'name.first',
  id: 'firstName',
}

数组索引

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

tsx

type Sales = [Date, number]

type Sales = [Date, number]

你可以像这样提取 number 值

tsx

columnHelper.accessor(1)

// OR

{
  accessorKey: 1,
}

columnHelper.accessor(1)

// OR

{
  accessorKey: 1,
}

访问器函数

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

tsx

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

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

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

tsx

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

// OR

{
  id: 'fullName',
  accessorFn: row => `${row.firstName} ${row.lastName}`,
}

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

// OR

{
  id: 'fullName',
  accessorFn: row => `${row.firstName} ${row.lastName}`,
}

🧠 请记住，访问的值是用于排序、筛选等的，因此你需要确保你的访问器函数返回一个可以有意义地操作的原始值。如果你返回一个非原始值（如对象或数组），你将需要适当的筛选/排序/分组函数来操作它们，甚至提供你自己的函数！😬

唯一列 ID

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

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

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

列格式化 & 渲染

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

你有几个格式化程序可用

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

单元格格式化

你可以通过将函数传递给 cell 属性并使用 props.getValue() 函数来访问单元格的值，从而提供自定义单元格格式化程序

tsx

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

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

单元格格式化程序还提供了 row 和 table 对象，允许你自定义单元格格式，而不仅仅是单元格值。下面的示例提供了 firstName 作为访问器，但也显示了位于原始行对象上的带有前缀的用户 ID

tsx

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

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

聚合单元格格式化

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

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

API