BizSearchForm 业务搜索表单

schema 驱动的搜索表单：一行 fields 配置渲染整个查询区，内置查询 / 重置 / 折叠展开按钮区，回车即查；与 BizTable 的 params + data-source 无缝联动。原生 el-form 属性（size、label-position 等）通过 v-bind="$attrs" 完整透传。

基础用法

声明字段 schema 即可：输入框、下拉、日期范围、数字输入等自动渲染，占位符按类型自动生成（请输入/请选择 + label）。点击「查询」或任意输入框内回车触发 search 事件，参数为完整表单值。

关键词

状态

请选择状态

创建日期

-

最小金额

空值过滤是业务侧常见做法，demo 中演示了提交前剔除 '' / undefined / []。

<script setup lang="ts">
import { ref } from 'vue'
import { ElTag } from 'element-plus'
import { BizSearchForm } from 'vue3-ep-biz-lib'
import type { BizSearchField, BizSearchValues } from 'vue3-ep-biz-lib'

const fields: BizSearchField[] = [
  { prop: 'keyword', label: '关键词', type: 'input', placeholder: '名称 / 编码' },
  {
    prop: 'status',
    label: '状态',
    type: 'select',
    options: [
      { label: '启用', value: 1 },
      { label: '停用', value: 0 },
    ],
  },
  { prop: 'dateRange', label: '创建日期', type: 'date-range' },
  { prop: 'minAmount', label: '最小金额', type: 'input-number', min: 0 },
]

const lastQuery = ref<BizSearchValues>({})
const searched = ref(false)

/** 过滤空值后提交（业务侧常用做法） */
const trimEmpty = (values: BizSearchValues): BizSearchValues => {
  const result: BizSearchValues = {}
  for (const key of Object.keys(values)) {
    const value = values[key]
    if (value !== '' && value !== undefined && value !== null && !(Array.isArray(value) && value.length === 0)) {
      result[key] = value
    }
  }
  return result
}

const onSearch = (values: BizSearchValues): void => {
  lastQuery.value = trimEmpty(values)
  searched.value = true
}

const onReset = (): void => {
  searched.value = false
}
</script>

<template>
  <BizSearchForm :fields="fields" @search="onSearch" @reset="onReset" />

  <div v-if="searched" style="padding: 12px; background-color: var(--el-fill-color-light); border-radius: 4px">
    最近一次查询参数：
    <ElTag
      v-for="(value, key) in lastQuery"
      :key="key"
      style="margin-right: 8px"
      type="info"
      effect="plain"
    >
      {{ key }} = {{ Array.isArray(value) ? value.join(' ~ ') : value }}
    </ElTag>
    <span v-if="Object.keys(lastQuery).length === 0">全部为空（查询全量数据）</span>
  </div>
</template>

显示代码

折叠展开

collapsible 开启折叠，collapsed-rows 控制折叠态展示行数（默认 1 行）。字段超出折叠数量的部分隐藏，展开后保留已填值；「展开 / 收起」按钮随操作区固定在行尾最右。

订单号

渠道

请选择渠道

下单时间

-

当前状态：已折叠（仅展示第一行 3 个字段）， 折叠时隐藏字段的已填值在展开后保留。

9 个字段按每行 3 个布局，折叠时仅展示第一行；「展开 / 收起」按钮只在字段数超出时出现。

<script setup lang="ts">
import { ref } from 'vue'
import { BizSearchForm } from 'vue3-ep-biz-lib'
import type { BizSearchField } from 'vue3-ep-biz-lib'

const fields: BizSearchField[] = [
  { prop: 'orderNo', label: '订单号', type: 'input' },
  {
    prop: 'channel',
    label: '渠道',
    type: 'select',
    options: [
      { label: '线上', value: 'online' },
      { label: '门店', value: 'offline' },
      { label: '分销', value: 'partner' },
    ],
  },
  { prop: 'createdRange', label: '下单时间', type: 'date-range' },
  // ---- 以下字段折叠态隐藏 ----
  {
    prop: 'payType',
    label: '支付方式',
    type: 'select',
    options: [
      { label: '支付宝', value: 'alipay' },
      { label: '微信', value: 'wechat' },
      { label: '银行卡', value: 'bank' },
    ],
  },
  { prop: 'minAmount', label: '金额下限', type: 'input-number', min: 0 },
  { prop: 'maxAmount', label: '金额上限', type: 'input-number', min: 0 },
  { prop: 'city', label: '收货城市', type: 'input', placeholder: '省 / 市 / 区' },
  { prop: 'seller', label: '销售员', type: 'input' },
  {
    prop: 'priority',
    label: '优先级',
    type: 'radio',
    options: [
      { label: '全部', value: 0 },
      { label: '高', value: 1 },
      { label: '中', value: 2 },
      { label: '低', value: 3 },
    ],
    defaultValue: 0,
  },
]

