TanStack Table React:getFacetedUniqueValues() 兼容函数解析与 v9 迁移指南
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>
三个关键点:
- 入参:
table(LegacyFeatures绑定的表格实例)与columnId(目标列 ID); - 出参:返回一个无参函数,调用后得到
Map<any, number>,键为去重后的单元格值,值为该值在刻面行集中出现的次数; 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 示例即演示了这一用法,其典型链路为:
- 定义列时启用该列的
enableFacetedValues等刻面相关配置; - 通过
column.getFacetedUniqueValues()(或全局的table.getGlobalFacetedUniqueValues())读取Map<any, number>; - 遍历该
Map渲染<option>(或 checkbox),并显示每个值的出现次数; - 当用户切换其他列的筛选条件时,由于刻面行模型会排除"当前列自身的过滤"但保留其他列过滤,选项计数会自动收缩到"在剩余数据集中仍然出现的值",实现动态可用的筛选选项。
值得注意的是,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,
})
迁移时的几条关键差异:
- 特性可 tree-shake(按需引入):v9 中只有你显式传入
features的功能才会被打包,getFacetedUniqueValues这类隐式标记不复存在; - 行模型与函数注册表显式化:
facetedRowModel、facetedUniqueValues槽位必须显式传入工厂函数,而不是通过"是否存在标记函数"推断; - 状态访问方式变化:
useLegacyTable返回的表格实例带有 v8 风格的getState()/setState()方法,而 v9 中应通过table.state读取状态、通过table.baseAtoms做细粒度更新(见 useLegacyTable.ts); - 细粒度渲染: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() 新范式的最佳切入点。