TanStack Table React:getFacetedUniqueValues() 兼容函数解析与 v9 迁移指南

原创2026-09-20 17:24:011,676 阅读
文章标签:前端UI组件

TanStack Table React:getFacetedUniqueValues() 兼容函数解析与 v9 迁移指南

本篇文章聚焦 TanStack Table 的 React 版本(本仓库中的 @tanstack/react-table)在 v9 中提供的一个特殊兼容函数 getFacetedUniqueValues()。该函数位于 useLegacyTable 的 v8 兼容层中,本身并不计算任何数据,而是作为"标记(marker)"告诉兼容 Hook 启用列刻面(column faceting)的"唯一值统计"能力。读完本文,你将完整理解它的签名、内部实现、与 v9 新版 useTable + createFacetedUniqueValues() 的关系,以及如何把旧版 facet 代码平滑迁移到新 API。

函数签名与文档定位

在 docs/framework/react/reference/legacy/functions/getFacetedUniqueValues.md 中,该函数被声明为:

function getFacetedUniqueValues<TData>(): FacetedUniqueValuesFactory<TData>;

其中:

  • 泛型参数 TData:继承自 RowData,代表表格行数据类型;
  • 返回值:FacetedUniqueValuesFactory<TData>,即一个"工厂函数生成器"——它接收表格实例与列 ID,返回一个用于产出 Map<any, number>(值 → 出现次数)的函数。

文档明确标注了该函数 Deprecated(已弃用):v9 中请改用新 useTable Hook 搭配 createFacetedUniqueValues(),并指出它"是用于 useLegacyTable 的 v8 API 兼容 stub 函数,仅作为启用刻面唯一值功能的标记"。换言之,它是 TanStack Table 从 v8 升级到 v9 时提供"旧 API 可用性"的过渡产物。

Stub 函数:它真的什么都不做吗

对照源码实现,packages/react-table/src/useLegacyTable.ts 中该函数的完整实现只有三行:

export function getFacetedUniqueValues<
  TData extends RowData,
>(): FacetedUniqueValuesFactory<TData> {
  return () => () => new Map()
}

可以看到:

  • 它返回一个"函数,返回另一个函数",最内层直接返回一个空 Map,没有任何数据遍历或统计逻辑;
  • 注释明确写道:"These are stub functions that act as markers for useLegacyTable to know which row models to enable. They don't actually do anything - the real implementation is handled by useLegacyTable internally."(这些是 stub 函数,作为标记让 useLegacyTable 知道要启用哪些 row model;它们实际上不做任何事,真正的实现由 useLegacyTable 内部处理)。

因此,getFacetedUniqueValues 的价值不在于执行,而在于"存在"——只要你在选项里传入了它,兼容层就知道用户想要刻面唯一值功能。

FacetedUniqueValuesFactory 类型签名解析

在同一文件中定义的 FacetedUniqueValuesFactory 类型(useLegacyTable.ts)给出了该工厂的真实契约:

export type FacetedUniqueValuesFactory<TData extends RowData> = (
  table: Table<LegacyFeatures, TData>,
  columnId: string,
) => () => Map<any, number>

三个关键点:

  1. 入参:table(LegacyFeatures 绑定的表格实例)与 columnId(目标列 ID);
  2. 出参:返回一个无参函数,调用后得到 Map<any, number>,键为去重后的单元格值,值为该值在刻面行集中出现的次数;
  3. LegacyFeatures:useLegacyTable 注册的特性集,它在 stockFeatures 基础上合并了内置的 filterFns、sortFns、aggregationFns 注册表(见 useLegacyTable.ts),因此旧版列定义中的字符串标识符(如 'includesString')在 v8 兼容层内仍然可用。

useLegacyTable 如何消费这个标记

useLegacyTable 在初始化时读取这些"标记选项",并转换为 v9 的 feature 配置(useLegacyTable.ts):

if (getFacetedRowModel) {
  legacyFeatures.facetedRowModel = createFacetedRowModel()
}
if (getFacetedMinMaxValues) {
  legacyFeatures.facetedMinMaxValues = createFacetedMinMaxValues()
}
if (getFacetedUniqueValues) {
  legacyFeatures.facetedUniqueValues = createFacetedUniqueValues()
}

也就是:当你传入 getFacetedUniqueValues 时,useLegacyTable 会在内部调用 table-core 的 createFacetedUniqueValues() 来构造真实的刻面唯一值工厂,并注册到 legacyFeatures.facetedUniqueValues 槽位,随后这些 features 被原样交给新的 useTable(见 useLegacyTable.ts)。这与同文件中的其他 stub 函数(getFilteredRowModel、getSortedRowModel、getFacetedMinMaxValues 等)的处理方式完全一致。

还需要注意一个生命周期细节:这些标记选项是 setup-only(仅初始化生效) 的——它们只在 useState 初始化器(第一次渲染)中被读取一次,用于匹配表格实例的生命周期,之后对选项对象的改动不会重新生效。

v9 真正的实现:createFacetedUniqueValues 的工作原理

