DictDynamicSearch 组件

基于 Element Plus 的动态搜索表单组件，支持响应式布局、折叠展开、表单校验等功能。

动态搜索组件，默认情况下使用dict-dynamic-search使用，如果字典包配置中有配置componentsPreFix字段，请根据此字段的具体配置值进行前缀修改，如配置了componentsPreFix为Bu, 则使用bu-dynamic-search使用。

复制成功

基本用法

vue

<DictDynamicSearch :list="searchList" @pass="handleSearch" @fail="handleFail" @reset="handleReset" />

Props

参数	说明	类型	默认值
`list`	搜索项配置列表	`Array`	`[]`
`isAutoSetPlaceholder`	是否自动生成 placeholder	`Boolean`	`true`
`isShowLabelPlaceholder`	placeholder 中是否包含 label 名称（如"请输入姓名"）	`Boolean`	`true`
`minWidth`	表单最小宽度（px）	`Number`	`768`
`largeWidth`	大屏宽度阈值（px），超过此值每行显示 4 个	`Number`	`1440`
`mediumWidth`	中屏宽度阈值（px），超过此值每行显示 3 个	`Number`	`1000`
`smallWidth`	小屏宽度阈值（px），超过此值每行显示 2 个	`Number`	`768`
`foldStatus`	初始折叠状态	`Boolean`	`true`
`showFold`	是否显示折叠/展开按钮	`Boolean`	`true`
`showReset`	是否显示重置按钮	`Boolean`	`true`
`showSearch`	是否显示查询按钮	`Boolean`	`true`
`expandOnNoEmptySearch`	控制隐藏的搜索框存在值时是否自动展开	`Boolean`	true
`expandOnError`	是否有报错时就展开	`Boolean`	false
`foldOnReset`	重置时是否自动收起	`Boolean`	true
`expandText`	配置展开文字	`String`	展开
`foldText`	配置收起文字	`String`	收起
`searchText`	配置查询文字	`String`	查询
`resetText`	配置重置文字	`String`	重置
`debounceImmediate`	防抖时是否先立即触发一次	`Boolean`	true
`debounceTime`	防抖时长，单位毫秒	`Number`	300
`rules`	全局表单验证规则，键为字段名，值为验证规则数组（同 Element Plus Form 规则）	Object	{}
`idField`	组件配置项中用于标识唯一ID的字段名（用于依赖排序）	String	id

list 配置项

list 数组中每一项是一个搜索字段配置对象，结构如下：

字段	说明	类型	必填
`fieldName`	字段名，对应表单的 `prop` 和 `model` 的 key	`String`	是
`label`	表单项标签	`String`	是
`compName`	动态组件名，如 `el-input`、`el-select`、`el-date-picker` 等	`String`	是
`modelValue`	字段默认值	`Any`	否
`props`	传递给动态组件的属性（如 `clearable`、`placeholder` 等）	`Object`	否
`formItemProps`	传递给 `el-form-item` 的属性（如 `rules` 等）	`Object`	否
`hidden`	hidden为true时，无论如何组件都不可见	Boolean	false
`visible`	初始可见性（默认 true，可通过 showRules 动态控制）	Boolean	true
`showRules`	显示/隐藏规则（见下方「显示规则详解」）	Array，Object，String	""
`showRuleType`	显示规则类型（默认全局动态组件配置的值 "compare"，可选 "calculate"、"validate" 等）	String	compare
`validatorRuleType`	验证规则类型（默认全局动态组件配置的值 "compare"，可选 "calculate" 等）	String	compare

showRules配置相关说明可阅读动态组件

list 配置示例

import { ref } from "vue"
const searchForm = ref({
  name: "爆米花",
  mobile: "",
  sex: "",
  birthday: "",
  dateRange: []
})
const searchList = [
  {
    fieldName: "name",
    label: "手机号",
    compName: "dict-input",
    modelValue: "",
    props: {
      clearable: true,
      maskType: "mobile",
      placeholder: "请输入手机号", // 手动指定 placeholder 会覆盖自动生成
      slotList: [
        {
          slotName: "prepend",
          render: "<el-button>+86</el-button>"
        }
      ]
    },
    formItemProps: {
      rules: [{ required: true, message: "请输入姓名", trigger: "blur" }]
    }
  },
  {
    fieldName: "sex",
    label: "性别",
    compName: "dict-select",
    modelValue: "",
    props: {
      dictType: "SEX_DEMO",
      clearable: true
    }
  },
  {
    fieldName: "dateRange",
    label: "日期范围",
    compName: "el-date-picker",
    modelValue: "",
    props: {
      type: "daterange",
      "range-separator": "至",
      "start-placeholder": "开始日期",
      "end-placeholder": "结束日期"
    }
  }
]

Events

事件名	说明	回调参数
`pass`	表单校验通过后触发	`(searchForm)` — 表单数据对象
`fail`	表单校验未通过时触发	`(errors, searchForm)` — 校验错误信息，表单数据对象
`reset`	点击重置按钮时触发	无

Events 示例

vue

<DictDynamicSearch v-model="searchForm" :list="searchList" @pass="handlePass" @fail="handleFail" @reset="handleReset" min-width="300px" label-width="80px" />