const expanded = ref(false)
const onExpandChange = (value: boolean): void => {
  expanded.value = value
}
</script>

<template>
  <BizSearchForm
    :fields="fields"
    collapsible
    :collapsed-rows="1"
    @expand-change="onExpandChange"
  />
  <p style="margin: 0; color: var(--el-text-color-secondary); font-size: 13px">
    当前状态：{{ expanded ? '已展开（全部 9 个字段）' : '已折叠（仅展示第一行 3 个字段）' }}，
    折叠时隐藏字段的已填值在展开后保留。
  </p>
</template>

显示代码

间距与右侧操作区

字段按固定间距流式排列：gutter 控制字段之间的水平间距（默认 12，可选 24 等）。每列宽度统一为「容器宽扣除间距与操作区后等分」——行行列宽一致、不铺满拉伸，从左依次排列、间距恒定，行尾剩余空间自然留白；查询 / 重置 / 展开按钮始终在最后一行的最右侧（字段只有一行时就在这一行右侧），折叠 / 展开切换列宽不跳变。超宽屏列宽封顶 item-max-width（默认 340px）。

gutter = 12（默认）：

关键词

状态

请选择状态

来源渠道

最小金额

创建日期

-

gutter = 24（宽松）：

关键词

状态

请选择状态

来源渠道

最小金额

创建日期

-

同一组字段分别用默认 12 与 gutter=24 排布；字段超出一行自动换行，按钮始终贴右。

<script setup lang="ts">
/** 固定间距流式布局：gutter 控制字段水平间距（默认 12，可选 24 等），宽容器下从左依次排列，操作按钮固定最右 */
import { BizSearchForm } from 'vue3-ep-biz-lib'
import type { BizSearchField } from 'vue3-ep-biz-lib'

const fields: BizSearchField[] = [
  { prop: 'keyword', label: '关键词', type: 'input', placeholder: '名称 / 编码' },
  {
    prop: 'status',
    label: '状态',
    type: 'select',
    options: [
      { label: '启用', value: 1 },
      { label: '停用', value: 0 },
    ],
  },
  { prop: 'channel', label: '来源渠道', type: 'input' },
  { prop: 'minAmount', label: '最小金额', type: 'input-number', min: 0 },
  { prop: 'dateRange', label: '创建日期', type: 'date-range' },
]
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 8px">
    <div style="font-size: 13px; color: var(--el-text-color-secondary)">gutter = 12（默认）：</div>
    <BizSearchForm :fields="fields" :columns="3" />

    <div style="font-size: 13px; color: var(--el-text-color-secondary)">gutter = 24（宽松）：</div>
    <BizSearchForm :fields="fields" :gutter="24" :columns="3" />
  </div>
</template>

显示代码

与 BizTable 联动

搜索表单提交值写入 params，BizTable 监听 params 变化自动回到第一页重新请求；表格远程排序继续生效。这是组件库推荐的标准列表页结构：biz-search-form + biz-table。

订单号

渠道

请选择渠道

状态

请选择状态

下单时间

-

暂无数据

查询、重置（search-on-reset 默认开启，重置后自动查询）、远程排序联动、工具栏全量开启。

<script setup lang="ts">
import { ref } from 'vue'
import { BizSearchForm, BizTable } from 'vue3-ep-biz-lib'
import type { BizSearchField, BizSearchValues, BizTableColumn, BizTableDataSource } from 'vue3-ep-biz-lib'

type OrderRow = {
  id: number
  orderNo: string
  channel: 'online' | 'offline' | 'partner'
  amount: number
  status: 0 | 1 | 2
  createdAt: string
}

