外观
KvSearchBar
响应式搜索表单组件,根据配置自动渲染输入框、选择器、日期等控件。
实时预览
响应式搜索栏
修改查询条件并点击搜索,页面会直接展示清洗后的查询参数。
最近一次查询:
{}Props
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
items | SearchFormItem[] | [] | 否 | 搜索项配置 |
span | number | 6 | 否 | 兼容原栅格配置,收起时显示 floor(24 / span) - 1 个条件(默认 3 个) |
gutter | number | 12 | 否 | 表单项间距 |
isExpand | boolean | false | 否 | 是否强制展开全部搜索项 |
defaultExpanded | boolean | false | 否 | 默认展开全部搜索项 |
labelPosition | 'left' | 'right' | 'top' | 'right' | 否 | 标签位置 |
labelWidth | string | number | '100px' | 否 | 标签宽度,默认容纳六字中文标签 |
showExpand | boolean | true | 否 | 是否显示展开/收起按钮 |
showReset | boolean | true | 否 | 是否显示重置按钮 |
showSearch | boolean | true | 否 | 是否显示搜索按钮 |
disabledSearch | boolean | false | 否 | 是否禁用搜索按钮 |
sanitizeOutput | Partial<SanitizeSearchOptions> | {} | 否 | 搜索参数清洗配置 |
messages | Partial<KevairyComponentMessages> | {} | 否 | 组件文案覆盖 |
搜索栏四周内边距均为 12px;默认控件高度为 32px,行间距为 12px。桌面使用左右两个独立容器:左侧筛选条件按“标签宽度 + 控件宽度”从左向右紧凑排列,间距由 gutter 控制,空间不足时自动换行,不再均分整行宽度;右侧按钮区按内容宽度独立占位,并与第一行顶部对齐,条件展开后不会占用按钮区。默认收起时显示三个条件,展开后每行数量由可用宽度决定。768px 及以下按钮区独占一行;640px 及以下每个筛选项独占一行,避免日期范围与按钮互相挤压。可以通过组件上的 --kv-search-control-height 调整控件高度。
搜索控件最大宽度为 260px,空间不足时随所在列收缩,宽屏下不会继续拉伸。
展开与收起内置高度过渡(约 240ms / 200ms),下方内容和移动端按钮随搜索区平滑移动,箭头同步旋转。收起期间额外条件退出键盘导航,过渡结束后隐藏,已填筛选值保持。系统开启“减少动态效果”或浏览器不支持 Web Animations API 时直接切换;窗口尺寸改变时结束当前动效并恢复自适应高度。
可在组件或其祖先上配置 --kv-search-padding-block(默认 12px)和 --kv-search-padding-inline(默认 12px),分别调整上下和左右内边距。
容器圆角使用 --kv-container-radius,未设置时回退到 --el-border-radius-base(最终回退为 4px)。此变量与表格卡片共用,不影响搜索区内按钮和输入框的控件圆角。
v-model
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
modelValue | Record<string, unknown> | {} | 表单数据 |
Events
| 事件 | 参数 | 说明 |
|---|---|---|
search | Record<string, unknown> | 点击搜索时触发,返回清洗后的参数 |
reset | — | 点击重置时触发 |
Exposed
| 名称 | 类型 | 说明 |
|---|---|---|
ref | FormInstance | Element Plus 表单实例 |
validate | () => Promise<boolean> | 校验表单 |
reset | () => void | 重置表单 |
getOutput | () => Record<string, unknown> | 获取清洗后的搜索参数 |
SearchFormItem
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
key | string | — | 是 | 字段名 |
label | string | Component | (() => VNode) | — | 是 | 标签 |
type | SearchComponentType | string | 'input' | 否 | 控件类型 |
render | Component | (() => VNode) | — | 否 | 自定义渲染函数或组件 |
hidden | boolean | false | 否 | 是否隐藏 |
span | number | — | 否 | 兼容保留,紧凑布局不再按此值分配列宽 |
labelWidth | string | number | — | 否 | 当前项标签宽度 |
props | Record<string, unknown> | {} | 否 | 传给控件的属性 |
slots | Record<string, Slot> | — | 否 | 控件命名插槽 |
支持的内置 type:input、inputTag、number、select、switch、checkbox、checkboxgroup、radiogroup、date、datetime、daterange、datetimerange、rate、slider、cascader、timepicker、timeselect、treeselect。
示例代码
vue
<script setup>
import { ref } from 'vue'
import { KvSearchBar } from '@kevairy/components'
const searchModel = ref({ keyword: '', status: '' })
const items = [
{
key: 'keyword',
label: '关键词',
type: 'input',
props: { placeholder: '请输入', clearable: true }
},
{
key: 'status',
label: '状态',
type: 'select',
props: {
options: [
{ label: '启用', value: 1 },
{ label: '禁用', value: 0 }
]
}
}
]
const handleSearch = (params) => {
console.log(params)
}
</script>
<template>
<KvSearchBar v-model="searchModel" :items="items" @search="handleSearch" />
</template>