column-filtering

用途

column-filtering 是 TanStack Table 中关于列过滤（column filtering）技能的文档，构建在 core、table-features 与 client-vs-server 之上。核心观点是：过滤状态（filtering state）、行处理（row processing）与过滤 UI（filter UI）是彼此独立的关注点，需要分开处理。

主要能力

通过 columnFilteringFeature 启用列过滤特性。
通过 createFilteredRowModel() 创建过滤后的行模型。
通过 filterFns 注册过滤函数，如 filterFn_includesString。
支持按字符串名称引用内置 filterFn_* 函数，也支持 filterFn: 'auto' 按数据类型解析。
支持 filterFromLeafRows 与 maxLeafRowFilterDepth 选项，实现叶子行优先过滤：仅当某个后代匹配时，父行才保留。
提供 manualFiltering 选项，用于在手动模式与客户端过滤之间切换。
涉及 filterMeta、嵌套行方向（nested-row direction）等概念。

使用方式

设置特性时导入并注册过滤特性与过滤函数：

import {
  columnFilteringFeature,
  createFilteredRowModel,
  filterFn_includesString,
  tableFeatures,
} from '@tanstack/table-core'

export const features = tableFeatures({
  columnFilteringFeature,
  filteredRowModel: createFilteredRowModel(),
  filterFns: { includesString: filterFn_includesString },
})

文档建议：单独导入各个 filterFn_* 内置函数，只注册列通过字符串名称引用的、或 filterFn: 'auto' 需要为相应数据类型解析的那些函数。完整的 filterFns 注册对象仍然可用，但会打包全部内置函数。

核心模式示例：

const options = {
  filterFromLeafRows: true,
  maxLeafRowFilterDepth: 2,
}

仅当某个后代匹配、希望父行因此保留时，才使用叶子行优先过滤。

适用场景

适用于使用 TanStack Table 构建数据表格、需要按列值进行过滤的开发者，尤其是需要区分客户端过滤与服务端过滤、或需要处理嵌套/树形行过滤的场景。

限制与常见错误

文档列出以下常见误区：

[高] 混用手动与客户端过滤：错误写法为 const options = { manualFiltering: true }，正确写法为 const options = { manualFiltering: false }。手动模式返回预过滤（pre-filtered）的模型；若为 true，应改为将过滤状态发送到服务端。（来源：packages/table-core/src/features/column-filtering/columnFilteringFeature.types.ts）
[高] 对渲染器输出做过滤：错误写法为 helper.accessor(row => ({ label: row.status }), { filterFn: 'includesString' })，正确写法为 helper.accessor('status', { filterFn: 'includesString' })。内置字符串与数值过滤期望的是可比较的 accessor 值，而不是对象或 UI 节点。（来源：docs/framework/react/guide/column-filtering.md#filterfns）
[高] 忽略 updater 函数回调：错误写法为 onColumnFiltersChange: value => { columnFilters = value as ColumnFiltersState }，正确写法为 onColumnFiltersChange: updater => { columnFilters = functionalUpdate(updater, columnFilters) }。受控回调收到的可能是值，也可能是基于先前状态的函数。（来源：packages/table-core/src/features/column-filtering/columnFilteringFeature.types.ts）

API 查找

可查看 node_modules/@tanstack/table-core/dist/features/column-filtering/ 与 dist/features/column-filtering/filterFns.d.ts，以获取准确的函数签名与自动移除（auto-remove）行为。

以上功能的完整参数细节、平台支持与收费情况，资料中暂未提供。