用途:为表格或列表提供模糊匹配的排名、过滤与排序能力,核心来自 @tanstack/match-sorter-utils。
主要能力:rankItem 对单个值按查询词计算排名并返回 RankingInfo;用 info.passed 判断是否通过阈值;compareItems 比较两个已保存的 RankingInfo 以排序。可通过 accessors 对对象字段排名,并支持每个 accessor 的 threshold 与 minRanking/maxRanking 边界。
基本用法:import { compareItems, rankItem, rankings } from '@tanstack/match-sorter-utils'。对值调用 rankItem(value, query, { threshold: rankings.MATCHES }),用 info.passed 过滤,再用 compareItems(a.info, b.info) 排序。对象可用 accessors: [(item) => item.name, (item) => item.email]。
与 TanStack Table 集成:在 filterFn 中调用 addMeta?.({ itemRank }),用 filterMeta: metaHelper<{ itemRank: RankingInfo }>() 注册元数据;sortFn 读取 row.columnFiltersMeta[columnId]?.itemRank 并用 compareItems,缺失时回退普通比较器。全局过滤需加载 @tanstack/table-core#table-features,并在 filterFns 注册 fuzzy 供 globalFilterFn: 'fuzzy' 使用。
限制与注意:不要用 rank 数值当通过标志,低于阈值的排名仍可能非零,应使用 passed;不要在排序比较器中重复调用 rankItem,应保留过滤阶段的 RankingInfo;compareItems 已按相关性升序返回,不要再取反。API 细节可查看 node_modules/@tanstack/match-sorter-utils/dist/index.d.ts。