const fields: BizSearchField[] = [
  { prop: 'keyword', label: '订单号', type: 'input', placeholder: '支持模糊匹配' },
  {
    prop: 'channel',
    label: '渠道',
    type: 'select',
    options: [
      { label: '线上', value: 'online' },
      { label: '门店', value: 'offline' },
      { label: '分销', value: 'partner' },
    ],
  },
  {
    prop: 'status',
    label: '状态',
    type: 'select',
    options: [
      { value: 0, label: '待支付' },
      { value: 1, label: '已支付' },
      { value: 2, label: '已退款' },
    ],
  },
  { prop: 'createdRange', label: '下单时间', type: 'date-range' },
]

const columns: BizTableColumn<OrderRow>[] = [
  { prop: 'orderNo', label: '订单号', minWidth: 150 },
  {
    prop: 'channel',
    label: '渠道',
    width: 100,
    enums: [
      { value: 'online', label: '线上', tag: 'primary' },
      { value: 'offline', label: '门店', tag: 'success' },
      { value: 'partner', label: '分销', tag: 'warning' },
    ],
  },
  {
    prop: 'status',
    label: '状态',
    width: 100,
    enums: [
      { value: 0, label: '待支付', tag: 'info' },
      { value: 1, label: '已支付', tag: 'success' },
      { value: 2, label: '已退款', tag: 'danger' },
    ],
  },
  { prop: 'amount', label: '金额（元）', width: 120, align: 'right' },
  { prop: 'createdAt', label: '下单时间', width: 120, sortable: 'custom' },
]

/** 查询参数：搜索表单提交后写入，biz-table 监听变化自动回页重查 */
const params = ref<Record<string, unknown>>({})

const trimEmpty = (values: BizSearchValues): Record<string, unknown> => {
  const result: Record<string, unknown> = {}
  for (const key of Object.keys(values)) {
    const value = values[key]
    if (value !== '' && value !== undefined && value !== null && !(Array.isArray(value) && value.length === 0)) {
      result[key] = value
    }
  }
  return result
}

const onSearch = (values: BizSearchValues): void => {
  params.value = trimEmpty(values)
}

/** mock 数据源：业务侧替换为真实接口即可 */
const dataSource: BizTableDataSource<OrderRow> = async ({ currentPage, pageSize, sort, params: query }) => {
  await new Promise((resolve) => setTimeout(resolve, 400))

  const all: OrderRow[] = Array.from({ length: 47 }, (_, i) => ({
    id: i + 1,
    orderNo: `SO2026${String(i + 1).padStart(6, '0')}`,
    channel: (['online', 'offline', 'partner'] as const)[i % 3],
    amount: ((i + 1) * 257) % 9000,
    status: (i % 3) as 0 | 1 | 2,
    createdAt: `2026-0${(i % 8) + 1}-1${i % 9}`,
  }))

  const keyword = String(query.keyword ?? '')
  let list = keyword === '' ? all : all.filter((row) => row.orderNo.includes(keyword))
  if (query.channel !== undefined && query.channel !== '') {
    list = list.filter((row) => row.channel === query.channel)
  }
  if (query.status !== undefined && query.status !== '') {
    list = list.filter((row) => row.status === query.status)
  }
  const range = query.createdRange
  if (Array.isArray(range) && range.length === 2) {
    const [start, end] = range as [string, string]
    list = list.filter((row) => row.createdAt >= start && row.createdAt <= end)
  }
  if (sort.order === 'ascending' || sort.order === 'descending') {
    const prop = sort.prop as keyof OrderRow
    list = [...list].sort((a, b) => {
      const result = String(a[prop]).localeCompare(String(b[prop]), 'zh-CN')
      return sort.order === 'ascending' ? result : -result
    })
  }

  const start = (currentPage - 1) * pageSize
  return { list: list.slice(start, start + pageSize), total: list.length }
}
</script>

<template>
  <div style="display: flex; flex-direction: column; height: 420px">
    <BizSearchForm :fields="fields" @search="onSearch" />
    <div style="flex: 1; min-height: 0">
      <BizTable :columns="columns" :data-source="dataSource" :params="params" toolbar title="订单列表" />
    </div>
  </div>
</template>

显示代码

更多控件与自定义控件

schema 支持 cascader / radio / checkbox / time-select 等类型；type: 'custom' 配合 slot 字段完全接管渲染，插槽作用域提供 { field, model }，model 为响应式表单模型，直接 v-model="model[prop]" 即可。

所属区域

客户类型

企业个人政府

