@tanstack/octane-table API 参考:TanStack Table v9 的 Octane 适配层接口与函数全解

原创2026-09-19 14:11:181,672 阅读
文章标签:前端UI组件

@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) => unknown
    • selector: (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*Context hooks);
  • 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 的文档可以提炼出三种读取方式:

  1. 渲染期读取:直接用 table.state(已被 selector 投影);
  2. 切片快照:table.atoms.<slice>.get();
  3. 显式订阅:table.Subscribe(带 source / selector 重载)或 useSelector(table.store, selector)。

通常你无需自行管理状态:设置 initialState 作为初值,调用 table.setSorting(...)、table.nextPage() 等特征 API 即可。只有应用需要"自己拥有某个状态切片"或需要细粒度订阅时,才引入选择器与 Subscribe 机制。

七、源码位置速查

八、延伸阅读

登录后查看全文
table