global-filtering

用途

全局过滤（Global Filtering）用于在表格中跨多个符合条件的列应用同一个过滤值（globalFilter），实现类似“全局搜索”的效果。该技能构建在 core、table-features、client-vs-server 和 column-filtering 之上，全局过滤复用了列过滤的管线。

主要能力

• 通过 globalFilteringFeature 启用全局过滤能力。
• 依赖 columnFilteringFeature 与 filteredRowModel 完成客户端过滤处理。
• 通过 globalFilterFn 指定全局过滤函数，例如 'includesString'。
• 通过 getColumnCanGlobalFilter 声明哪些列参与全局过滤，当产品规则与默认的原始值检测不同时使用。
• 支持手动服务端过滤（manual server filtering），此时过滤绕过客户端模型，过滤值需要驱动服务端请求。

使用方式

设置 features：

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

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

核心模式：

const options = {
  globalFilterFn: 'includesString' as const,
  getColumnCanGlobalFilter: (column) => column.id !== 'actions',
}

当产品规则与默认的原始值检测不同时，声明列的参与资格。

常见错误

[CRITICAL] 遗漏列过滤前置条件

错误：tableFeatures({ globalFilteringFeature })

正确：tableFeatures({ columnFilteringFeature, globalFilteringFeature, filteredRowModel: createFilteredRowModel() })

全局过滤依赖列过滤，并且需要 filtered model 进行客户端处理。

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

[HIGH] 假设每一列都参与

错误：const options = { globalFilterFn: 'includesString' }

正确：const options = { getColumnCanGlobalFilter: column => column.id !== 'actions' }

默认参与资格使用第一行核心数据，并接受字符串或数字值。

来源：packages/table-core/src/features/global-filtering/globalFilteringFeature.ts

[HIGH] 手动过滤仅保留在本地

错误：table.setGlobalFilter(search); const options = { manualFiltering: true }

正确：const page = await fetchRows({ search }); const options = { data: page.rows, manualFiltering: true }

手动过滤绕过客户端模型，因此该值必须驱动服务端请求。

来源：docs/framework/react/guide/global-filtering.md#manual-server-side-global-filtering

API 探索

检查 node_modules/@tanstack/table-core/dist/features/global-filtering/ 以及 dist/features/column-filtering/，了解共享状态和过滤函数。

适用场景

适用于需要在表格中提供跨列全局搜索过滤功能的场景，尤其是使用 TanStack Table 并希望复用列过滤管线、或需要将过滤逻辑交由服务端处理的开发者。

限制

该技能依赖列过滤功能，必须同时启用 columnFilteringFeature 与 filteredRowModel。默认参与资格仅基于第一行核心数据并接受字符串或数字值，若产品规则不同需显式声明。手动过滤时不会在客户端处理数据，过滤值必须用于服务端请求。