# VForm 组件 API 文档

## 组件简介 | Component Introduction
`VForm` 是基于 Element Plus 的表单组件，支持响应式布局、丰富的表单项类型、校验、插槽、方法暴露等。

`VForm` is a form component based on Element Plus, supporting responsive layout, rich field types, validation, slots, and exposed methods.

---

## Props/属性
| 属性名 | 说明 | 类型 | 是否必填 | 默认值 |
|--------|------|------|----------|--------|
| fields | 表单项配置 | Array | 是 | - |
| config | 表单整体配置 | Object | 否 | {} |
| isSearch | 是否为搜索表单 | Boolean | 否 | false |

---

## fields 配置项 | Fields Options
每一项对应一个表单项，支持以下字段：

| 字段名 | 说明 | 类型 | 备注 |
|--------|------|------|------|
| name | 字段名 | String | 必填，唯一标识 |
| component | 组件类型 | String | 必填，支持 Input/Select/DatePicker/Checkbox/RadioGroup 等 |
| label | 标签 | String/Function | 支持字符串或函数返回VNode |
| placeholder | 占位符 | String |  |
| options | 选项列表 | Array | 适用于 Select/RadioGroup/CheckboxGroup 等 |
| rules | 校验规则 | Array | 参考 el-form rules |
| slot | 插槽名 | String/Object | 支持自定义内容，如 { default, prefix, suffix, error } |
| render | 自定义渲染函数 | Function | (scope) => VNode |
| class | 表单项 class | String |  |
| style | 表单项 style | Object |  |
| fieldClass | 字段 class | String |  |
| fieldStyle | 字段 style | Object |  |
| group | 分组名 | String | 用于分组布局 |
| colSpan | 跨列数 | Number |  |
| labelWidth | 标签宽度 | Number/String |  |
| required | 是否必填 | Boolean |  |
| clearable | 可清空 | Boolean |  |
| disabled | 禁用 | Boolean |  |
| readonly | 只读 | Boolean |  |
| maxlength | 最大长度 | Number |  |
| minlength | 最小长度 | Number |  |
| valueFormat | 值格式化 | String | 适用于日期类 |
| onChange | 值变化回调 | Function | (value) => void |
| ... | 其余各表单项支持的属性 |  |  |

---

## config 配置项 | Config Options
表单整体配置，支持以下字段：

| 字段名 | 说明 | 类型 | 备注 |
|--------|------|------|------|
| columns | 列数 | Number | 响应式布局专用 |
| labelWidth | 标签宽度 | Number/String |  |
| labelPosition | 标签位置 | String | 'left'/'right'/'top' |
| labelSuffix | 标签后缀 | String | 默认为 ':' |
| inline | 行内表单 | Boolean |  |
| actionAlign | 操作区对齐 | String | 'left'/'center'/'right' |
| actionNewLine | 操作区换行 | Boolean |  |
| submitBtn | 提交按钮配置 | Object/Boolean | 参考下表 |
| resetBtn | 重置按钮配置 | Object/Boolean | 参考下表 |
| rules | 校验规则 | Object | { [fieldName]: rules } |
| class | 表单 class | String |  |
| style | 表单 style | Object |  |
| width | 表单宽度 | Number/String |  |
| disabled | 禁用 | Boolean |  |
| size | 尺寸 | String | 'large'/'default'/'small' |
| statusIcon | 校验图标 | Boolean |  |
| showMessage | 显示校验信息 | Boolean |  |
| inlineMessage | 行内校验信息 | Boolean |  |
| hideRequiredAsterisk | 隐藏必填星号 | Boolean |  |
| trimEmpty | 提交时去除空值 | Boolean |  |
| ... | 其余 el-form 支持的属性 |  |  |

### submitBtn/resetBtn 配置 | Submit/Reset Button Options
| 字段名 | 说明 | 类型 | 备注 |
|--------|------|------|------|
| text | 按钮文本 | String |  |
| width | 按钮宽度 | Number/String |  |
| type | 按钮类型 | String | 'primary'/'success'/'warning' 等 |
| plain | 朴素按钮 | Boolean |  |
| loading | 加载中 | Boolean |  |
| class | 按钮 class | String |  |
| ... | 其余 el-button 支持的属性 |  |  |

---

## v-model
- 绑定值类型：`Object`（表单数据）
- 用法：`v-model="formModel"`

---

## 事件 | Events
| 事件名 | 说明 | 回调参数 |
|--------|------|----------|
| submit | 提交表单时触发 | (done, ...args) |
| reset | 重置表单时触发 | (done, ...args) |
| validate | 校验通过时触发 | 无 |
| validateError | 校验失败时触发 | error |

---

## 插槽 | Slots
- 支持通过 slot 名自定义表单项内容、label、error、action 区域等。
- fields/slot 字段可实现自定义内容和插槽扩展。

---

## 方法 | Methods (通过 ref 调用)
| 方法名 | 说明 |
|--------|------|
| validate(callback) | 校验整个表单，返回 Promise |
| validateField(props, callback) | 校验指定字段 |
| resetFields(props) | 重置表单/指定字段 |
| clearValidate(props) | 清除校验结果 |
| scrollToField(prop) | 滚动到指定字段 |
| submit() | 提交表单 |
| reset() | 重置表单 |
| refs.formItem | 获取所有表单项 ref |
| refs.field | 获取所有字段 ref |
| root | el-form 实例 |

---

## 示例 | Example
```vue
<template>
  <VForm
    ref="formRef"
    v-model="formModel"
    :fields="fields"
    :config="config"
    @submit="onSubmit"
    @reset="onReset"
  >
    <template #namePrefix>👤</template>
    <template #inputErrorSlot>自定义错误提示</template>
    <template #optionSlot="{ option }">{{ option.label }} (自定义)</template>
  </VForm>
</template>

<script setup>
import { ref, h } from 'vue'
import { VForm } from 'your-lib-path'

const formModel = ref({})
const config = {
  labelWidth: 120,
  columns: 2,
  submitBtn: { text: '提交', class: 'submit-demo' },
  labelSuffix: ':',
  rules: {
    A: [ { required: true, message: '请输入姓名', trigger: 'blur' } ]
  }
}
const fields = [
  {
    name: 'A',
    component: 'Input',
    label: (data) => h('span', {}, `这是label${data.labelSuffix}`),
    placeholder: '请输入',
    clearable: true,
    slot: { prefix: 'namePrefix', error: 'inputErrorSlot' },
    rules: [ { min: 3, max: 5, message: 'Length should be 3 to 5', trigger: 'blur' } ]
  },
  {
    name: 'B',
    component: 'Select',
    label: '地区',
    placeholder: '请选择',
    clearable: true,
    options: [ { label: '上海', value: 0 }, { label: '北京', value: 1 } ],
    slot: { option: 'optionSlot' },
    rules: [ { required: true, message: '请选择地区', trigger: 'change' } ]
  },
  {
    name: 'C',
    component: 'DatePicker',
    label: '日期',
    placeholder: '请选择开始日期',
    valueFormat: 'x',
    slot: 'dateDefault'
  }
]
function onSubmit(done, ...args) {
  // 提交逻辑
  done()
}
function onReset(done, ...args) {
  // 重置逻辑
  done()
}
</script>
```