Filter 筛选器
Filter 使用 Rue 当前的filter + btn视觉风格，在此基础上补了一层更顺手的 API： 可以使用Filter.Item/Filter.Reset组合写法，也可以直接用items、value、onChange组织整组筛选。
何时使用
- 需要一排轻量筛选按钮，并保持 Rue 当前视觉。
- 需要同时覆盖表单重置、即时切换和多选标签场景。
- 需要在展示基础 compound 写法的同时，逐步切换到数据驱动写法。
推荐用法
推荐优先使用items模式，把筛选项、默认值和变体样式统一放到根组件上管理。
# 数据驱动与受控状态
当前阶段：
all# 多选筛选
已选择：
search, alerts# 样式覆盖
Tone Overrides
Sizes
# Filter using form
# Filter using div
# Filter with grouped options
每组筛选项都需要唯一的 name，并通过 aria-label 提供按钮文案。
API
当前页面展示的是语义化的 Filter API；基础的 compound 写法仍然可用。
Filter
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
as | 根节点模式，可选 form 或 div | 'form' | 'div' | 'form' |
items | 数据驱动筛选项，支持字符串、数字、布尔值或对象 | ReadonlyArray<FilterItemData | FilterValue> | [] |
name | 统一传给子项的 name；radio 模式未传时会自动生成分组名 | string | - |
type | 输入类型，决定单选或多选 | 'radio' | 'checkbox' | 'radio' |
multiple | 多选快捷开关，等价于 type="checkbox" | boolean | false |
value | 受控值；单选传单值，多选传数组 | FilterValue | FilterValue[] | - |
defaultValue | 非受控默认值；form 模式 reset 会回到该初始状态 | FilterValue | FilterValue[] | - |
onChange | 选中项变化回调，返回当前值与 values 元信息 | (value, event, meta) => void | - |
reset | 自动渲染 Reset，支持布尔或配置对象 | boolean | FilterResetProps | false |
color | 整组默认颜色，单项可覆盖 | 'default' | 'danger' | 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'error' | 'default' |
variant | 整组默认视觉变体 | 'solid' | 'filled' | 'outlined' | 'dashed' | 'text' | 'solid' |
size | 整组默认尺寸，支持 xs-xl 与 small/middle/large 别名 | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'small' | 'medium' | 'middle' | 'large' | - |
Filter.Item
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
label | 筛选项文案；会映射到 aria-label | any | - |
value | 筛选值；未传时会尝试使用 label | FilterValue | - |
checked / defaultChecked | 单项受控或非受控选中状态 | boolean | - |
color / variant / size | 覆盖根组件的按钮样式配置 | FilterColor / FilterVariant / FilterSize | - |
type | 单项输入类型，默认继承根组件 | 'radio' | 'checkbox' | 继承 |
Filter.Reset
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
mode | Reset 的交互模式，form 为恢复默认值，div 为清空选中 | 'form' | 'div' | 继承根组件 |
label | Reset 文案；form 模式映射到 value，div 模式映射到 aria-label | any | '×' |
color / variant / size | Reset 按钮的样式覆盖 | FilterColor / FilterVariant / FilterSize | 继承 |
FAQ
什么时候用 form，什么时候用 div？
form适合表单内筛选，点击Reset会回到defaultValue对应的初始状态；div更适合即时交互场景，Reset 会直接清空当前选中。
为什么推荐使用 label 而不是只写 aria-label？
基础写法保持aria-label，但语义 API 下优先推荐label，这样在items模式里既能声明按钮文案，也更方便推导默认value。
受控模式和多选模式怎么返回值？
单选模式下，onChange返回单个值或undefined；多选模式下返回数组。 同时第三个参数里的values 会始终给出当前整组已选值，便于统一处理。