PcSearch 搜索表单组件文档

PcSearch 是一个基于 Element Plus Form 封装的配置化搜索组件。它将常用的 input、select、date-picker 封装为配置项，支持快速构建统一风格的搜索栏，并提供了灵活的插槽扩展能力。

1. 核心特性

```js [JavaScript] const message = 'Hello VitePress' console.log(message) ```

```ts [TypeScript] const message: string = 'Hello VitePress' console.log(message) ```

```bash [pnpm] pnpm install vitepress ```

• 📋 配置驱动：通过 formList 数组即可快速生成复杂的表单布局。
• ✅ 内置校验：支持 required 简易配置或自定义 rules 校验逻辑。
• 📅 类型丰富：内置文本输入、下拉选择、日期/日期范围选择。
• 🔧 自动关联：配套 PcTable 使用时，支持一键重置（重置并刷新）和搜索功能。
• 🧩 高度灵活：提供 form-item- 前缀的动态插槽，可覆盖任意表单项渲染。

---

2. 基础用法

2.1 简单搜索栏

通过 v-model 绑定数据对象，配置 formList 渲染表单。

<template>
  <pc-search 
    v-model="queryParams" 
    :form-list="formConfig" 
    @request="handleSearch" 
  />
</template>

<script setup lang="ts">
const queryParams = ref({
  keyword: '',
  status: '',
  dateRange: []
})

const formConfig: IPcSearchFormItemProp[] = [
  { label: '关键词', prop: 'keyword', type: 'input' },
  { 
    label: '状态', 
    prop: 'status', 
    type: 'select', 
    sources: [
      { label: '启用', value: 1 },
      { label: '禁用', value: 0 }
    ] 
  },
  { label: '日期', prop: 'dateRange', type: 'date', datetype: 'daterange' }
]

const handleSearch = (type?: string) => {
  // type === 'reset' 表示重置后的触发
  console.log('执行搜索/刷新请求', queryParams.value)
}
</script>

---

3. 配置指南

3.1 常用字段配置

• Select 选择器：支持自定义 labelKey 和 valueKey。

{
  label: '所属部门',
  prop: 'deptId',
  type: 'select',
  labelKey: 'name',  // 默认为 label
  valueKey: 'id',    // 默认为 value
  sources: [{ name: '研发部', id: 101 }]
}

• Date 日期选择：通过 datetype 切换类型（如 year/month/daterange）。

3.2 校验配置

{
  label: '手机号',
  prop: 'phone',
  required: true, // 快捷开启必填
  rules: [ { pattern: /^1[3-9]\d{9}$/, message: '格式错误', trigger: 'blur' } ]
}

---

4. API 详解

4.1 Props 属性

参数	说明	类型	默认值
modelValue	表单数据对象 (v-model)	Record<string, any>	{}
formList	表单项配置列表	FormItemProp[]	[]
actionList	自定义右侧操作按钮	IActionListProp[]	[]

4.2 FormItemProp 配置

属性	说明	类型
prop	字段名 (modelValue 对应的 key)	string
label	表单标签文本	string
type	组件类型	`'input'
width	组件宽度	`string
required	是否必填	boolean
rules	Element Plus 标准校验规则	FormItemRule[]
sources	仅 select 使用，下拉数据源	Array<{label, value}>
datetype	仅 date 使用，对应 type 属性	IDatePickerType
restProps	透传给 Element 原生组件的属性	Object

4.3 Slots 插槽

插槽名	说明
form-item-[prop]	替换整个 el-form-item 区域
[prop]	仅替换表单控件部分（保留 label 和校验逻辑）
actionList	搜索/重置按钮后的扩展区域
after	表单最末尾的扩展区域

4.4 Events 事件

事件名	说明	参数
request	点击搜索或重置时触发，常用于调用接口	(type?: 'reset')
change	任意表单项值改变时触发	(prop, value)
reset	仅点击重置按钮时触发	-

---

5. 组件联动示例 (Search + Table)

这是该组件最常见的使用场景：

<template>
  <pc-search 
    v-model="searchParams"
    :form-list="formList"
    @request="onTableRequest"
  />

  <pc-table
    ref="tableRef"
    :request-api="apiFunc"
    :req-params="searchParams"
    :colum-list="columns"
  />
</template>

<script setup>
const searchParams = ref({ name: '' });
const tableRef = ref();

// 当搜索组件触发 request 时，让表格重置页码并刷新
const onTableRequest = (type) => {
  if (type === 'reset') {
    tableRef.value.requestData('reset');
  } else {
    tableRef.value.requestData();
  }
}
</script>

---

你说得对，插槽是这个组件灵活性的核心。我在文档中补充了具体的插槽分类说明和代码示例，以便开发者更清楚如何自定义内容。

---

6. 插槽 (Slots) 详解

PcSearch 提供了三个层级的插槽，允许你从“局部控件”到“整个表单项”进行自定义。

6.1 插槽分类

插槽名	说明	常用场景
[prop]	控件级插槽。保留 el-form-item 的 Label、校验逻辑和布局，仅替换输入框部分。	使用自定义组件（如：数字范围、省市区联动）。
form-item-[prop]	项级插槽。完全替换整个 el-form-item。	需要修改 Label 样式或特殊布局时。
actionList	操作区插槽。位于“搜索、重置”按钮之后。	放置“导出”、“新增”等功能按钮。
after	尾部插槽。位于表单最后方。	放置表单末尾的提示文字或其他修饰。

---

6.2 代码演示

A. 使用 [prop] 替换控件 (最常用)

如果你有一个配置 prop: 'userType'，你可以直接通过 #userType 自定义它的交互，而无需改变其他配置。

<pc-search v-model="formData" :form-list="formList">
  <template #status="{ row }">
    <el-radio-group v-model="formData.status">
      <el-radio :label="1">启用</el-radio>
      <el-radio :label="0">禁用</el-radio>
    </el-radio-group>
  </template>
</pc-search>

B. 使用 form-item-[prop] 替换整项

如果你需要彻底改变某个表单项的外观（比如不需要 Label ）。

<template #form-item-keyword>
  <div class="custom-item">
    <span>快速搜索：</span>
    <el-input v-model="formData.keyword" />
  </div>
</template>

C. 使用 actionList 添加业务按钮

在搜索、重置按钮旁边添加额外的操作。

<template #actionList>
  <el-button type="success" @click="handleExport">导出 Excel</el-button>
  <el-button type="warning" @click="handleBatchDelete">批量删除</el-button>
</template>

---