# CForm 表单组件

## 功能说明

CForm 是一个表单容器组件，用于管理表单数据、处理表单验证和提交。组件支持自动滚动到错误位置，提供了表单项变化回调和表单完成回调。

## 引用方式

```js
import { CForm } from '@components/forms/form';
```

## 组件参数

- `formData` (Object，必填)：表单数据对象，用于存储表单各项的值
- `autoScrollToError` (String，可选)：是否自动滚动到错误位置，默认为 off
  - `on`：启用自动滚动
  - `off`：禁用自动滚动
- `onChange` (Function，可选)：表单项变化的回调函数，参数为变化的表单项数据
- `onFinish` (Function，可选)：表单完成的回调函数，仅在提交且通过表单验证后调用，参数为整个表单数据

## 实例方法

- `$submit`：手动触发表单提交，会执行表单验证
- `$preVerify(keys, callback)`：提前验证指定的表单项，参数为表单项名称数组和回调函数
- `$setErrors(errors)`：直接设置表单错误，参数为错误对象，格式为 `{字段名: 错误信息}`
- `$setScrollTop(top)`：设置滚动位置，参数为滚动的 top 值

## 使用示例

### 基础用法

```html
<template>
  <CForm 
    :formData="form" 
    :onFinish="handleFinish"
  >
    <CFormItem name="username" label="用户名" required>
      <CInput type="text" placeholder="请输入用户名" />
    </CFormItem>
    <CFormItem name="password" label="密码" required>
      <CInput type="password" placeholder="请输入密码" />
    </CFormItem>
    <CFormSubmit text="提交" />
  </CForm>
</template>

<script>
import { CForm, CFormItem, CFormSubmit } from '@components/forms/form';
import { CInput } from '@components/forms/input';

export default {
  components: {
    CForm,
    CFormItem,
    CFormSubmit,
    CInput
  },
  data() {
    return {
      form: {
        username: '',
        password: ''
      }
    };
  },
  methods: {
    handleFinish() {
      // 表单验证通过后的处理逻辑
      console.log('表单提交成功', this.form);
      // 发送请求等操作
    }
  }
};
</script>
```

### 自动滚动到错误位置

```html
<CForm 
  :formData="form" 
  autoScrollToError="on" 
  :onFinish="handleFinish"
>
  <!-- 表单项 -->
</CForm>
```

### 手动提交表单

```js
// 在组件方法中调用
submitForm() {
  this.$refs.form.$submit();
}
```

```html
<CForm 
  ref="form" 
  :formData="form" 
  :onFinish="handleFinish"
>
  <!-- 表单项 -->
  <button @tap="evt => submitForm()">提交</button>
</CForm>
```

### 提前验证指定表单项

```js
// 在组件方法中调用
validateFields() {
  this.$refs.form.$preVerify(['username', 'email'], (passed) => {
    if (passed) {
      console.log('验证通过');
    } else {
      console.log('验证失败');
    }
  });
}
```

### 直接设置表单错误

```js
// 在组件方法中调用
setFormErrors() {
  this.$refs.form.$setErrors({
    username: '用户名已存在',
    email: '邮箱格式不正确'
  });
}
```

## 注意事项

1. CForm 组件需要与 CFormItem 组件配合使用，用于包装表单项
2. 表单数据对象（formData）的属性名应与 CFormItem 的 name 属性对应
3. 表单验证失败时会自动显示错误提示，并根据 autoScrollToError 设置决定是否滚动到错误位置
4. 表单验证通过后才会调用 onFinish 回调函数
5. 可以通过实例方法手动控制表单的提交、验证和错误设置