column-faceting

用途

column-faceting 用于构建分面筛选（faceted filter）界面。它建立在核心（core）、表格功能（table-features）和列筛选（column-filtering）之上，负责从数据中派生出筛选选项，本身不渲染任何筛选控件。

主要能力

该技能提供以下分面能力：

columnFacetingFeature：启用列分面功能。
facetedRowModel：分面行模型。
facetedUniqueValues：派生离散列的唯一值及其计数。
facetedMinMaxValues：派生数值列的最小/最大值范围。

离散控件使用唯一值，数值范围仅使用最小/最大值。

使用方式

设置

import {
  columnFacetingFeature,
  columnFilteringFeature,
  createFacetedMinMaxValues,
  createFacetedRowModel,
  createFacetedUniqueValues,
  createFilteredRowModel,
  filterFn_includesString,
  filterFn_inNumberRange,
  tableFeatures,
} from '@tanstack/table-core'

export const features = tableFeatures({
  columnFilteringFeature,
  filteredRowModel: createFilteredRowModel(),
  filterFns: {
    includesString: filterFn_includesString,
    inNumberRange: filterFn_inNumberRange,
  },
  columnFacetingFeature,
  facetedRowModel: createFacetedRowModel(),
  facetedUniqueValues: createFacetedUniqueValues(),
  facetedMinMaxValues: createFacetedMinMaxValues(),
})

核心模式

const counts = table.getColumn('status')?.getFacetedUniqueValues() ?? new Map()
const range = table.getColumn('age')?.getFacetedMinMaxValues()

离散控件使用唯一值，数值范围仅使用最小/最大值。
过滤后的模型使分面能够响应表格的其他活动筛选条件。
将单独导入的内置函数按常规键名注册，以便列可以通过字符串名称引用它们；列也可以直接接收筛选函数而无需注册。完整的 filterFns 注册表对象仍然可用，但会打包所有内置函数。

常见错误

[HIGH] 注册 API 但缺少模型槽位

错误：tableFeatures({ columnFilteringFeature, columnFacetingFeature })

正确：tableFeatures({ columnFilteringFeature, columnFacetingFeature, facetedRowModel: createFacetedRowModel(), facetedUniqueValues: createFacetedUniqueValues() })

每个分面 getter 都需要其匹配的工厂槽位。

来源：packages/table-core/src/features/column-faceting/columnFacetingFeature.ts

[MEDIUM] 期望分面自行应用

错误：column.getFacetedUniqueValues().get(activeValue) === 0

正确：column.getFacetedUniqueValues().get(activeValue) ?? 0

列分面会有意排除该列自身的筛选，同时应用其他筛选。

来源：docs/framework/react/guide/column-faceting.md

[HIGH] 将页面分面当作全局分面

错误：const globalCounts = column.getFacetedUniqueValues()

正确：const globalCounts = await fetchFacetCounts(activeFilters)

在服务端分页场景下，客户端分面只能看到已加载的数据。

来源：docs/framework/react/guide/column-faceting.md#custom-server-side-faceting

API 发现

检查 node_modules/@tanstack/table-core/dist/features/column-faceting/ 以获取确切的 getter 和工厂返回类型。

适用场景

适用于需要为表格提供动态筛选选项计数的场景，例如按状态、类别等离散字段生成带计数的选项列表，或为年龄等数值字段生成范围。

限制

该技能只派生筛选选项，不渲染筛选控件。
分面会刻意排除该列自身的筛选而应用其他筛选。
在服务端分页场景下，客户端分面只能看到已加载的数据，需改用服务端分面。