# SearchForm 通用搜索表单组件使用说明

## 组件位置
`@/components/common/SearchForm.vue`

## 功能特性
- 支持多种表单控件类型（输入框、选择器、日期选择器等）
- 支持字典选择器（使用 CommonSelector 组件）
- 支持搜索、重置功能
- 支持单个字段清空回调
- 支持回车触发搜索
- 支持显示/隐藏搜索区域
- 灵活的布局配置

## 基本用法

### 1. 引入组件
```vue
import SearchForm from '@/components/common/SearchForm.vue'
```

### 2. 基本示例
```vue
<template>
  <div>
    <search-form
      ref="searchFormRef"
      v-model="searchForm"
      :items="searchItems"
      @search="handleSearch"
      @reset="handleReset"
      @field-clear="handleFieldClear"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'

// 搜索表单数据
const searchForm = ref({})

// 搜索字段配置
const searchItems = ref([
  {
    type: 'input',
    label: '项目名称',
    prop: 'projectName',
    placeholder: '请输入项目名称',
    clearable: true,
    span: 6
  },
  {
    type: 'input',
    label: '项目编号',
    prop: 'projectCode',
    placeholder: '请输入项目编号',
    clearable: true,
    span: 6
  }
])

// 搜索处理
const handleSearch = (formData) => {
  console.log('搜索参数:', formData)
  // 调用你的列表数据获取方法
  getProjectData(formData)
}

// 重置处理
const handleReset = (formData) => {
  console.log('重置后的参数:', formData)
}

// 单个字段清空处理
const handleFieldClear = (prop, formData) => {
  console.log('字段清空:', prop, formData)
}
</script>
```

## 支持的字段类型

### 1. input - 输入框
```javascript
{
  type: 'input',
  label: '项目名称',
  prop: 'projectName',
  placeholder: '请输入项目名称',
  clearable: true,      // 是否显示清空按钮
  disabled: false,      // 是否禁用
  maxlength: 50,        // 最大长度
  span: 6,              // 栅格占用的列数
  searchOnEnter: true   // 回车时是否触发搜索（默认true）
}
```

### 2. select - 下拉选择器
```javascript
{
  type: 'select',
  label: '项目状态',
  prop: 'projectLzType',
  placeholder: '请选择项目状态',
  clearable: true,
  span: 6,
  options: [
    { label: '待立项', value: '1' },
    { label: '已立项', value: '5' }
  ]
}
```

### 3. dict-select - 字典选择器（推荐）
```javascript
{
  type: 'dict-select',
  label: '项目类型',
  prop: 'projectType',
  dictName: 'xmlx',        // 必传：字典名称（从 sessionStorage 的 resourceData 中获取）
  placeholder: '请选择项目类型',
  span: 6,
  labelKey: 'name',        // 可选：标签字段（默认 'name'）
  valueKey: 'key',         // 可选：值字段（默认 'key'）
  radio: false             // 可选：是否使用单选组（默认 false，使用下拉）
}
```

### 4. date - 日期选择器
```javascript
{
  type: 'date',
  label: '创建时间',
  prop: 'createTime',
  dateType: 'date',        // date/datetime/month/year 等
  placeholder: '请选择日期',
  valueFormat: 'YYYY-MM-DD',
  format: 'YYYY-MM-DD',
  clearable: true,
  span: 6
}
```

### 5. daterange - 日期范围选择器
```javascript
{
  type: 'daterange',
  label: '时间范围',
  prop: 'timeRange',
  startPlaceholder: '开始日期',
  endPlaceholder: '结束日期',
  valueFormat: 'YYYY-MM-DD',
  clearable: true,
  span: 6
}
```

### 6. number - 数字输入框
```javascript
{
  type: 'number',
  label: '金额',
  prop: 'amount',
  min: 0,
  max: 1000000,
  step: 100,
  span: 6
}
```

### 7. radio - 单选框组
```javascript
{
  type: 'radio',
  label: '状态',
  prop: 'status',
  span: 6,
  options: [
    { label: '启用', value: '1' },
    { label: '禁用', value: '0' }
  ]
}
```

### 8. checkbox - 复选框组
```javascript
{
  type: 'checkbox',
  label: '权限',
  prop: 'permissions',
  span: 6,
  options: [
    { label: '查看', value: 'view' },
    { label: '编辑', value: 'edit' }
  ]
}
```

### 9. cascader - 级联选择器
```javascript
{
  type: 'cascader',
  label: '地区',
  prop: 'region',
  options: [...],
  props: {
    value: 'value',
    label: 'label',
    children: 'children'
  },
  clearable: true,
  span: 6
}
```