联系时间

请选择联系时间

仅看启用

否

是

{}

columns 调整每行字段数（1~8 任意整数）；提交值以 JSON 展示。

<script setup lang="ts">
import { ref } from 'vue'
import { ElSwitch } from 'element-plus'
import { BizSearchForm } from 'vue3-ep-biz-lib'
import type { BizSearchField, BizSearchValues } from 'vue3-ep-biz-lib'

const fields: BizSearchField[] = [
  {
    prop: 'region',
    label: '所属区域',
    type: 'cascader',
    options: [
      {
        label: '华东',
        value: 'east',
        children: [
          { label: '杭州', value: 'hangzhou' },
          { label: '上海', value: 'shanghai' },
        ],
      },
      {
        label: '华南',
        value: 'south',
        children: [
          { label: '深圳', value: 'shenzhen' },
          { label: '广州', value: 'guangzhou' },
        ],
      },
    ],
  },
  {
    prop: 'types',
    label: '客户类型',
    type: 'checkbox',
    options: [
      { label: '企业', value: 'company' },
      { label: '个人', value: 'personal' },
      { label: '政府', value: 'gov' },
    ],
  },
  {
    prop: 'contactTime',
    label: '联系时间',
    type: 'time-select',
    start: '08:00',
    end: '20:00',
    step: '01:00',
  },
  // 自定义控件：slot 名称由 schema 指定，v-model 绑定 model[prop]
  { prop: 'enabled', label: '仅看启用', type: 'custom', slot: 'enabled', defaultValue: false },
]

const lastQuery = ref<BizSearchValues>({})
const onSearch = (values: BizSearchValues): void => {
  lastQuery.value = values
}
</script>

<template>
  <BizSearchForm :fields="fields" :columns="2" @search="onSearch">
    <template #enabled="{ model }">
      <ElSwitch v-model="model.enabled" active-text="是" inactive-text="否" />
    </template>
  </BizSearchForm>

  <pre style="margin: 0; padding: 12px; background-color: var(--el-fill-color-light); border-radius: 4px; font-size: 12px; overflow: auto">{{ JSON.stringify(lastQuery, null, 2) }}</pre>
</template>

显示代码

高级筛选（多类型混排）

订单号

下单时间

-

最小金额

区域

仅加急

高级检索场景：订单号 + 日期范围 + 数字下限 + 区域级联 + 自定义开关控件（type: custom + slot）混排。

<script setup lang="ts">
/** 场景：高级筛选——日期范围/数字区间一半/级联/自定义控件混排 */
import { ref } from 'vue'
import { ElMessage, ElSwitch } from 'element-plus'
import { BizSearchForm } from 'vue3-ep-biz-lib'
import type { BizSearchField } from 'vue3-ep-biz-lib'

const fields: BizSearchField[] = [
  { prop: 'orderNo', label: '订单号' },
  {
    prop: 'range',
    label: '下单时间',
    type: 'date-range',
    startPlaceholder: '开始日期',
    endPlaceholder: '结束日期',
  },
  { prop: 'minAmount', label: '最小金额', type: 'input-number', min: 0, placeholder: '金额下限' },
  {
    prop: 'region',
    label: '区域',
    type: 'cascader',
    options: [
      { label: '华东', value: 'hd', children: [{ label: '南京', value: 'nj' }, { label: '苏州', value: 'sz' }] },
      { label: '华北', value: 'hb', children: [{ label: '北京', value: 'bj' }] },
    ],
  },
  { prop: 'onlyUrgent', label: '仅加急', type: 'custom', slot: 'urgent' },
]

const values = ref<Record<string, unknown>>({})

const onSearch = (payload: Record<string, unknown>): void => {
  ElMessage.success(`查询条件：${JSON.stringify(payload)}`)
}
</script>

<template>
  <BizSearchForm v-model="values" :fields="fields" :columns="3" @search="onSearch">
    <template #urgent="{ model }">
      <ElSwitch :model-value="model.onlyUrgent === true" @update:model-value="model.onlyUrgent = $event" />
    </template>
  </BizSearchForm>
</template>

显示代码

重置回默认值

状态

近 N 天

渠道

修改条件后点「重置」——回到 defaultValue（生效 / 7 天 / 全渠道），而不是清空为空串

常错点演示：defaultValue 是「重置基准」——重置回到 生效 / 7 天 / 全渠道，而非清空成空串。

