@tanstack/react-table API 参考指南:模块结构与核心导出全解析
@tanstack/react-table API 参考指南:模块结构与核心导出全解析
导读
本文是 @tanstack/react-table(TanStack Table 的 React 框架绑定层)官方 API 参考文档的深度解读,以 docs/framework/react/reference/index.md 索引页为骨架,完整梳理该包导出的全部接口、类型别名与函数,并对照 packages/react-table/src 下的源码实现逐一定位底层原理。读完本文,你将掌握 useTable、createTableHook、Subscribe、FlexRender 等核心 API 的完整签名、类型约束与使用方式,理解 index 模块与 legacy 模块的分层关系,并能直接使用仓库内 composable-tables 示例 落地一套"组件预绑定 + 上下文访问"的组合式表格架构。
模块总览:index 与 legacy 两大导出分区
@tanstack/react-table 的 API 参考入口将全部导出划分为两个模块,对应包内两个独立源码文件:
| 模块 | 对应源码 | 内容定位 |
|---|---|---|
| index | packages/react-table/src/index.ts | 当前推荐使用的新版 API:基于 TanStack Store 原子(atoms)与 feature 机制构建的表格实例 |
| legacy | packages/react-table/src/legacy.ts | 旧版 v8 风格的 API,大部分条目已标记为 ~~弃用~~(strikethrough) |
从入口文件 packages/react-table/src/index.ts 可以看到,新版 index 模块首先 export * from '@tanstack/table-core' 重导出核心层全部内容,再依次导出 FlexRender、Subscribe、createTableHook、createTableHookContexts、useTable 五个本地模块。这种"核心层(table-core)+ 框架绑定层(react-table)"的分层是理解整个 API 面结构的关键。
index 模块导出清单
索引页列出了三组导出:
- Interfaces(10 个):
AppCellComponent、AppCellPropsWithoutSelector、AppCellPropsWithSelector、AppHeaderComponent、AppHeaderPropsWithoutSelector、AppHeaderPropsWithSelector、AppTableComponent、AppTablePropsWithoutSelector、AppTablePropsWithSelector、CreateTableHookResult、TableHookContexts。 - Type Aliases(17 个):
AppCellContext、AppColumnDefBase、AppColumnDefTemplate、AppColumnHelper、AppDisplayColumnDef、AppGroupColumnDef、AppHeaderContext、AppReactTable、CreateTableHookOptions、FlexRenderProps、ReactTable、Renderable、SubscribeProps系列(SubscribeProps、SubscribePropsWithSource、SubscribePropsWithSourceIdentity、SubscribePropsWithSourceWithSelector、SubscribePropsWithStore)、SubscribeSource。 - Functions(6 个):
createTableHook、createTableHookContexts、flexRender、FlexRender、Subscribe、useTable。
不难看出,这组 API 围绕两条主线展开:表格实例的创建(useTable / createTableHook / createTableHookContexts)与渲染层的订阅与分发(Subscribe / flexRender / FlexRender),而全部 App* 类型则是 createTableHook 组合式架构下的配套类型。
legacy 模块:旧版 API 的兼容层
legacy 索引页 列出了 LegacyFeatures、LegacyRowModelOptions 两个接口,FacetedMinMaxValuesFactory、FacetedRowModelFactory、FacetedUniqueValuesFactory、RowModelFactory 等类型别名,以及 getCoreRowModel、getExpandedRowModel、getFacetedMinMaxValues、getFacetedRowModel、getFacetedUniqueValues、getFilteredRowModel、getGroupedRowModel、getPaginationRowModel、getSortedRowModel、legacyCreateColumnHelper、useLegacyTable 等函数。
值得注意的是,其中 LegacyCell、LegacyColumn、LegacyColumnDef、LegacyHeader、LegacyHeaderGroup、LegacyReactTable、LegacyRow、LegacyTable、LegacyTableOptions 及上述全部 get*RowModel 函数、useLegacyTable、legacyCreateColumnHelper 均被标记为弃用。这意味着新版架构不再推荐直接传递 getCoreRowModel() 这类 row model 工厂,而是通过 tableFeatures({ ... }) 声明式地组合 feature 与 row model(详见下文 useTable 一节)。
核心函数 API 详解
useTable:基于 Store 原子的表格实例工厂
useTable 参考文档 给出了最核心的签名:
function useTable<TFeatures, TData, TSelected>(tableOptions, selector?): ReactTable<TFeatures, TData, TSelected>;
其中 TFeatures extends TableFeatures、TData extends RowData、TSelected = TableState<TFeatures>(未传 selector 时默认订阅全部已注册的 state 切片)。文档明确说明其职责是"创建一个由 TanStack Store 原子支撑的 React 表格实例(Creates a React table instance backed by TanStack Store atoms)"。
对照源码 packages/react-table/src/useTable.ts 可梳理其内部实现链路:
- 首次渲染时调用核心层的
constructTable构造表格实例,并注入coreReactivityFeature: reactReactivity()这一 React 响应式桥接(tableOptions.features中用户传入的 feature 会合并其后); - 为实例挂载
Subscribe(默认以table.store为订阅源)与FlexRender两个成员; - 每次渲染通过
table_setOptions将最新tableOptions合并进 options(syncExternalState: false,不在渲染期广播给响应式订阅者); - 通过
useSelector(rootSource, selector, { compare: shallow })用浅比较完成 state 切片投影,并用useIsomorphicLayoutEffect在提交后发布外部受控 state; - 最后经
useMemo返回{ ...table, options, state }——源码注释特别说明"这不是最省内存的写法,但它是 React Compiler 正常工作的必要条件"。
selector 参数的语义在 ReactTable 类型文档 中有精确说明:table.state 是 selector 投影后的选中状态(selected state),可能与完整表格 state 结构不一致。典型用法:
const table = useTable(
{
features,
columns,
data,
},
(state) => ({ pagination: state.pagination }),
)
table.state.pagination // 只包含 pagination 切片
若省略 selector,TSelected 默认为完整 TableState<TFeatures>,即订阅所有已注册的 state 切片;若想进一步缩小订阅范围,则应在组件树更下层使用 table.Subscribe 做定向订阅。
createTableHook:组合式表格 Hook 工厂
createTableHook 参考文档 将其定位为"TanStack Form 的 createFormHook 在表格领域的对应物",一次调用即可完成 feature、row model、默认 options 的统一定义,以及三类组件的统一注册。完整签名如下:
function createTableHook<TFeatures, TTableComponents, TCellComponents, THeaderComponents>(
__namedParameters
): CreateTableHookResult<TFeatures, TTableComponents, TCellComponents, THeaderComponents>;
其中三个组件泛型参数均约束为 Record<string, ComponentType<any>>,即"组件名 → React 组件"的映射表。返回值 CreateTableHookResult 提供 6 个成员(见 CreateTableHookResult 接口文档):
| 成员 | 类型 | 用途 |
|---|---|---|
appFeatures |
TFeatures |
传入 createTableHook 的 features 对象 |
createAppColumnHelper |
<TData>() => AppColumnHelper<...> |
预绑定 TFeatures 与注册组件的列助手 |
useAppTable |
<TData, TSelected>(tableOptions, selector?) => AppReactTable<...> |
返回挂载了 App* 包装组件与 tableComponents 的扩展表格 |
useTableContext |
<TData, TSelected>() => AppReactTable<...> |
读取最近 <table.AppTable> 提供的表格实例 |
useCellContext |
<TValue>() => Cell<...> & TCellComponents & { FlexRender } |
读取最近 <table.AppCell> 提供的单元格实例(已扩展注册组件) |
useHeaderContext |
<TValue>() => Header<...> & THeaderComponents & { FlexRender } |
读取最近 <table.AppHeader> / <table.AppFooter> 提供的表头实例 |
在 createTableHook.tsx 源码 中,createTableHook 的实现要点包括:
- 三个 context 参数(
tableContext/cellContext/headerContext)默认使用模块级共享 context(sharedTableContext等,见 createTableHook.tsx:34-38);仅当需要隔离(例如在另一个表格内部嵌套表格)时才传入自定义createContext创建的 context; createAppColumnHelper运行时就是对核心层createColumnHelper的透传,增强类型在编译期完成;useAppTable内部合并"默认 options + 本次 options"(后者优先),并返回Object.assign(table, { AppTable, AppCell, AppHeader, AppFooter, ...tableComponents })的扩展实例;- 三个
App*组件通过useMemo一次性创建(依赖数组为空),关键注释指出:useTable每次渲染都会返回全新的table引用(React Compiler 的要求),因此App*组件必须稳定创建,改为通过tableRef在每次渲染时刷新当前表格引用,否则受控输入(如工具栏搜索框)会在每次 state 更新时失焦重挂载(见 createTableHook.tsx:960-968); AppCell/AppHeader/AppFooter在渲染时通过Object.assign把注册组件与 context 感知的FlexRender挂到cell/header实例上(见 createTableHook.tsx:1044-1047 与 1120-1123),这正是"组件预绑定"的实现机制。
flexRender 与 FlexRender:模板化渲染分发
flexRender 函数文档 说明:当需要用自定义标记渲染 header / cell / footer 时,应使用 flexRender 而不是 cell.getValue() 或 cell.renderValue():
function flexRender<TProps>(Comp, props): ReactNode | Element;
其源码实现(packages/react-table/src/FlexRender.tsx:45-54)非常直观:若 Comp 为空则返回 null;若为 React 组件(通过 isReactComponent 判断类组件、函数组件与 memo / forwardRef 这类 exotic 组件)则渲染 <Comp {...props} />,否则直接把原始值(字符串等)作为 ReactNode 返回。典型的直接调用方式为:
flexRender(cell.column.columnDef.cell, cell.getContext())
flexRender(header.column.columnDef.header, header.getContext())
flexRender(footer.column.columnDef.footer, footer.getContext())
而 FlexRender 组件 是对 flexRender 的组件化封装,配合 FlexRenderProps 类型 使用。FlexRenderProps 是一个三选一的联合类型,cell、header、footer 三个属性中必须且只能传一个:
<table.FlexRender cell={cell} />
<table.FlexRender header={header} />
<table.FlexRender footer={footer} />
组件实现(FlexRender.tsx:97-136)在渲染 cell 时还会额外处理分组场景:当 cell.getIsAggregated() 为真时优先使用 columnDef.aggregatedCell(否则回退到 cell),当 cell.getIsPlaceholder() 为真时直接返回 null。因此建议在分组表格中统一使用 <table.FlexRender cell={cell} /> 而不是手写 flexRender,以自动获得聚合/占位单元格的正确行为。
Subscribe:定向订阅表格状态
Subscribe 函数文档 提供了一种"订阅表格 state 的特定切片以定向触发重渲染"的机制,并给出了三种用法:
// 1) 独立组件 + 完整 store:通过 selector 投影出所需切片
<Subscribe source={table.store} selector={(state) => ({ rowSelection: state.rowSelection })}>
{({ rowSelection }) => (
<div>Selected rows: {Object.keys(rowSelection).length}</div>
)}
</Subscribe>
// 2) 独立组件 + 单个原子(atom):不传 selector 时 children 直接接收源值
<Subscribe source={table.atoms.rowSelection}>
{(rowSelection) => <div>...</div>}
</Subscribe>
// 3) 投影源值(例如单行选中态)
<Subscribe
source={table.atoms.rowSelection}
selector={(rowSelection) => rowSelection?.[row.id]}
>
{(selected) => <tr data-selected={!!selected}>...</tr>}
</Subscribe>
// 4) 表格实例方法 table.Subscribe(省略 source 时默认订阅 table.store)
<table.Subscribe selector={(state) => ({ rowSelection: state.rowSelection })}>
{({ rowSelection }) => (
<div>Selected rows: {Object.keys(rowSelection).length}</div>
)}
</table.Subscribe>
从 useTable.ts:77-91 的源码可以看到,table.Subscribe 是 Subscribe 组件的实例化绑定,source 缺省时回落到 tableInstance.store。文档特别解释了三重重载的设计意图:重载(overload)而非联合类型(union),这样 JSX 中的 selector 回调才能获得正确的上下文类型推断——联合类型会把两个 selector 签名退化合并成隐式 any;同时"source 不带 selector"单独成一个重载,保证 children 能收到 TSourceValue(恒等投影),否则 TSubSelected 会默认成 unknown 而非从 source 推断。
与之配套的 SubscribeProps 系列类型(SubscribePropsWithSource、SubscribePropsWithSourceIdentity、SubscribePropsWithSourceWithSelector、SubscribePropsWithStore)分别约束"任意订阅源"、"source 恒等投影"、"source + selector 投影"、"store 订阅"四种 props 形态,可在 index 模块类型列表 中逐一查阅。
组合式架构的类型体系:从 AppCellContext 到 AppReactTable
createTableHook 的组合式能力靠一整套 App* 类型在编译期保证,这些类型都定义在 createTableHook.tsx 中:
AppCellContext:在核心CellContext基础上,cell属性扩展为Cell & TCellComponents & { FlexRender: () => ReactNode },即 cell 实例上直接可访问注册的单元格组件与 context 感知的 FlexRender。AppHeaderContext:同理,header属性扩展为Header & THeaderComponents & { FlexRender }。AppColumnDefBase(见类型文档):Omit<IdentifiedColumnDef, 'cell' | 'header' | 'footer'>后重新定义三者,其类型分别为AppColumnDefTemplate<AppCellContext<...>>/AppColumnDefTemplate<AppHeaderContext<...>>(footer 复用 header context)。AppColumnDefTemplate<TProps> = string | ((props: TProps) => any),即列模板既可以是静态字符串,也可以是接收增强 context 的渲染函数。AppDisplayColumnDef/AppGroupColumnDef:分别对应 display 列与 group 列(group 列额外保留columns子列数组),同样替换了 cell / header / footer 类型。AppColumnHelper:与核心ColumnHelper同构的accessor/columns/display/group四个方法,但列定义参数全部使用上述App*增强类型,让 TypeScript 在定义列时就能感知已注册的组件(例如cell: ({ cell }) => <cell.TextCell />中的TextCell是类型安全的)。AppReactTable(定义于 createTableHook.tsx:532-602):ReactTable<TFeatures, TData, TSelected> & NoInfer<TTableComponents> & { AppTable; AppCell; AppHeader; AppFooter },即useAppTable返回的扩展表格,其上直接挂载tableComponents中的组件(如<table.PaginationControls />)与四个包装组件。
CreateTableHookOptions(见类型文档)则规定了 createTableHook 可接收的选项:Omit<TableOptions<TFeatures, any>, 'columns' | 'data' | 'store' | 'state' | 'initialState'> 再加上六个可选字段——tableComponents(表级组件,如 { PaginationControls, GlobalFilter, RowCount })、cellComponents(单元格级组件,如 { TextCell, NumberCell, DateCell, CurrencyCell })、headerComponents(表头级组件,如 { SortIndicator, ColumnFilter, ResizeHandle })以及三个自定义 context(tableContext / cellContext / headerContext)。其中 tableContext 的文档特别强调:默认使用模块级共享 context,只有当你需要隔离不同表格的 context(例如表格嵌套)时才需要自行创建。
实战走读:composable-tables 示例中的完整用法
仓库的 examples/react/composable-tables 是这套组合式 API 的端到端示范,其内部结构与文档示例一一对应。
第一步:定义共享 Hook(hooks/table.ts)
export const {
createAppColumnHelper,
useAppTable,
useTableContext,
useCellContext,
useHeaderContext,
} = createTableHook({
features: tableFeatures({
columnFilteringFeature,
rowPaginationFeature,
rowSelectionFeature,
rowSortingFeature,
sortedRowModel: createSortedRowModel(),
filteredRowModel: createFilteredRowModel(),
paginatedRowModel: createPaginatedRowModel(),
filterFns: { includesString: filterFn_includesString, inNumberRange: filterFn_inNumberRange },
sortFns: { alphanumeric: sortFn_alphanumeric, text: sortFn_text },
}),
getRowId: (row) => row.id, // 默认表格选项,全局生效
tableComponents: { PaginationControls, RowCount, TableToolbar },
cellComponents: { SelectCell, TextCell, NumberCell, StatusCell, ProgressCell, RowActionsCell, PriceCell, CategoryCell },
headerComponents: { SortIndicator, ColumnFilter, FooterColumnId, FooterSum },
})
注意此处同时演示了 feature 机制与 row model 的声明式组合,以及 getRowId 等默认 options 的注入——这是旧版 getPaginationRowModel() 工厂式写法在新版中的替代形态。
第二步:注册的组件通过 context 读取实例。例如 table-components.tsx 中的 PaginationControls 用 useTableContext() 拿到表格后直接调用 table.firstPage()、table.state.pagination.pageIndex、table.setPageSize() 等 API;cell-components.tsx 中的 TextCell 用 useCellContext<string>() 后直接 cell.getValue(),NumberCell 做 toLocaleString() 本地化,PriceCell 做货币格式化;header-components.tsx 中的 SortIndicator 通过 useHeaderContext() 读取 header.column.getIsSorted() 渲染升降序箭头,ColumnFilter 则用 useSelector(table.store, ...) 订阅当前列的过滤值以保持受控输入同步。
组件内部可以自由混用多种订阅方式:SelectCell 使用 Subscribe source={table.atoms.rowSelection} 来规避 React Compiler 的 memo 化(row.getIsSelected() 是表格 API 调用,编译器无法追踪,不显式订阅就永远不会重渲染),ColumnFilter 使用 useSelector 从 table.store 投影单列过滤值,工具栏组件直接读 table.state——三者共存的模式在示例注释中均有明确说明。
第三步:业务组件组合使用(main.tsx)。UsersTable 与 ProductsTable 两个表格共享同一套 useAppTable、createAppColumnHelper 与注册组件,只是分别绑定 Person / Product 数据类型与各自列配置:
const table = useAppTable(
{
key: 'users-table', // devtools 需要
columns,
data,
debugTable: true,
enableRowSelection: true,
},
(state) => state, // 默认 selector
)
return (
<table.AppTable>
<table.TableToolbar title="Users Table" onRefresh={refreshData} onStressTest={stressTest} />
{/* 表头 */}
{table.getHeaderGroups().map((headerGroup) => (
<tr key={headerGroup.id}>
{headerGroup.headers.map((h) => (
<table.AppHeader header={h} key={h.id}>
{(header) => (
<th colSpan={header.colSpan} onClick={header.column.getToggleSortingHandler()}>
{header.isPlaceholder ? null : (
<>
<header.FlexRender />
<header.SortIndicator />
<header.ColumnFilter />
</>
)}
</th>
)}
</table.AppHeader>
))}
</tr>
))}
{/* 单元格 */}
{table.getRowModel().rows.map((row) => (
<tr key={row.id}>
{row.getAllCells().map((c) => (
<table.AppCell cell={c} key={c.id}>
{(cell) => <td><cell.FlexRender /></td>}
</table.AppCell>
))}
</tr>
))}
{/* 表尾 */}
{/* 工具栏 / 分页 / 行数 */}
<table.PaginationControls />
<table.RowCount />
</table.AppTable>
)
这里清晰展示了三个核心使用范式:useAppTable 创建实例时无需再传 features(已在 hook 层绑定);App* 包装组件通过 render-prop children 把"已预绑定注册组件"的 cell / header 交给业务层;<table.Xxx /> 直接以组件方式复用表格级组件。
如果你想要一个更轻量、不使用 createTableHook 的入门对照,可参考 examples/react/basic-use-table/src/main.tsx,它展示了 tableFeatures({}) + createColumnHelper<typeof features, Person>() + useTable 的最小三件套,以及用 <table.FlexRender header={header} />、<table.FlexRender cell={cell} />、<table.FlexRender footer={header} /> 渲染三区块的标准写法。
源码结构速查与阅读指引
如果你想深入研读实现而非仅使用 API,推荐按以下顺序阅读源码:
- packages/react-table/src/index.ts —— 导出面全景(仅 6 行,是最快的入口);
- packages/react-table/src/useTable.ts ——
ReactTable类型定义(Subscribe重载设计、state语义、store弃用说明都集中在这里); - packages/react-table/src/useTable.ts ——
useTable实现(constructTable、table_setOptions、useSelector、markCommitted、table_publishExternalState的完整调用链); - packages/react-table/src/createTableHook.tsx —— 组合式架构全部类型与
App*组件实现; - packages/react-table/src/FlexRender.tsx ——
flexRender的组件判定与分组/聚合单元格处理; - packages/react-table/src/Subscribe.ts —— 独立版
Subscribe组件与SubscribeProps*类型。
配套类型文档可查阅 docs/framework/react/reference/index/type-aliases 目录下的 ReactTable、FlexRenderProps、SubscribeSource、AppReactTable 等条目,每个条目都标注了定义的精确源码行号(Defined in),便于对照阅读。
小结
@tanstack/react-table 的 API 面可以概括为三个层次:useTable 负责实例创建与 state 投影,Subscribe / flexRender / FlexRender 负责渲染层的定向订阅与模板分发,createTableHook 负责将 features、默认选项与三类组件统一预绑定,形成一套可在多个表格间复用的组合式架构。legacy 模块则保留了 v8 风格的 row model 工厂与旧类型以兼容存量代码。掌握 reference/index.md 这条索引,加上 packages/react-table/src 的源码对照与 examples/react/composable-tables 的完整示例,即可在生产项目中灵活驾驭这套 API。