参数

useTableFiltering() 只接一个配置对象。过滤值存在 ref 里时用 getter 包一层，表格每次读都能拿到最新的值：useTableFiltering(() => ({ ... }))。

名称	类型	默认值	说明
filters	TableFilterState	—	必填。当前的过滤状态：字段 key 到过滤值的映射。
onFilterChange	(key: string, value: TableFilterValue | null) => void	—	必填。用户改过滤值时调用。null 表示清掉这个过滤。
fields	readonly TableFilterField[]	—	必填。列可以过滤的字段。每一项有 key、label、type，以及这种类型需要的选项或范围。
variant	'inline' | 'inline-compact' | 'popover'	'popover'	控件放在哪。inline 和 inline-compact 放在表头单元格里、列名下面，后者更紧凑；popover 藏在漏斗按钮后面，确认后才生效。

返回值

useTableFiltering() 返回一个 TablePlugin<T>，放进 Table 的 plugins 里。它填的是插件约定里的两个字段：

名称	类型	说明
transformColumns	(columns: TableColumn<T>[]) => TableColumn<T>[]	只有行内变体才给：带过滤而且没写 width 的列补成 proportional(1)，控件在列名下面放得开。
filterFor	(column: TableColumn<T>) => TableFilterContribution | null	生成这一列的控件。列没有 filter，或者它指的字段不在 fields 里时返回 null。

TableFilterContribution

名称	类型	说明
variant	'inline' | 'inline-compact' | 'popover'	补完默认值之后的摆放方式。
field	TableFilterField	列指到的字段，来自 fields。
value	TableFilterValue | null	当前值，来自 filters。这个字段还没有过滤时是 null。
onChange	(value: TableFilterValue | null) => void	把新值交给你的 onFilterChange，字段 key 已经带上了。

TableFilterField

名称	类型	默认值	说明
key	string	—	字段 key。列的 filter 里写这个字符串，字段读的是 row[key]。
label	string	—	控件的标签和占位文字，也是读屏读到的名字。
type	'string' | 'enum' | 'multi-select' | 'number' | 'date'	—	命中方式。string 匹配子串，enum 匹配一个选项，multi-select 匹配勾选中的任意一项，number 比数值，date 要求单元格日期比选的更晚。
options	readonly { value: string, label: string }[]	—	enum 和 multi-select 的选项。没有选项时列表是空的。
min	number	—	number 字段能接受的最小值。
max	number	—	number 字段能接受的最大值。
step	number	isIntegerOnly 时是 1，否则不设	number 字段的步进。
isIntegerOnly	boolean	false	number 字段只接受整数。

TableFilterValue

名称	类型	说明
value	string | number | string[]	number 字段存数字，multi-select 存选项值数组，其余存字符串。date 字段存 ISO 日期，例如 2026-03-21。