@tanstack/octane-table API 参考:TanStack Table v9 的 Octane 适配层接口与函数全解
@tanstack/octane-table API 参考:TanStack Table v9 的 Octane 适配层接口与函数全解
本文是 @tanstack/octane-table 官方 API 参考索引(docs/framework/octane/reference/index.md)的深度展开。@tanstack/octane-table 是 TanStack Table v9 针对 Octane 渲染器 的框架适配层:它原样复用框架无关的 @tanstack/table-core(可摇树优化的 features、TanStack Store 原子状态),并额外提供 useTable、Subscribe、FlexRender、createTableHook 等 Octane 专属 API。读完本文,你将掌握该包完整的函数、接口、类型别名与变量清单,理解 useTable 与 useAppTable 的选择器订阅机制,并能在 .tsrx 文件中用预绑定组件搭建可组合、类型完备的数据表格。
一、包定位:core 与 adapter 的分层架构
从包入口 packages/octane-table/src/index.ts 可以看出 v9 的核心设计:框架无关的表格逻辑(constructTable、可摇树的 features、由 TanStack Store atoms 支撑的每个状态切片)全部位于 @tanstack/table-core,而本包只做两件事——原样 re-export core,以及把适配器移植到 Octane:
export * from '@tanstack/table-core'
export * from './FlexRender'
export * from './Subscribe.tsrx'
export * from './createTableHook.tsrx'
export * from './createTableHookContexts'
export * from './types'
export * from './useTable.tsrx'
因此,本文参考索引中的每一项 API 都属于适配层:useTable 负责在 Octane 组件内创建表格实例,FlexRender/flexRender 负责渲染列的 header/cell/footer 定义,Subscribe 提供显式状态订阅,createTableHook 把"特征组合 + 组件约定"封装成应用级 hook。
安装方式(详见 Octane 快速上手):
npm install @tanstack/octane-table
二、函数 API:表格实例的创建与渲染
1. useTable() —— 创建 Octane 表格实例
useTable 是核心入口,签名见 functions/useTable.md:
function useTable<TFeatures, TData, TSelected>(tableOptions, selector?): OctaneTable<TFeatures, TData, TSelected>
TFeatures extends TableFeatures:由tableFeatures({...})产出的特征组合类型;TData extends RowData:行数据类型;TSelected = TableState<TFeatures>:默认选中完整表状态,也可通过第二个参数selector投影出状态切片;tableOptions: TableOptions<TFeatures, TData>:包含data、columns、features、initialState等。
典型用法(摘录自 快速上手 的完整示例):
const features = tableFeatures({})
const table = useTable({
features,
columns,
data,
})
v9 的 features 是按需注册的:tableFeatures({}) 只声明用到的可选特征(如 rowSortingFeature、createSortedRowModel()、sortFns),核心行模型始终内置,未注册的特征既不会进入 bundle,也不会出现在类型中。
2. createTableHook() —— 组合可复用表格
签名见 functions/createTableHook.md:
function createTableHook<TFeatures, TTableComponents, TCellComponents, THeaderComponents>(
options
): CreateTableHookResult<TFeatures, TTableComponents, TCellComponents, THeaderComponents>
它把「共享的 features、行模型、组件约定」固化一次,返回 useAppTable 与 createAppColumnHelper。快速上手给出的最小形态:
const features = tableFeatures({
rowSortingFeature,
sortedRowModel: createSortedRowModel(),
sortFns,
})
const { useAppTable, createAppColumnHelper } = createTableHook({ features })
之后每个页面只需:
const table = useAppTable({ columns, data })
注意 useAppTable 的 tableOptions 是 Omit<TableOptions, "features">——features 已经固化在 hook 里,无需重复传入。完整模式(含预绑定 cell/header 组件)见 Composable Tables 指南。
3. createTableHookContexts() —— 隔离的上下文逃生舱
签名见 functions/createTableHookContexts.md:
function createTableHookContexts<TFeatures, TData>(): TableHookContexts<TFeatures, TData>
它创建一组全新的、作用域隔离的 table/cell/header context 及配套 hook,镜像 TanStack Form 的 createFormHookContexts 设计。通常你不需要它:默认情况下 createTableHook 会把 AppTable/AppCell/AppHeader 的 provider 接到共享的模块级 context 上。只有当一张表嵌套在另一张表内部、消费者可能读到错误的最近 provider 时,才需要独立 context:
// scoped-table-context.ts
export const {
tableContext, cellContext, headerContext,
useTableContext, useCellContext, useHeaderContext,
} = createTableHookContexts<typeof features>()
// table.ts
export const { useAppTable } = createTableHook({
features,
tableContext, // 传入 scoped context,让 provider 使用它们
cellContext,
headerContext,
tableComponents: { PaginationControls },
})
类型提示:这些返回的 hook 只以 TFeatures 为类型参数,不感知 createTableHook 中注册的组件映射(因为组件映射定义在其后)。要获得最丰富的类型(App* 组件与注册组件均已附加),优先使用 createTableHook 返回的 use*Context hooks。
4. flexRender() 与 FlexRender() —— 渲染列定义
底层工具函数 flexRender(functions/flexRender.md):
function flexRender<TProps>(Comp, props): unknown
官方注释明确建议:自定义渲染 header/cell/footer 时,用 flexRender 而不是 cell.getValue() 或 cell.renderValue()。例如:
flexRender(cell.column.columnDef.cell, cell.getContext())
其实现位于 packages/octane-table/src/FlexRender.ts,并带有一段重要的移植说明:上游还会检测 class 组件与 react.memo/react.forwardRef 这类 exotic 对象,但这两个分支在 octane 中都是死代码——没有 class 组件或 forwardRef,且 octane 的 memo() 返回普通函数,所以组件判定就是 typeof === 'function';非组件值(字符串、数字、预创建的 descriptor)原样透传。
组件形式 FlexRender(functions/FlexRender-1.md)是它的简化封装,只能传 cell、header、footer 三者之一:
<FlexRender cell={cell} />
<FlexRender header={header} />
<FlexRender footer={footer} />
等价于手动调用三次 flexRender(...)。在 useTable 返回的表格实例上,它被绑定为 table.FlexRender(见下文 OctaneTable 类型),这是快速上手示例中 table.FlexRender header={header} 的由来。
三、变量:Subscribe
参考索引中的 Variables 仅一项:Subscribe(variables/Subscribe.md)。它是显式订阅组件,支撑细粒度状态订阅场景。OctaneTable 类型中展示了其完整重载形态(见 type-aliases/OctaneTable.md):三个重载分别覆盖「带 source、无 selector」「带 source + selector」「直接传 store」三种用法,这样设计是为了让 JSX 中的 selector 回调获得正确的上下文类型——如果两个 selector 签名合成一个 union,会退化成隐式 any。其 props 类型体系见 SubscribeProps、SubscribePropsWithSource、SubscribePropsWithStore、SubscribeSource、SubscribeStaticChild 等类型别名。
使用建议(来自 OctaneTable.store 的弃用注释):渲染期读取用 table.state,切片快照用 table.atoms.<slice>.get(),显式订阅用 table.Subscribe 或 useSelector(table.store, selector);table.store.state 只是当前值快照,在渲染代码中容易误用。
四、核心类型别名:表格实例与选项
1. OctaneTable —— useTable 的返回类型
type OctaneTable<TFeatures, TData, TSelected> = Omit<Table<TFeatures, TData>, "store"> & object
即:table-core 的框架无关 Table,去掉 store 属性,再加上 Octane 的 Subscribe/FlexRender 组件与选中的 state:
FlexRender:渲染 header/cell/footer 的 Octane 组件,<table.FlexRender cell={cell} />这类用法;state:readonly Readonly<TSelected>,即经useTable第二参数 selector 投影后的状态。例如useTable(options, (state) => ({ globalFilter: state.globalFilter }))后table.state只含globalFilter;store(已弃用):table.store.state是当前值快照,易在渲染中误用,优先使用上面的替代方案;Subscribe:带三个重载的订阅组件(见第三节)。
2. AppOctaneTable —— useAppTable 的返回类型
type AppOctaneTable<TFeatures, TData, TSelected, TTableComponents, TCellComponents, THeaderComponents> =
OctaneTable<TFeatures, TData, TSelected> & CoreNoInfer<TTableComponents> & object
它在 OctaneTable 基础上附加四个 App 包装组件(type-aliases/AppOctaneTable.md):
AppTable:根包装组件,提供 table context,可选 selector 订阅。无 selector 时 children 是 renderable;有 selector 时 children 接收选中状态:
<table.AppTable>
<table>…</table>
</table.AppTable>
<table.AppTable selector={(s) => s.pagination}>
{(pagination) => <div>{pagination.pageIndex as unknown as string}</div>}
</table.AppTable>
AppHeader/AppFooter:包装 header/footer 并提供 header context(footer 也走 header context),预绑定headerComponents:
<table.AppHeader header={header}>
{(h) => <th><h.SortIndicator /></th>}
</table.AppHeader>
<table.AppFooter header={footer}>
{(f) => <td><f.FlexRender /></td>}
</table.AppFooter>
AppCell:包装 cell 并提供 cell context,预绑定cellComponents:
<table.AppCell cell={cell}>
{(c) => <td><c.TextCell /></td>}
</table.AppCell>
3. CreateTableHookOptions —— createTableHook 的选项
(type-aliases/CreateTableHookOptions.md)类型为:
type CreateTableHookOptions<TFeatures, TTableComponents, TCellComponents, THeaderComponents> =
Omit<TableOptions<TFeatures, any>, "columns" | "data" | "store" | "state" | "initialState"> & object
继承除 columns/data/store/state/initialState 之外的全部 TableOptions,并新增:
| 选项 | 类型 | 说明 |
|---|---|---|
tableComponents? |
Record<string, TableComponentType> |
需要访问表格实例的组件,如 { PaginationControls, GlobalFilter, RowCount },直接挂在 useAppTable 返回的 table 对象上,内部用 useTableContext() 读取 |
cellComponents? |
Record<string, TableComponentType> |
需要访问 cell 实例的组件,如 { TextCell, NumberCell, DateCell, CurrencyCell },通过 AppCell 的 children 获得,内部用 useCellContext() |
headerComponents? |
Record<string, TableComponentType> |
需要访问 header 实例的组件,如 { SortIndicator, ColumnFilter, ResizeHandle },内部用 useHeaderContext()(footer 组件同样可用) |
tableContext? |
Context<OctaneTable> |
自定义 table context,默认是共享模块级 context;嵌套表格需要隔离时传入 createContext 创建的自有 context |
cellContext? / headerContext? |
Context<Cell> / Context<Header> |
同理,为 cell / header 实例的自定义 context |
4. 列定义与渲染相关类型
AppColumnDefBase/AppColumnDefTemplate/AppDisplayColumnDef/AppGroupColumnDef:App 层列定义类型,泛型中携带TFeatures与已注册的TCellComponents/THeaderComponents,因此header/cell/footer的渲染函数参数上能看到绑定后的组件与 FlexRender;TableComponentType:注册到tableComponents/cellComponents/headerComponents的组件类型约束(Record<string, ...>的值类型);FlexRenderProps:table.FlexRender/ 独立<FlexRender>的 props(cell、header、footer三选一,泛型带TFeatures/TData/TValue);Renderable:flexRender第一个参数Comp的类型,即"可渲染定义"(普通值或组件函数);Subscribe*系列:SubscribeProps、SubscribePropsWithSource、SubscribePropsWithStore、SubscribeSource、SubscribeStaticChild——分别描述订阅组件的 props(带 source / 带 store)、source 定义与静态 children 类型。
五、接口:App 组件 props 与上下文
1. App 组件 props:WithSelector / WithoutSelector 双形态
AppTablePropsWithSelector / AppCellPropsWithSelector 等接口(参考索引 Interfaces 部分)把 props 拆成两个形态:
-
WithSelector 形态(如 AppCellPropsWithSelector):
cell: Cell<TFeatures, TData, TValue>(AppTable 版本则是 children 直接渲染)children: (cell, state) => unknownselector: (state) => TSelected
此时组件既提供 context,又充当
Subscribe订阅节点,children 拿到的是选中切片后的状态; -
WithoutSelector 形态(
AppCellPropsWithoutSelector/AppTablePropsWithoutSelector/AppHeaderPropsWithoutSelector):无selector,children 只接收实例本身,不做状态订阅。
2. 组件与上下文接口
AppCellComponent/AppHeaderComponent/AppTableComponent:三个 App 包装组件的组件类型(table.AppCell、table.AppHeader、table.AppFooter、table.AppTable各自的类型签名),泛型中携带各自绑定的组件映射;AppCellContext/AppHeaderContext:cell / header 上下文中暴露给useCellContext()/useHeaderContext()的实例形态——Cell_Core & ExtractFeatureMapTypes<...> & TCellComponents & { FlexRender },即核心实例 + 特征 API + 注册组件 + 上下文绑定的 FlexRender;AppColumnHelper:createAppColumnHelper返回的列辅助器,预绑定TFeatures与注册组件;TableHookContexts:createTableHookContexts的返回结构(tableContext、cellContext、headerContext及三个use*Contexthooks);CreateTableHookResult(interfaces/CreateTableHookResult.md):createTableHook的返回结构,完整成员包括:appFeatures:传入的 features 对象(types.ts:814);createAppColumnHelper: <TData>() => AppColumnHelper<...>(types.ts:819);useAppTable: <TData, TSelected>(tableOptions, selector?) => AppOctaneTable<...>(types.ts:829);useTableContext: <TData, TSelected>() => AppOctaneTable<...>(types.ts:851),读取最近<table.AppTable>提供的表格实例,与useAppTable返回的是同一个扩展实例;useCellContext/useHeaderContext(types.ts:866/types.ts:877):读取最近<table.AppCell>/<table.AppHeader>/<table.AppFooter>提供的实例,并附加注册组件与 context 绑定的 FlexRender。- 类型提示:
useTableContext的TSelected无法自动推断(context 不携带 provider 的泛型),需与useAppTable的 selector 保持一致,默认全量状态即可覆盖最常见的无 selector 用法。
六、状态管理:Store atoms 与选择器订阅
v9 的表格状态由 TanStack Store atoms 支撑(见 Table State 指南,它是其它一切指南的基础)。从 OctaneTable 的文档可以提炼出三种读取方式:
- 渲染期读取:直接用
table.state(已被 selector 投影); - 切片快照:
table.atoms.<slice>.get(); - 显式订阅:
table.Subscribe(带 source / selector 重载)或useSelector(table.store, selector)。
通常你无需自行管理状态:设置 initialState 作为初值,调用 table.setSorting(...)、table.nextPage() 等特征 API 即可。只有应用需要"自己拥有某个状态切片"或需要细粒度订阅时,才引入选择器与 Subscribe 机制。
七、源码位置速查
- 适配层入口与 re-export:packages/octane-table/src/index.ts
flexRender与FlexRender实现:packages/octane-table/src/FlexRender.tsuseTable/createTableHook组件实现:packages/octane-table/src/useTable.tsrx、packages/octane-table/src/createTableHook.tsrxcreateTableHookContexts实现:packages/octane-table/src/createTableHookContexts.ts- 全部类型定义(
OctaneTable在types.ts:202、CreateTableHookOptions在types.ts:535、AppCellPropsWithSelector在types.ts:618、AppOctaneTable在types.ts:733、CreateTableHookResult在types.ts:807):packages/octane-table/src/types.ts
八、延伸阅读
- Octane 快速上手:从安装到第一个可排序表格的完整示例
- Composable Tables 指南:
createTableHook+ 预绑定组件的完整模式 - Flex Render 指南:
flexRender/FlexRender的自定义渲染实践 - Table State 指南:Store atoms 状态模型的底层说明
- 可运行的完整示例(含更多列与 footer):examples/octane/basic-use-table