### 10. tree - 树选择器
```javascript
{
  type: 'tree',
  label: '部门',
  prop: 'department',
  data: [...],             // 树形数据
  checkStrictly: true,     // 是否可选择任意节点
  clearable: true,
  span: 6
}
```

## Props 参数

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| items | 表单项配置数组 | Array | [] |
| modelValue | 表单数据（v-model） | Object | {} |
| inline | 是否行内表单 | Boolean | true |
| labelWidth | 标签宽度 | String | 'auto' |
| size | 表单尺寸 | String | 'default' |
| gutter | 栅格间隔 | Number | 16 |
| defaultSpan | 默认每个表单项占的列数 | Number | 6 |
| buttonSpan | 按钮列数 | Number | 6 |
| searchText | 搜索按钮文本 | String | '搜索' |
| resetText | 重置按钮文本 | String | '重置' |
| autoSearchOnReset | 重置时是否自动搜索 | Boolean | true |
| autoSearchOnClear | 字段清空时是否自动搜索 | Boolean | false |

## Events 事件

| 事件名 | 说明 | 回调参数 |
|--------|------|----------|
| search | 点击搜索按钮时触发 | (formData: Object) |
| reset | 点击重置按钮时触发 | (formData: Object) |
| field-change | 字段值变化时触发 | (prop: String, value: Any, formData: Object) |
| field-clear | 字段清空时触发 | (prop: String, formData: Object) |
| enter-search | 回车键触发时触发 | (prop: String, formData: Object) |

## 组件方法（通过 ref 调用）

```javascript
// 手动触发搜索
searchFormRef.value.search()

// 手动重置表单
searchFormRef.value.resetFields()

// 访问表单数据
console.log(searchFormRef.value.formData)
```

## 完整示例（项目列表页）

```vue
<template>
  <div class="manage-container">
    <div class="manage-wrap">
      <!-- 搜索表单区域 -->
      <div class="manage-search" v-if="showSearch">
        <search-form
          ref="searchFormRef"
          v-model="searchForm"
          :items="searchItems"
          @search="handleSearch"
          @reset="handleReset"
          @field-clear="handleFieldClear"
        />
      </div>

      <div class="manage-header">
        <div class="header-left">
          <el-button
            :icon="showSearch ? ArrowUp : ArrowDown"
            @click="toggleSearch"
          >
            {{ showSearch ? '隐藏搜索' : '显示搜索' }}
          </el-button>
        </div>
      </div>

      <!-- 列表内容 -->
      <div class="manage-content">
        <!-- 你的表格组件 -->
      </div>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { ArrowUp, ArrowDown } from '@element-plus/icons-vue'
import SearchForm from '@/components/common/SearchForm.vue'

const showSearch = ref(true)
const searchFormRef = ref()
const searchForm = ref({})

const searchItems = ref([
  {
    type: 'input',
    label: '项目名称',
    prop: 'projectName',
    placeholder: '请输入项目名称',
    clearable: true,
    span: 6
  },
  {
    type: 'dict-select',
    label: '项目类型',
    prop: 'projectType',
    dictName: 'xmlx',
    placeholder: '请选择项目类型',
    span: 6
  },
  {
    type: 'daterange',
    label: '创建时间',
    prop: 'createTime',
    startPlaceholder: '开始日期',
    endPlaceholder: '结束日期',
    valueFormat: 'YYYY-MM-DD',
    span: 6
  }
])

const toggleSearch = () => {
  showSearch.value = !showSearch.value
}

const handleSearch = (formData) => {
  console.log('搜索参数:', formData)
  currentPage.value = 1
  getProjectData(formData)
}

const handleReset = (formData) => {
  console.log('重置后的参数:', formData)
  currentPage.value = 1
}

const handleFieldClear = (prop, formData) => {
  console.log('字段清空:', prop, formData)
}

const getProjectData = (params = {}) => {
  // 你的数据获取逻辑
  console.log('获取列表数据:', params)
}
</script>

<style scoped lang="less">
.manage-search {
  padding: 16px;
  background: #fff;
  margin-bottom: 16px;
  border-radius: 4px;
}
</style>
```

## 注意事项

1. **字典选择器使用**：确保 sessionStorage 中有 `resourceData` 数据，且包含对应的字典名称
2. **字段清空**：默认情况下，字段清空不会自动触发搜索，如需自动搜索，设置 `autoSearchOnClear: true`
3. **重置行为**：默认重置后会自动触发搜索，如需关闭，设置 `autoSearchOnReset: false`
4. **回车搜索**：输入框和数字输入框支持回车触发搜索，可通过 `searchOnEnter: false` 关闭
5. **布局调整**：通过调整 `defaultSpan` 和各字段的 `span` 属性来控制布局
