表格实例指南

TanStack Table 是一个无头 UI 库。当我们谈论 “表格” 或 “表格实例” 时，我们指的不是字面意义上的 <table> 元素。相反，我们指的是包含表格状态和 API 的 核心表格对象。表格实例是通过调用你的适配器的 createTable 函数（例如 useReactTable、createSolidTable、createSvelteTable、useQwikTable、useVueTable）来创建的。

创建表格实例

要创建一个表格实例，需要 2 个 必选选项：columns 和 data。还有数十个其他表格选项可以配置功能和行为，但这两个是必需的。

定义数据

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

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

[
  {
    "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
}

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

// 注意：为了防止无限重渲染，data 需要一个“稳定”的引用
const data: User[] = []
// 或者
const [data, setData] = React.useState<User[]>([])
// 或者
const data = ref<User[]>([])
// 等等...

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

定义列

列定义在下一节的列定义指南中有详细介绍。然而，这里我们要注意的是，当你定义列的类型时，你应该使用与你数据相同的 TData 类型。

const columns: ColumnDef<User>[] = [] // 将 User 类型作为泛型 TData 类型传递
// 或者
const columnHelper = createColumnHelper<User>() // 将 User 类型作为泛型 TData 类型传递

列定义是我们告诉 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 })

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

表格状态 (Table State)

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

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

table.getState().rowSelection // 读取行选择状态
table.setRowSelection((old) => ({...old})) // 设置行选择状态
table.resetRowSelection() // 重置行选择状态

表格 API (Table APIs)

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

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

例如，你可以在这里找到核心表格实例 API 文档：表格 API。

表格行模型 (Table Row Models)

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

列指南

行模型指南