表格实例指南

TanStack Table 是一个无 UI 库。当我们提到“表格”或“表格实例”时，我们指的不是一个实际的 <table> 元素。而是指包含表格状态和 API 的核心表格对象。表格实例是通过调用适配器的 createTable 函数创建的（例如 useReactTable、createSolidTable、createSvelteTable、useQwikTable、useVueTable）。

创建表格实例

创建表格实例需要 2 个选项：columns 和 data。有几十种其他表格选项可用于配置功能和行为，但这 2 个是必需的。

定义数据

data 是一个对象数组，将被转换成表格的行。数组中的每个对象通常代表一行数据。如果您使用 TypeScript，我们通常会为数据的形状定义一个类型。此类型用作所有其他表格、列、行和单元格实例的泛型类型。此类型通常被称为 TData。

例如，如果我们有一个表格，以数组形式显示用户列表，如下所示：

json

[
  {
    "firstName": "Tanner",
    "lastName": "Linsley",
    "age": 33,
    "visits": 100,
    "progress": 50,
    "status": "Married"
  },
  {
    "firstName": "Kevin",
    "lastName": "Vandy",
    "age": 27,
    "visits": 200,
    "progress": 100,
    "status": "Single"
  }
]

[
  {
    "firstName": "Tanner",
    "lastName": "Linsley",
    "age": 33,
    "visits": 100,
    "progress": 50,
    "status": "Married"
  },
  {
    "firstName": "Kevin",
    "lastName": "Vandy",
    "age": 27,
    "visits": 200,
    "progress": 100,
    "status": "Single"
  }
]

那么我们可以像这样定义一个 User (TData) 类型：

//TData
type User = {
  firstName: string
  lastName: string
  age: number
  visits: number
  progress: number
  status: string
}

//TData
type User = {
  firstName: string
  lastName: string
  age: number
  visits: number
  progress: number
  status: string
}

然后我们可以使用此类型定义我们的 data 数组，之后 TanStack Table 将能够智能地推断出我们列、行、单元格等的许多类型。

//note: data needs a "stable" reference in order to prevent infinite re-renders
const data: User[] = []
//or
const [data, setData] = React.useState<User[]>([])
//or
const data = ref<User[]>([])
//etc...

//note: data needs a "stable" reference in order to prevent infinite re-renders
const data: User[] = []
//or
const [data, setData] = React.useState<User[]>([])
//or
const data = ref<User[]>([])
//etc...

注意：data 需要一个“稳定”的引用（尤其是在 React 中）才能防止无限渲染。这就是为什么我们建议使用 React.useState 或 React.useMemo，或者将数据定义在创建表格实例的同一个 React 组件之外，或者使用 TanStack Query 等库来管理您的数据状态。

定义列

列定义将在下一节列定义指南中详细介绍。但在此我们注意到，在定义列类型时，您应该使用与数据相同的 TData 类型。

const columns: ColumnDef<User>[] = [] //Pass User type as the generic TData type
//or
const columnHelper = createColumnHelper<User>() //Pass User type as the generic TData type

const columns: ColumnDef<User>[] = [] //Pass User type as the generic TData type
//or
const columnHelper = createColumnHelper<User>() //Pass User type as the generic TData type

列定义是我们将告诉 TanStack Table 每个列如何通过 accessorKey 或 accessorFn 访问和/或转换行数据。有关更多信息，请参阅列定义指南。

创建表格实例

定义好 columns 和 data 后，我们现在可以创建基本的表格实例了。

//vanilla js
const table = createTable({ columns, data })

//react
const table = useReactTable({ columns, data })

//solid
const table = createSolidTable({ columns, data })

//svelte
const table = createSvelteTable({ columns, data })

//vue
const table = useVueTable({ columns, data })

//vanilla js
const table = createTable({ columns, data })

//react
const table = useReactTable({ columns, data })

//solid
const table = createSolidTable({ columns, data })

//svelte
const table = createSvelteTable({ columns, data })

//vue
const table = useVueTable({ columns, data })

那么 table 实例中有什么呢？让我们看看我们可以与表格实例进行哪些交互。

Table 状态

表格实例包含所有表格状态，可以通过 table.getState() API 访问。每个表格功能都会在表格状态中注册各种状态。例如，行选择功能注册 rowSelection 状态，分页功能注册 pagination 状态等。

每个功能还将在表格实例上具有相应的状态设置器 API 和状态重置器 API。例如，行选择功能将具有 setRowSelection API 和 resetRowSelection。

table.getState().rowSelection //read the row selection state
table.setRowSelection((old) => ({...old})) //set the row selection state
table.resetRowSelection() //reset the row selection state

table.getState().rowSelection //read the row selection state
table.setRowSelection((old) => ({...old})) //set the row selection state
table.resetRowSelection() //reset the row selection state

表格 API

每个功能都会创建数十个表格 API，以帮助您以不同方式读取或修改表格状态。

核心表格实例和所有其他功能 API 的 API 参考文档可以在 API 文档中找到。

例如，您可以在此处找到核心表格实例 API 文档：表格 API

表格行模型

有一组特殊的表格实例 API 用于从表格实例中读取行，称为行模型。TanStack Table 具有高级功能，生成的行可能与您最初传入的 data 数组非常不同。要了解有关您可以作为表格选项传入的不同行模型的更多信息，请参阅行模型指南。

API