<script setup lang="ts">
/** 场景：重置回默认值——defaultValue 是重置基准而非空值 */
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { BizSearchForm } from 'vue3-ep-biz-lib'
import type { BizSearchField } from 'vue3-ep-biz-lib'

const fields: BizSearchField[] = [
  { prop: 'status', label: '状态', type: 'select', defaultValue: 'active', options: [
    { label: '全部', value: '' },
    { label: '生效', value: 'active' },
    { label: '停用', value: 'disabled' },
  ] },
  { prop: 'days', label: '近 N 天', type: 'input-number', defaultValue: 7, min: 1, max: 90 },
  { prop: 'channel', label: '渠道', type: 'select', defaultValue: 'all', options: [
    { label: '全渠道', value: 'all' },
    { label: '小程序', value: 'mp' },
    { label: 'APP', value: 'app' },
  ] },
]

const values = ref<Record<string, unknown>>({ status: 'active', days: 7, channel: 'all' })
</script>

<template>
  <div style="max-width: 640px">
    <BizSearchForm v-model="values" :fields="fields" :columns="3" @search="(payload) => ElMessage.info(`查询：${JSON.stringify(payload)}`)" />
    <div style="margin-top: 8px; font-size: 13px; color: var(--el-text-color-secondary)">
      修改条件后点「重置」——回到 defaultValue（生效 / 7 天 / 全渠道），而不是清空为空串
    </div>
  </div>
</template>

显示代码

搜索区与刷新同排

巡检任务列表

关键词

状态

请选择状态

负责人

列表页场景：collapsible 收起高频字段，标题置于表单上方，下方刷新 / 导出按钮区。

<script setup lang="ts">
/** 场景：搜索区 + 刷新/导出同排——collapsible 收起高频字段，标题置于表单上方 */
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { BizButton, BizSearchForm } from 'vue3-ep-biz-lib'
import type { BizSearchField } from 'vue3-ep-biz-lib'

const fields: BizSearchField[] = [
  { prop: 'keyword', label: '关键词' },
  { prop: 'status', label: '状态', type: 'select', options: [{ label: '正常', value: 'ok' }, { label: '异常', value: 'bad' }] },
  { prop: 'owner', label: '负责人' },
  { prop: 'tag', label: '标签' },
  { prop: 'minScore', label: '最低分', type: 'input-number', min: 0 },
]

const values = ref<Record<string, unknown>>({})
const refreshing = ref(false)

const onRefresh = (): void => {
  refreshing.value = true
  window.setTimeout(() => {
    refreshing.value = false
    ElMessage.success('已刷新')
  }, 600)
}
</script>

<template>
  <div style="max-width: 720px">
    <div style="font-size: 14px; font-weight: 600; margin-bottom: 8px">巡检任务列表</div>
    <BizSearchForm v-model="values" :fields="fields" :columns="3" collapsible @search="() => ElMessage.info('按当前条件查询（示例）')" />
    <div style="display: flex; gap: 10px; margin-top: 8px">
      <BizButton size="small" :loading="refreshing" @click="onRefresh">刷新</BizButton>
      <BizButton size="small" plain @click="ElMessage.info('导出当前结果（示例）')">导出</BizButton>
    </div>
  </div>
</template>

显示代码

筛选方案联动（preset）

关键字

状态

请选择状态

优先级

请选择优先级

创建日期

-

操作区左侧出现「筛选方案」：调整条件 → 保存当前查询 → 之后一键套用（自动回填 + 触发查询）；星标可设默认方案。方案存 localStorage（storage-key），服务端持久化改传 presets + 事件回写。

preset 配置传入即在操作区内置 BizFilterPreset：保存当前条件为方案 / 一键套用（自动回填 + 触发查询）/ 星标默认——高频复筛场景免重复勾选。

<script setup lang="ts">
/** 场景：筛选方案一等联动——preset 配置内置 BizFilterPreset（保存/套用/星标默认全自动接线） */
import { ref } from 'vue'
import { BizSearchForm } from 'vue3-ep-biz-lib'
import type { BizSearchField } from 'vue3-ep-biz-lib'

