---
url: /components/search-filter.md
---
# SearchFilter 筛选表单

查询/重置二合一的筛选表单，`fields` 配置式声明字段，支持输入框与下拉选择，内置查询/重置按钮与回车触发。

行为要点：

* 任意字段变更都会 emit `update:modelValue`，`v-model` 始终拿到完整值对象；
* 点击查询按钮或在输入框内回车都会 emit `search`；`loading` 期间查询被阻止（按钮加载态并忽略回车），防止重复提交；
* 点击重置会把每个字段恢复为 `defaultValue`（未配置则为空串），先 emit `reset`，`searchOnReset` 为真时紧接着再 emit 一次 `search`。

## 基础用法

## 布局与加载态

`columns` 控制每行字段数（2 / 3 / 4），`loading` 时查询按钮进入加载态并阻止重复提交。

## 重置默认值与字段变体

`type: 'select'` 渲染下拉（`options` 就地内联声明，适合静态枚举；选项来自接口时先请求再更新 fields 即可）。`defaultValue` 是重置时的恢复值；select 默认可清空，`clearable: false` 关闭清空按钮；`disabled` 字段不可编辑但同样参与重置。

先把等级改成 P1、城市选上海，再点重置：所有字段都恢复为各自 `defaultValue`（等级回到 P0，其余回到空串），并自动触发一次查询。

## 自定义操作区

`actions` 插槽渲染在查询/重置按钮之后，适合放高级筛选入口、保存常用条件等自定义操作。

## 交互：查询取值

`search` 事件携带当前值对象的快照（拷贝，后续修改不影响已触发的那次）；也可通过实例方法 `getValues()` 主动取值。

## API