表 APIs

`useReactTable` / `createSolidTable` / `useQwikTable` / `useVueTable` / `createSvelteTable`

type useVueTable = <TData extends AnyData>(
  options: TableOptions<TData>
) => Table<TData>

这些函数用于创建表格。你使用哪一个取决于你所使用的框架适配器。

选项 (Options)

这些是表格的核心选项和 API 属性。更多选项和 API 属性可在其他表格特性中找到。

data

data: TData[]

表格要显示的数据。这个数组应该与你提供给 table.setRowType<...> 的类型匹配，但理论上可以是任何数组。数组中的每个项通常是键/值对象，但这并非必需。列可以通过字符串/索引或函数式访问器来访问此数据，以返回它们想要的任何内容。

当 data 选项的引用发生变化时（通过 Object.is 比较），表格将重新处理数据。任何依赖核心数据模型的其他数据处理（如分组、排序、过滤等）也将被重新处理。

确保你的 data 选项只在你希望表格重新处理数据时才发生变化。每次渲染表格时提供一个内联的 [] 或将数据数组构造为一个新对象，将导致大量不必要的重新处理。这在较小的表格中可能不易察觉，但在较大的表格中你可能会注意到。

columns

type columns = ColumnDef<TData>[]

用于表格的列定义数组。有关创建列定义的更多信息，请参阅列定义指南。

defaultColumn

defaultColumn?: Partial<ColumnDef<TData>>

用于提供给表格的所有列定义的默认列选项。这对于提供默认的单元格/头部/页脚渲染器、排序/过滤/分组选项等非常有用。所有传递给 options.columns 的列定义都将与此默认列定义合并，以生成最终的列定义。

initialState

initialState?: Partial<
  VisibilityTableState &
  ColumnOrderTableState &
  ColumnPinningTableState &
  FiltersTableState &
  SortingTableState &
  ExpandedTableState &
  GroupingTableState &
  ColumnSizingTableState &
  PaginationTableState &
  RowSelectionTableState
>

使用此选项可以有选择地将初始状态传递给表格。此状态将在表格自动重置各种表格状态时（例如 options.autoResetPageIndex）或通过 table.resetRowSelection() 等函数重置时使用。大多数重置函数允许你选择性地传递一个标志，以重置为空白/默认状态而不是初始状态。

当此对象改变时，表格状态不会重置，这也意味着初始状态对象不需要稳定。

autoResetAll

autoResetAll?: boolean

设置此选项以覆盖任何 autoReset... 特性选项。

state

state?: Partial<
  VisibilityTableState &
  ColumnOrderTableState &
  ColumnPinningTableState &
  FiltersTableState &
  SortingTableState &
  ExpandedTableState &
  GroupingTableState &
  ColumnSizingTableState &
  PaginationTableState &
  RowSelectionTableState
>

state 选项可用于选择性地控制表格的部分或全部状态。你在此处传递的状态将与内部自动管理的状态合并并覆盖，以生成表格的最终状态。你还可以通过 onStateChange 选项监听状态变化。

onStateChange

onStateChange: (updater: Updater<TableState>) => void

onStateChange 选项可用于选择性地监听表格内的状态变化。如果你提供此选项，你将负责手动控制和更新表格状态。你可以通过 state 选项将状态传递回表格。

debugAll

调试仅在开发模式下可用。

debugAll?: boolean

将此选项设置为 true 以将所有调试信息输出到控制台。

debugTable

调试仅在开发模式下可用。

debugTable?: boolean

将此选项设置为 true 以将表格调试信息输出到控制台。

debugHeaders

调试仅在开发模式下可用。

debugHeaders?: boolean

将此选项设置为 true 以将头部调试信息输出到控制台。

debugColumns

调试仅在开发模式下可用。

debugColumns?: boolean

将此选项设置为 true 以将列调试信息输出到控制台。

debugRows

调试仅在开发模式下可用。

debugRows?: boolean

将此选项设置为 true 以将行调试信息输出到控制台。

_features

_features?: TableFeature[]

你可以添加到表格实例的额外功能数组。

render

此选项仅在实现表格适配器时才需要。

type render = <TProps>(template: Renderable<TProps>, props: TProps) => any

render 选项为表格提供了一个渲染器实现。此实现用于将表格的各种列头和单元格模板转换为用户框架支持的结果。

mergeOptions

此选项仅在实现表格适配器时才需要。

type mergeOptions = <T>(defaultOptions: T, options: Partial<T>) => T