const fields: BizSearchField[] = [
  { prop: 'keyword', label: '关键字', defaultValue: '', placeholder: '工单号 / 标题' },
  {
    prop: 'status',
    label: '状态',
    type: 'select',
    options: [
      { label: '待处理', value: 'pending' },
      { label: '处理中', value: 'processing' },
      { label: '已完成', value: 'done' },
    ],
  },
  {
    prop: 'priority',
    label: '优先级',
    type: 'select',
    options: [
      { label: '紧急', value: 'high' },
      { label: '普通', value: 'normal' },
      { label: '低', value: 'low' },
    ],
  },
  { prop: 'createdAt', label: '创建日期', type: 'date-range' },
]

const allRows = [
  { id: 'WO-1001', title: '车间温度传感器离线', status: 'pending', priority: 'high', date: '10-18' },
  { id: 'WO-1002', title: '网关固件升级失败', status: 'processing', priority: 'high', date: '10-19' },
  { id: 'WO-1003', title: '显示屏花屏', status: 'pending', priority: 'normal', date: '10-19' },
  { id: 'WO-1004', title: '报表导出超时', status: 'done', priority: 'low', date: '10-20' },
  { id: 'WO-1005', title: '备用电池更换', status: 'processing', priority: 'normal', date: '10-20' },
]

const conditions = ref<Record<string, unknown>>({})
const rows = ref(allRows)

const applyFilter = (values: Record<string, unknown>): void => {
  conditions.value = values
  const keyword = String(values.keyword ?? '').trim()
  const status = values.status
  const priority = values.priority
  rows.value = allRows.filter(
    (row) =>
      (keyword === '' || row.id.includes(keyword) || row.title.includes(keyword)) &&
      (status === '' || status === undefined || row.status === status) &&
      (priority === '' || priority === undefined || row.priority === priority),
  )
}
</script>

<template>
  <el-space direction="vertical" size="large" style="width: 100%">
    <BizSearchForm
      :fields="fields"
      :columns="3"
      :preset="{ storageKey: 'demo-ticket-preset', searchOnApply: true }"
      @search="applyFilter"
    />
    <el-table :data="rows" border size="small">
      <el-table-column prop="id" label="工单号" width="100" />
      <el-table-column prop="title" label="标题" min-width="160" />
      <el-table-column prop="status" label="状态" width="90">
        <template #default="{ row }">
          <el-tag size="small" :type="row.status === 'done' ? 'success' : row.status === 'processing' ? 'primary' : 'warning'">
            {{ row.status === 'done' ? '已完成' : row.status === 'processing' ? '处理中' : '待处理' }}
          </el-tag>
        </template>
      </el-table-column>
      <el-table-column prop="priority" label="优先级" width="80" />
      <el-table-column prop="date" label="创建日期" width="100" />
      <template #empty>当前条件下无工单</template>
    </el-table>
    <p style="margin: 0; font-size: 13px; color: var(--el-text-color-secondary)">
      操作区左侧出现「筛选方案」：调整条件 → 保存当前查询 → 之后一键套用（自动回填 + 触发查询）；星标可设默认方案。方案存 localStorage（<code>storage-key</code>），服务端持久化改传 <code>presets</code> + 事件回写。
    </p>
  </el-space>
</template>

显示代码

日期范围业务快捷项

订单号

创建时间

至

状态

请选择状态

{}

date-range 字段开启 shortcuts: true 后，控件换用 BizDateRange 渲染——面板自带「今日 / 本周 / 近7天 / 近30天」等业务快捷项，值仍为 YYYY-MM-DD 字符串数组。

<script setup lang="ts">
/** 场景：列表筛选——日期范围字段带业务快捷项（BizDateRange 渲染） */
import { ref } from 'vue'
import { BizSearchForm } from 'vue3-ep-biz-lib'
import type { BizSearchField } from 'vue3-ep-biz-lib'

const fields: BizSearchField[] = [
  { prop: 'orderNo', label: '订单号', placeholder: '请输入订单号' },
  {
    prop: 'createdAt',
    label: '创建时间',
    type: 'date-range',
    shortcuts: true,
  },
  {
    prop: 'status',
    label: '状态',
    type: 'select',
    options: [
      { label: '全部', value: '' },
      { label: '待付款', value: 'pending' },
      { label: '已付款', value: 'paid' },
      { label: '已取消', value: 'closed' },
    ],
  },
]

const last = ref<Record<string, unknown>>({})

