typescript

本技能基于 core 和 table-features 构建。让 feature 对象和辅助函数在用户代码中传递类型。

设置

import {
  createColumnHelper,
  metaHelper,
  tableFeatures,
} from '@tanstack/table-core'

type Person = { id: string; age: number }
type ColumnMeta = { align?: 'start' | 'end' }
const features = tableFeatures({ columnMeta: metaHelper<ColumnMeta>() })
const helper = createColumnHelper<typeof features, Person>()
export const columns = helper.columns([
  helper.accessor('age', { meta: { align: 'end' } }),
])

核心模式

保留异构访问器的值类型

const columns = helper.columns([
  helper.accessor('id', { header: 'ID' }),
  helper.accessor('age', { header: 'Age' }),
])

columns() 会保留每个访问器的 TValue，而不会将数组类型拓宽。

通过辅助函数组合选项

const defaults = tableOptions<typeof features, Person>({
  defaultColumn: { meta: { align: 'start' } },
})

对于可复用的片段，使用 tableOptions；对于一次性的场景，直接使用适配器选项即可。

常见错误

[HIGH] 抹除访问器值的类型推断

错误写法：

const columns: ColumnDef<typeof features, Person, unknown>[] = [
  helper.accessor('age', {}),
]

正确写法：

const columns = helper.columns([helper.accessor('age', {})])

宽泛的类型注解会丢弃访问器特定的 number 值类型。

来源：docs/guide/helpers.md#createcolumnhelper

[MEDIUM] 手动传递内部 feature 泛型

错误写法：

type Features = TableFeatures

正确写法：

type Features = typeof features

具体的注册表是 feature 门控 API 和注册表键的来源。

来源：packages/table-core/src/types/TableFeatures.ts

[MEDIUM] 全局合并单表 meta

错误写法：

declare module '@tanstack/table-core' {
  interface ColumnMeta<TData, TValue> {
    align?: string
  }
}

正确写法：

const features = tableFeatures({
  columnMeta: metaHelper<{ align?: 'start' | 'end' }>(),
})

V9 中仅用于类型的 feature 插槽会将 meta 类型限定在表格工厂范围内。

来源：docs/guide/table-and-column-meta.md

API 发现

检查 node_modules/@tanstack/table-core/dist/helpers/ 以及 dist/index.d.ts 重新导出的签名；避免将深层内部泛型签名复制到应用代码中。