tanstack-ember-table-create-table-hook

用途

该技能用于在 TanStack Ember Table v9 中创建应用级表格工厂。当若干张表共享真实的 features 或默认配置时，使用 app factory；一次性的表格仍应使用 useTable。它建立在 @tanstack/table-core 的 core、getting-started 与 table-state 之上。

主要能力

通过 createTableHook 在一个稳定模块作用域内定义共享的 features 与默认表格选项，并导出 appFeatures、createAppColumnHelper、createAppTable。
createAppTable 保留 useTable 的选项 thunk，因此像 this.data 这样的被追踪读取仍保持响应式。
createAppColumnHelper<TData>() 绑定 feature 类型，并推断每一行的类型。
createAppTable(() => options) 将共享默认值与表格专属选项合并。
appFeatures 暴露已注册的确切 feature 集合，供辅助类型或可复用工具使用。

使用方式

设置

import Component from '@glimmer/component'
import { tracked } from '@glimmer/tracking'
import {
  createSortedRowModel,
  createTableHook,
  rowSortingFeature,
  sortFn_alphanumeric,
  tableFeatures,
} from '@tanstack/ember-table'

const features = tableFeatures({
  rowSortingFeature,
  sortedRowModel: createSortedRowModel(),
  sortFns: { alphanumeric: sortFn_alphanumeric },
})

export const { appFeatures, createAppColumnHelper, createAppTable } =
  createTableHook({
    features,
    enableSortingRemoval: false,
  })

type Person = { id: string; name: string }
const columnHelper = createAppColumnHelper()
const columns = columnHelper.columns([
  columnHelper.accessor('name', { header: 'Name' }),
])

export default class PeopleTable extends Component {
  @tracked data: Person[] = []

  table = createAppTable(() => ({
    columns,
    data: this.data,
  }))
}

在稳定的模块作用域创建 hook 与 column helper。不要在表格调用点再次传入 features；factory 拥有 feature 集合并将其绑定进列推断。

组合契约

Hook 选项提供稳定的共享 features 与默认表格选项。
createAppColumnHelper<TData>() 绑定 feature 类型，同时推断每一行的类型。
createAppTable(() => options) 将共享默认值与表格专属选项合并。
表格专属选项优先于共享默认值，但 factory 仍是 feature 的拥有者。
appFeatures 暴露已注册的确切 feature 集合，供辅助类型或可复用工具使用。

共享选项有意排除 columns、data 与 state。将模型输入与受控状态保留在每张表的调用点；共享的是约定，而不是把同一个可变状态对象共享给互不相关的表格。

共享 rowSortingFeature、sortedRowModel 与排序默认值会让每张表都具备排序能力；这并不会让它们内部的排序状态被共享。factory 技术上接受在共享 atoms 中放入一个稳定的外部 atom，但这会刻意将各表及其列 ID 耦合起来。除非同步表格就是实际的产品行为，否则优先使用独立状态。

渲染方式

Ember 的 factory 不注册 AppTable、AppCell、AppHeader、context hooks 或可复用组件注册表。继续使用 FlexRenderCell、FlexRenderHeader 与 FlexRenderFooter 进行渲染。继续按照 getting-started 中描述的方式，将依赖接收者的 v9 方法包装进 Ember 模板辅助工具。

适用场景

适用于多张表格共享同一套功能或默认配置的场景。共享 rowSortingFeature、sortedRowModel 与排序默认值时，每张表都获得排序能力，而各自的内部排序状态相互独立。

限制与常见错误

高：照搬其他适配器的组件注册表

错误：期望来自 React、Solid、Svelte 或 Lit 示例的 table.AppTable、useTableContext，或 tableComponents 选项。

正确：使用常规的 Ember FlexRender 组件，并在另一个组件确实需要时通过普通的 Ember 组合传入 table。

Ember hook 只共享 features、默认值与类型推断。

高：按表传入 features

错误：

createAppTable(() => ({ features: otherFeatures, columns, data: this.data }))

正确：当某张表需要一套确实不同的 feature 集时，单独定义一个 app hook。createAppTable 在调用点类型中省略了 features。

高：在追踪更新中重建 hook 或 columns

错误：在组件 getter 或 createAppTable thunk 内调用 createTableHook、createAppColumnHelper 或 columns(...)。

正确：在模块作用域创建一次，让表格 thunk 只读取会变化的输入。

中：把受控状态作为默认值共享

hook 选项省略 state。将 state 与匹配的 on[State]Change 回调放入每个 createAppTable thunk，使每张表对每个切片都有一个明确的拥有者。仅当各表有意协调同一个兼容切片时，才使用共享的外部 atom。

中：重复手写 feature 泛型

使用 createAppColumnHelper<Person>(); 不要在 factory 已经捕获之后，还在每个 column helper 上来回传递 typeof features。

API 探查

检查 node_modules/@tanstack/ember-table/declarations/create-table-hook.d.ts 以了解已安装 factory 的返回形态、被省略的选项与合并优先级。检查 use-table.d.ts 了解 thunk 响应式，检查 node_modules/@tanstack/table-core/dist/features/<feature>/ 了解共享 feature API。不要从其他适配器的 createTableHook 推断 Ember 组件/上下文行为。