Appearance
AtSearch
沈孟平
最后更新于 2026-04-23 19:53:53
一个带有丝滑响应式宽度的搜索组件。通过配置 minWidth prop 来实现响应式宽度。注意，搜索组件仅包含基础类型表单：input、switch、inputNumber、select、cascader、datePicker、timePicker、treeSelect、radio、custom。
Warning
注意当使用 apiFn 的时候，props 中的 options 会覆盖 apiFn 返回的 options
组件定位
可以把 AtSearch 理解成“列表筛选场景专用的 AtForm 外壳”：
- 内部仍然使用
AtForm渲染字段 - 自动把表单切换为 inline 布局
- 自动根据可用宽度计算是否展示“展开/收起”
- 内置查询、重置和回车触发查询的交互
如果你的场景包含数组字段、对象块、表格表单或复杂嵌套，优先使用 AtForm；如果只是列表页顶部筛选栏，优先使用 AtSearch。
使用建议
initValue控制的是“重置时恢复到什么状态”，而不是首次渲染时自动覆盖model。- 通过
ref.formRef可以访问内部AtForm实例，例如手动校验、设置值、重置校验。 - 搜索栏折叠高度会跟随
n-form-props.size自动计算，适合直接接入现有页面尺寸体系。
代码演示
可以通过 atSearchRef.value?.formRef 来访问内部的表单实例。
基础示例
可以通过 initValue 来控制重置动作。
显示 label 与自定义宽度
自定义操作
API
AtSearch Props
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
| model | object | 必填项 | 表单数据对象 | |
| configs | array | 必填项 | 表单配置项 | |
| loading | boolean | undefined | 加载状态 | |
| min-width | string | '320px' | 每个表单项的最小宽度，用于实现响应式布局 | |
| card-style | object | object | 卡片样式 | |
| default-open | boolean | false | 默认是否展开 | |
| n-form-props | Omit<FormProps, 'themeOverrides' | 'model'> | undefined | NaiveUI Form Props | |
| init-value | object | undefined | 初始值，设置后重置表单会恢复到该值状态 | |
| show-reset-btn | boolean | true | 是否显示重置按钮 |
AtSearch Events
| 名称 | 类型 | 说明 | 版本 |
|---|---|---|---|
| search | (action: 'reset' | 'query') => void | 搜索事件 |
AtSearch Expose
| 名称 | 类型 | 说明 | 版本 |
|---|---|---|---|
| formRef | AtFormInst | 内部表单实例，可访问表单的所有方法 |
AtSearch Slots
| 名称 | 参数 | 说明 | 版本 |
|---|---|---|---|
| action | () | 自定义操作按钮区域 |