此选项用于选择性地实现表格选项的合并。某些框架（如 SolidJS）使用代理来跟踪响应性和用法，因此需要仔细处理响应式对象的合并。此选项将此过程的控制权反转给适配器。

getCoreRowModel

getCoreRowModel: (table: Table<TData>) => () => RowModel<TData>

这个必需选项是一个工厂函数，用于计算并返回表格的核心行模型。它每个表格只调用一次，并且应该返回一个新函数，该函数将计算并返回表格的行模型。

默认实现通过任何表格适配器的 { getCoreRowModel } 导出提供。

getSubRows

getSubRows?: (
  originalRow: TData,
  index: number
) => undefined | TData[]

此可选函数用于访问任何给定行的子行。如果你正在使用嵌套行，你需要使用此函数从行中返回子行对象（或 undefined）。

getRowId

getRowId?: (
  originalRow: TData,
  index: number,
  parent?: Row<TData>
) => string

此可选函数用于为任何给定行派生唯一 ID。如果未提供，则使用行的索引（嵌套行使用其祖父母的索引通过 . 连接在一起，例如 index.index.index）。如果你需要识别来自任何服务器端操作的单独行，建议你使用此函数返回一个无论网络 IO/歧义如何都有意义的 ID，例如 userId、taskId、数据库 ID 字段等。

表格 API (Table API)

这些属性和方法在表格对象上可用：

initialState

initialState: VisibilityTableState &
  ColumnOrderTableState &
  ColumnPinningTableState &
  FiltersTableState &
  SortingTableState &
  ExpandedTableState &
  GroupingTableState &
  ColumnSizingTableState &
  PaginationTableState &
  RowSelectionTableState

这是表格解析后的初始状态。

reset

reset: () => void

调用此函数可将表格状态重置为初始状态。

getState

getState: () => TableState

调用此函数可获取表格的当前状态。建议使用此函数及其状态，尤其是在手动管理表格状态时。它是表格内部用于其提供的每个特性和函数的完全相同的状态。

此函数返回的状态是自动管理的内部表格状态和通过 options.state 传递的任何手动管理状态的浅合并结果。

setState

setState: (updater: Updater<TableState>) => void

调用此函数可更新表格状态。建议你以 (prevState) => newState 的形式传递更新函数来更新状态，但也可以直接传递对象。

如果提供了 options.onStateChange，它将由此函数与新状态一起触发。

options

options: TableOptions<TData>

对表格当前选项的只读引用。

此属性通常在内部使用或由适配器使用。它可以通过向表格传递新选项来更新。这因适配器而异。对于适配器本身，表格选项必须通过 setOptions 函数更新。

setOptions

setOptions: (newOptions: Updater<TableOptions<TData>>) => void

此函数通常由适配器用于更新表格选项。它可以直接用于更新表格选项，但通常不建议绕过适配器更新表格选项的策略。

getCoreRowModel

getCoreRowModel: () => {
  rows: Row<TData>[],
  flatRows: Row<TData>[],
  rowsById: Record<string, Row<TData>>,
}

返回在应用任何处理之前的核心行模型。

getRowModel

getRowModel: () => {
  rows: Row<TData>[],
  flatRows: Row<TData>[],
  rowsById: Record<string, Row<TData>>,
}

返回在应用了所有其他已使用特性处理后的最终模型。

getAllColumns

type getAllColumns = () => Column<TData>[]

返回表格中所有列的规范化和嵌套层次结构，镜像自传递给表格的列定义。

getAllFlatColumns

type getAllFlatColumns = () => Column<TData>[]

将表格中所有列扁平化为单个级别。这包括整个层次结构中的父列对象。

getAllLeafColumns

type getAllLeafColumns = () => Column<TData>[]

将表格中所有叶节点列扁平化为单个级别。这不包括父列。

getColumn

type getColumn = (id: string) => Column<TData> | undefined

按其 ID 返回单个列。

getHeaderGroups

type getHeaderGroups = () => HeaderGroup<TData>[]

返回表格的头部组。

getFooterGroups

type getFooterGroups = () => HeaderGroup<TData>[]

返回表格的页脚组。

getFlatHeaders

type getFlatHeaders = () => Header<TData>[]

返回表格的扁平化 Header 对象数组，包括父头部。

getLeafHeaders

type getLeafHeaders = () => Header<TData>[]

返回表格的扁平化叶节点 Header 对象数组。

列定义

列 APIs