const onSearch = (values: Record<string, unknown>): void => {
  last.value = values
}
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <BizSearchForm :fields="fields" @search="onSearch" />
    <pre style="margin: 0; padding: 8px 12px; font-size: 12px; border-radius: 6px; background: var(--el-fill-color-light)">{{ JSON.stringify(last, null, 2) }}</pre>
  </div>
</template>

显示代码

Props

属性名	类型	默认值	说明
fields	BizSearchField[]	—	字段 schema 配置，见下方 BizSearchField
v-model	BizSearchValues	—	表单值（受控模式，不传则内部维护）
loading	boolean	false	查询按钮 loading
label-width	string | number	90	标签宽度
columns	number	3	每行字段数（1~8 任意整数；容器很宽时单项封顶不再拉伸，从左依次排列）
gutter	number	12	字段之间的水平间距（px）
item-max-width	string | number	340	单项最大宽度，数字按 px；宽屏封顶避免控件被拉得过宽
collapsible	boolean	false	是否可折叠展开
collapsed-rows	number	1	折叠态展示的行数
search-on-reset	boolean	true	重置后自动触发查询
search-on-enter	boolean	true	回车触发查询
search-text	string	'查询'	查询按钮文案
reset-text	string	'重置'	重置按钮文案
show-reset	boolean	true	是否显示重置按钮
preset	BizSearchPresetConfig	—	筛选方案联动：{ storageKey?, presets?, searchOnApply?, max?, editable?, triggerText? }，传入即在操作区内置 BizFilterPreset（保存当前条件 / 一键套用回填 + 自动查询 / 星标默认）

未列出的属性（size、label-position、disabled 等）透传 el-form 原生 props。

BizSearchField 结构

字段	类型	说明
prop	string	字段名（表单模型 key）
label	string	标签文案
type	BizSearchFieldType	控件类型：input（默认）/ input-number / select / date / datetime / date-range / month / year / time-select / cascader / radio / checkbox / custom
options	BizSearchOption[]	选项（select / radio / checkbox / cascader），{ label, value, disabled?, children? }
defaultValue	unknown	默认值，同时作为重置基准
placeholder / start-placeholder / end-placeholder	string	占位符，缺省按类型自动生成
multiple / filterable / clearable / disabled	—	透传对应控件语义，clearable 默认 true
min / max / step / precision / controls-position	—	input-number 专属
format / value-format	string	日期格式；value-format 缺省为 YYYY-MM-DD（datetime 含时分秒）
shortcuts	boolean	date-range 专属：内置业务快捷项（今日 / 本周 / 近7天…），改用 BizDateRange 渲染，值格式不变
start / end / step	string	time-select 时间选项范围与步长
cascader-props	CascaderProps	透传 el-cascader props（多级、任意选级等）
width	string | number	控件宽度，默认 100%，数字按 px
slot	string	自定义控件插槽名（配合 type: 'custom' 或覆盖任意类型）

date-range / checkbox / 多选 select / 多选 cascader 的值为数组。

Events

事件名	参数	说明
update:modelValue	(values: BizSearchValues)	表单值变化（v-model）
search	(values: BizSearchValues)	点击查询 / 回车 / 调用 search()
reset	(values: BizSearchValues)	重置后触发（重置基准为 defaultValue 或类型空值）
field-change	(payload: { prop, value })	任一字段值变化（控件 change 提交后）
expand-change	(expanded: boolean)	展开 / 收起变化
preset-apply	(values, item)	筛选方案应用（已回填表单；searchOnApply 开启时 search 已随后触发）
preset-save	(item)	筛选方案保存（受控模式由业务持久化后回写 preset.presets）
preset-remove	(id)	筛选方案删除
preset-change	(items)	方案列表变化（本地存储模式）

Slots

插槽名	说明
动态插槽（field.slot）	自定义控件，作用域 { field, model }，model 为响应式模型，可 v-model="model[field.prop]"

Expose

属性 / 方法	说明
formRef	el-form 实例，可调用 validate / resetFields 等原生方法
getValues	() => BizSearchValues，获取表单值
setValues	(values)，批量设置表单值（仅已声明字段）
presetRef	内置 BizFilterPreset 实例（getDefault / getItems 等高级控制）
search	触发查询（等同点击查询按钮）
reset	重置并按 search-on-reset 决定是否触发查询
toggleExpand	展开 / 收起