// 校验通过，获取表单数据
const handlePass = () => {
  alert(JSON.stringify(searchForm.value))
  // 发起查询请求...
}

// 校验失败
const handleFail = (errors, form) => {
  console.log("校验错误：", errors)
}

// 重置
const handleReset = () => {
  alert(JSON.stringify(searchForm.value))
}

Slots

插槽名	说明	作用域参数
`prefix`	form-item最前面	`{ searchForm }` — 当前表单数据、`{ fold }` — 当前折叠状态、`{ itemsPerRow }` — 当前每行显示items数量
`button-suffix`	搜索按钮区域前面（可自定义按钮）	`{ searchForm }` — 当前表单数据、`{ fold }` — 当前折叠状态、`{ itemsPerRow }` — 当前每行显示items数量
`button-prepend`	搜索按钮区域后面（可自定义按钮）	`{ searchForm }` — 当前表单数据、`{ fold }` — 当前折叠状态、`{ itemsPerRow }` — 当前每行显示items数量
`prepend`	form-item最后面	`{ searchForm }` — 当前表单数据、`{ fold }` — 当前折叠状态、`{ itemsPerRow }` — 当前每行显示items数量

Slots 示例

vue

<DictDynamicSearch v-model="searchForm" :list="searchList" @pass="handlePass">
  <!-- 自定义标题 -->
  <template #prefix>
    <h3 style="margin-bottom: 12px;">用户查询</h3>
  </template>

  <!-- 自定义搜索按钮区域 -->
  <template #button-prepend="{ searchForm }">
    <el-button type="warning" @click="handleExport(searchForm)">导出</el-button>
  </template>
</DictDynamicSearch>

响应式布局规则

组件根据窗口宽度自动调整每行显示的搜索项数量：

窗口宽度	每行显示数量
`> largeWidth`（默认 1440px）	4 个
`> mediumWidth`（默认 1000px）	3 个
`> smallWidth`（默认 768px）	2 个
`≤ smallWidth`	1 个

可通过 largeWidth、mediumWidth、smallWidth 自定义阈值。

折叠/展开

当 showFold 为 true 且搜索项数量超过每行显示数量减 1 时，会显示折叠/展开按钮。
折叠状态下，仅显示第一行搜索项（每行数量减 1）。
可通过 foldStatus 控制初始状态。

Placeholder 自动生成规则

当 isAutoSetPlaceholder 为 true 时，组件会根据 compName 自动生成 placeholder：

组件类型	生成的 placeholder
包含 `input` 的组件（如 `el-input`）	`请输入{label}`
其他组件（如 `el-select`、`el-date-picker`）	`请选择{label}`

若 isShowLabelPlaceholder 为 false，则不包含 label，仅显示"请输入"或"请选择"。
若在 item.props.placeholder 中手动指定了 placeholder，则优先使用手动指定的值。

完整示例

vue

<script setup>
import { ref } from "vue"
const searchForm = ref({
  name: "爆米花",
  mobile: "",
  sex: "",
  birthday: "",
  dateRange: []
})
const searchList = [
  {
    fieldName: "name",
    label: "姓名",
    compName: "dict-input",
    props: {
      maskType: "name"
    },
    formItemProps: {
      rules: [{ required: true, message: "请输入姓名", trigger: "blur" }]
    }
  },
  {
    fieldName: "sex",
    label: "性别",
    compName: "dict-select",
    modelValue: 1,
    props: {
      dictType: "SEX_DEMO"
    }
  },
  {
    fieldName: "mobile",
    label: "手机号",
    compName: "dict-input",
    props: {
      maskType: "mobile",
      slotList: [
        {
          slotName: "prepend",
          render: "<el-button>+86</el-button>"
        }
      ]
    },
    formItemProps: {
      rules: [{ required: true, message: "请输入姓名", trigger: "blur" }]
    }
  },
  {
    fieldName: "birthday",
    label: "出生日期",
    compName: "el-date-picker",
    props: {
      type: "date"
    }
  },
  {
    fieldName: "dateRange",
    label: "日期范围",
    compName: "el-date-picker",
    props: {
      type: "daterange",
      "range-separator": "至",
      "start-placeholder": "开始日期",
      "end-placeholder": "结束日期"
    }
  }
]

// 校验通过，获取表单数据
const handlePass = () => {
  alert(JSON.stringify(searchForm.value))
  // 发起查询请求...
}

// 校验失败
const handleFail = (errors, form) => {
  console.log("校验错误：", errors)
}

// 重置
const handleReset = () => {
  alert(JSON.stringify(searchForm.value))
}
</script>

<template>
  <DictDynamicSearch v-model="searchForm" :list="searchList" @pass="handlePass" @fail="handleFail" @reset="handleReset" :min-width="300" label-width="80px" :smallWidth="600" />
</template>

优质广告位诚邀合作

DictDynamicSearch 组件 ​

基本用法 ​

Props ​

list 配置项 ​

list 配置示例 ​

Events ​

Events 示例 ​

Slots ​

Slots 示例 ​

响应式布局规则 ​

折叠/展开 ​

Placeholder 自动生成规则 ​

完整示例 ​