刻面唯一值能力的真实计算在 table-core 的 packages/table-core/src/features/column-faceting/createFacetedUniqueValues.ts 中完成。createFacetedUniqueValues() 返回的工厂函数:

  • 使用 tableMemo 对结果做记忆化缓存(feature 名为 columnFacetingFeature),避免在行集未变化时重复计算;
  • 依赖 column.getFacetedRowModel()(即"应用了其他列过滤、但排除了本列自身过滤"的行模型)的 flatRows 作为统计来源;
  • 当 columnId === '__global__' 时,改从全局刻面行模型 getGlobalFacetedRowModel 取行,并遍历所有参与全局过滤的叶子列来聚合唯一值;
  • 最终遍历每一行的 getUniqueValues(columnId) 结果,累加每个值出现的次数,产出 Map<any, number>。

对应的缓存与回退逻辑在 packages/table-core/src/features/column-faceting/columnFacetingFeature.utils.ts:

  • column_getFacetedUniqueValues(column, table) 按列 ID 惰性创建并缓存工厂函数;
  • 若 features.facetedUniqueValues 未注册,则回退到 createStableEmptyMapFn()——注意这里特意返回同一个空 Map 实例,保证引用稳定,与内置工厂的记忆化行为保持一致;
  • 全局版本 table_getGlobalFacetedUniqueValues(table) 采用同样的回退策略。

对外暴露的 API 类型定义在 packages/table-core/src/features/column-faceting/columnFacetingFeature.types.ts:Column.getFacetedUniqueValues()、Table.getFacetedUniqueValues() 与 Table.getGlobalFacetedUniqueValues() 均返回 Map<any, number>。

典型使用场景:faceted filtering(分面筛选)

刻面唯一值最常见的落地场景是"faceted filtering":筛选器面板在用户输入/选择前,就为每个候选值展示"该值对应多少行",即"选项 + 计数"的分面选择器。仓库中的 examples/react/filters-faceted 示例即演示了这一用法,其典型链路为:

  1. 定义列时启用该列的 enableFacetedValues 等刻面相关配置;
  2. 通过 column.getFacetedUniqueValues()(或全局的 table.getGlobalFacetedUniqueValues())读取 Map<any, number>;
  3. 遍历该 Map 渲染 <option>(或 checkbox),并显示每个值的出现次数;
  4. 当用户切换其他列的筛选条件时,由于刻面行模型会排除"当前列自身的过滤"但保留其他列过滤,选项计数会自动收缩到"在剩余数据集中仍然出现的值",实现动态可用的筛选选项。

值得注意的是,createFacetedUniqueValues 的实现对**无 accessor 的列(如 display 列)**做了防御处理:getUniqueValues 返回 undefined 时直接 continue 跳过(见 createFacetedUniqueValues.ts),不会因空值抛出异常。

迁移指南:从 getFacetedUniqueValues 到 createFacetedUniqueValues

useLegacyTable 文档(docs/framework/react/reference/legacy/functions/useLegacyTable.md)给出了完整的迁移方向。旧写法:

import { useLegacyTable, getFacetedUniqueValues, getFacetedRowModel } from '@tanstack/react-table'

const table = useLegacyTable({
  columns,
  data,
  getFacetedUniqueValues,
  getFacetedRowModel,
  // ...其他 v8 风格选项
})

新写法(v9 显式 features):

import { useTable } from '@tanstack/react-table'
import {
  createFacetedUniqueValues,
  createFacetedRowModel,
  columnFacetingFeature,
} from '@tanstack/table-core'

const features = tableFeatures({
  columnFacetingFeature,
  facetedRowModel: createFacetedRowModel(),
  facetedUniqueValues: createFacetedUniqueValues(),
})

const table = useTable({
  features,
  columns,
  data,
})

迁移时的几条关键差异:

  1. 特性可 tree-shake(按需引入):v9 中只有你显式传入 features 的功能才会被打包,getFacetedUniqueValues 这类隐式标记不复存在;
  2. 行模型与函数注册表显式化:facetedRowModel、facetedUniqueValues 槽位必须显式传入工厂函数,而不是通过"是否存在标记函数"推断;
  3. 状态访问方式变化:useLegacyTable 返回的表格实例带有 v8 风格的 getState()/setState() 方法,而 v9 中应通过 table.state 读取状态、通过 table.baseAtoms 做细粒度更新(见 useLegacyTable.ts);
  4. 细粒度渲染:v9 建议使用 table.Subscribe 进行按需重渲染,替代 v8 式的全量订阅。

注意事项与最佳实践

  • 不要在 v9 新代码中使用 stub 函数:getFacetedUniqueValues 仅服务于 useLegacyTable 兼容场景,新代码请直接使用 createFacetedUniqueValues();
  • 标记选项是 setup-only:useLegacyTable 只在首次渲染读取这些标记,运行时修改不会生效;
  • 未注册工厂时的行为:若未配置 facetedUniqueValues 工厂,getFacetedUniqueValues() 相关 API 会返回引用稳定的空 Map(参考 columnFacetingFeature.utils.ts),因此消费方应处理"空 Map"的情况;
  • 全局刻面上下文:__global__ 是内部保留的列 ID,用于全局过滤场景下跨所有可全局过滤叶子列聚合唯一值,不要自行占用该 ID 作为业务列名。

综上,getFacetedUniqueValues() 是 TanStack Table v9 为了 v8 用户平稳升级而保留的"空壳标记",理解它的实现与消费链路,是掌握 useLegacyTable 兼容层以及后续迁移到 useTable + createFacetedUniqueValues() 新范式的最佳切入点。

登录后查看全文
table