知识库文档，添加表单组件文档

Tevin

2025-03-13 c27e413f71c4beb1318237fedf585770702fe3a4

知识库文档，添加表单组件文档

 _cursor.ai/forms.doc/checkbox.doc/CCheckBox.doc.md

New file
@@ -0,0 +1,132 @@
# CCheckBox 复选框组件

## 功能说明

CCheckBox 是一个复选框组件，用于在表单中提供多选或单选功能。组件支持两种显示模式：直接显示模式和弹窗选择模式，以及两种选择类型：多选和单选。

## 引用方式

```js
import { CCheckBox } from '@components/forms/checkbox';
```

## 组件参数

- `itemRes` (Object，必填)：表单数据资源对象，表单组件内部机制专用
- `options` (Array，可选)：选项列表，每个选项应包含 label 和 value 属性，默认为空数组
- `boxType` (String，可选)：勾选类型，可选值有 checkbox（多选）、radio（单选），默认为 checkbox
- `displayType` (String，可选)：显示模式，可选值有 plane（直接显示）、dialog（弹窗选择），默认为 plane
- `placeholder` (String，可选)：输入框占位提示文本

## 使用示例

### 基础用法（多选，直接显示模式）

```html
<template>
  <CForm :form="form">
    <CFormItem name="hobbies" label="兴趣爱好">
      <CCheckBox 
        :options="hobbiesOptions" 
        placeholder="请选择兴趣爱好" 
      />
    </CFormItem>
  </CForm>
</template>

<script>
import { CForm, CFormItem } from '@components/forms/form';
import { CCheckBox } from '@components/forms/checkbox';

export default {
  components: {
    CForm,
    CFormItem,
    CCheckBox
  },
  data() {
    return {
      form: {
        hobbies: []
      },
      hobbiesOptions: [
        { label: '阅读', value: 'reading' },
        { label: '音乐', value: 'music' },
        { label: '运动', value: 'sports' },
        { label: '旅行', value: 'travel' },
        { label: '电影', value: 'movie' }
      ]
    };
  }
};
</script>
```

### 单选模式

```html
<CFormItem name="gender" label="性别">
  <CCheckBox 
    boxType="radio" 
    :options="genderOptions" 
    placeholder="请选择性别" 
  />
</CFormItem>
```

```js
data() {
  return {
    form: {
      gender: ''
    },
    genderOptions: [
      { label: '男', value: 'male' },
      { label: '女', value: 'female' }
    ]
  };
}
```

### 弹窗选择模式

```html
<CFormItem name="skills" label="技能">
  <CCheckBox 
    displayType="dialog" 
    :options="skillsOptions" 
    placeholder="请选择技能" 
  />
</CFormItem>
```

```js
data() {
  return {
    form: {
      skills: []
    },
    skillsOptions: [
      { label: 'JavaScript', value: 'js' },
      { label: 'HTML', value: 'html' },
      { label: 'CSS', value: 'css' },
      { label: 'Vue', value: 'vue' },
      { label: 'React', value: 'react' },
      { label: 'Node.js', value: 'node' }
    ]
  };
}
```

## 注意事项

1. 组件支持两种选择类型：
   - `checkbox`：多选模式，可以选择多个选项，表单值为数组
   - `radio`：单选模式，只能选择一个选项，表单值为单个值
2. 组件支持两种显示模式：
   - `plane`：直接显示模式，选项直接显示在表单项下方
   - `dialog`：弹窗选择模式，点击表单项后弹出选择弹窗
3. 当选项较多时，建议使用弹窗选择模式（`displayType="dialog"`）
4. 在多选模式下，表单值为选中项的 value 值组成的数组
5. 在单选模式下，表单值为选中项的 value 值
6. 组件会自动根据表单值显示已选项的文本，多个选项时用逗号分隔 

 _cursor.ai/forms.doc/chinaArea.doc/CChinaArea.doc.md

New file
@@ -0,0 +1,89 @@
# CChinaArea 中国地区选择器组件

## 功能说明

CChinaArea 是一个中国地区选择器组件，用于在表单中选择省市区地址。组件内置了完整的中国行政区划数据，支持省、市、区三级联动选择，并且可以设置默认值和只读模式。

## 引用方式

```js
import { CChinaArea } from '@components/forms/chinaArea';
```

## 组件参数

- `itemRes` (Object，必填)：表单数据资源对象，表单组件内部机制专用
- `level` (Number，可选)：选择层级，可选值为 1（省）、2（省市）、3（省市区），默认为 3
- `placeholder` (String，可选)：选择器占位提示文本
- `readOnly` (Boolean，可选)：只读模式，默认为 false
- `separator` (String，可选)：地址文本分隔符，默认为空格
- `defaultCode` (String，可选)：默认选中的区域编码

## 使用示例

### 基础用法

```html
<template>
  <CForm :form="form">
    <CFormItem name="address" label="所在地区">
      <CChinaArea 
        placeholder="请选择所在地区" 
      />
    </CFormItem>
  </CForm>
</template>

<script>
import { CForm, CFormItem } from '@components/forms/form';
import { CChinaArea } from '@components/forms/chinaArea';

export default {
  components: {
    CForm,
    CFormItem,
    CChinaArea
  },
  data() {
    return {
      form: {
        address: {
          province: '',
          city: '',
          district: '',
          code: ''
        }
      }
    };
  }
};
</script>
```

### 自定义配置

```html
<CFormItem name="region" label="配送区域">
  <CChinaArea 
    :level="2" 
    separator="/" 
    defaultCode="330100" 
    placeholder="请选择配送区域" 
  />
</CFormItem>
```

## 注意事项

1. 组件返回的数据格式为对象，包含以下字段：
   - `province`：省份名称
   - `city`：城市名称
   - `district`：区县名称（仅在 level=3 时有值）
   - `code`：选中区域的行政区划代码
2. 可以通过 `defaultCode` 设置默认选中的区域
3. `level` 参数决定了选择的层级：
   - 1：仅选择省份
   - 2：选择省份和城市
   - 3：选择省份、城市和区县
4. 组件会根据当前选择自动联动更新下级选项
5. 在只读模式下，地址信息将以文本形式显示，使用 `separator` 分隔 

 _cursor.ai/forms.doc/datePicker.doc/CDatePicker.doc.md

New file
@@ -0,0 +1,112 @@
# CDatePicker 日期选择组件

## 功能说明

CDatePicker 是一个日期选择组件，用于在表单中选择日期或日期范围。组件支持三种选择模式：日期选择、日期时间选择和日期范围选择。

## 引用方式

```js
import { CDatePicker } from '@components/forms/datePicker';
```

## 组件参数

- `itemRes` (Object，必填)：表单数据资源对象，表单组件内部机制专用
- `mode` (String，可选)：日期时间选择器模式，可选值有 date、dateTime、dateRange，默认为 date
- `placeholder` (String，可选)：输入框占位提示文本
- `limitStart` (String，可选)：可选日期的开始日期，格式为 YYYY-MM-DD
- `limitEnd` (String，可选)：可选日期的结束日期，格式为 YYYY-MM-DD
- `fields` (String，可选)：日期选择粒度，可选值有 year、month、day，默认为 day
- `readOnly` (Boolean，可选)：只读模式，默认为 false
- `allowClear` (Boolean，可选)：是否允许清除已选值，默认为 false

## 使用示例

### 基础用法（日期选择模式）

```html
<template>
  <CForm :form="form">
    <CFormItem name="birthday" label="出生日期">
      <CDatePicker placeholder="请选择出生日期" />
    </CFormItem>
  </CForm>
</template>

<script>
import { CForm, CFormItem } from '@components/forms/form';
import { CDatePicker } from '@components/forms/datePicker';

export default {
  components: {
    CForm,
    CFormItem,
    CDatePicker
  },
  data() {
    return {
      form: {
        birthday: ''
      }
    };
  }
};
</script>
```

### 日期时间选择模式

```html
<CFormItem name="meetingTime" label="会议时间">
  <CDatePicker 
    mode="dateTime" 
    placeholder="请选择会议时间" 
  />
</CFormItem>
```

### 日期范围选择模式

```html
<CFormItem name="vacationPeriod" label="休假时间">
  <CDatePicker 
    mode="dateRange" 
    placeholder="请选择休假时间段" 
  />
</CFormItem>
```

### 限制可选日期范围

```html
<CFormItem name="appointmentDate" label="预约日期">
  <CDatePicker 
    limitStart="2023-01-01" 
    limitEnd="2023-12-31" 
    placeholder="请选择预约日期" 
  />
</CFormItem>
```

### 允许清除已选值

```html
<CFormItem name="deadline" label="截止日期">
  <CDatePicker 
    :allowClear="true" 
    placeholder="请选择截止日期" 
  />
</CFormItem>
```

## 注意事项

1. 不同的 `mode` 值对应不同的日期选择交互方式：
   - `date`：选择单个日期，使用系统日期选择器
   - `dateTime`：选择日期和时间，使用自定义的日期时间选择器
   - `dateRange`：选择日期范围，使用自定义的日期范围选择器
2. 当设置 `allowClear` 为 true 时，已选择日期后会显示清除图标，点击可清除已选值
3. `limitStart` 和 `limitEnd` 参数仅在 `mode` 为 date 时生效
4. 组件默认的可选日期范围是当前年份的前后 30 年
5. 在只读模式下，日期选择器将不可操作 

 _cursor.ai/forms.doc/form.doc/CForm.doc.md

New file
@@ -0,0 +1,142 @@
# CForm 表单组件

## 功能说明

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

## 引用方式

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

## 组件参数

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

## 实例方法

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

## 使用示例

### 基础用法

```html
<template>
  <CForm 
    :form="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 
  :form="form" 
  autoScrollToError="on" 
  :onFinish="handleFinish"
>
  <!-- 表单项 -->
</CForm>
```

### 手动提交表单

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

```html
<CForm 
  ref="form" 
  :form="form" 
  :onFinish="handleFinish"
>
  <!-- 表单项 -->
  <button @tap="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. 可以通过实例方法手动控制表单的提交、验证和错误设置 

 _cursor.ai/forms.doc/form.doc/CFormAgreement.doc.md

New file
@@ -0,0 +1,88 @@
# CFormAgreement 表单协议组件

## 功能说明

CFormAgreement 是表单协议组件，用于在表单中提供用户协议勾选功能。组件包含勾选框和协议文本，点击协议文本可以打开浮层查看详细内容。

## 引用方式

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

## 组件参数

- `formRes` (Object，必填)：表单资源对象，由 CForm 组件提供
- `protocol` (String，必填)：需要同意的协议名称，如"用户协议"、"隐私政策"等

## 使用示例

### 基础用法

```html
<template>
  <CForm :form="form" :onFinish="handleFinish">
    <CFormItem name="username" label="用户名" required>
      <CInput type="text" placeholder="请输入用户名" />
    </CFormItem>
    
    <CFormAgreement :formRes="formRes" protocol="《用户协议》">
      <view class="protocol-content">
        <!-- 协议详细内容 -->
        <view class="paragraph">
          欢迎您使用我们的服务。在使用我们的服务前，请您仔细阅读以下条款...
        </view>
        <view class="paragraph">
          1. 服务条款的确认和接纳...
        </view>
        <view class="paragraph">
          2. 用户信息保护...
        </view>
        <!-- 更多协议内容 -->
      </view>
    </CFormAgreement>
    
    <CFormSubmit>提交</CFormSubmit>
  </CForm>
</template>

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

export default {
  components: {
    CForm,
    CFormItem,
    CFormSubmit,
    CFormAgreement,
    CInput
  },
  data() {
    return {
      form: {
        username: ''
      },
      formRes: null
    };
  },
  methods: {
    handleFinish() {
      console.log('表单提交成功', this.form);
    }
  },
  mounted() {
    // 获取表单资源对象
    this.formRes = this.$refs.form.formRes;
  }
};
</script>
```

## 注意事项

1. CFormAgreement 组件需要在 CForm 组件内使用，并且需要传入表单资源对象 formRes
2. 组件会在表单验证时检查是否已勾选协议，未勾选时会阻止表单提交并显示提示信息
3. 协议详细内容通过默认插槽提供，会在点击协议名称时在浮层中显示
4. 组件内部使用了特殊的字段名 `$agreement` 进行验证，不会影响表单数据
5. 为了获取 formRes 对象，需要在组件挂载后从 CForm 组件实例中获取 

 _cursor.ai/forms.doc/form.doc/CFormItem.doc.md

New file
@@ -0,0 +1,100 @@
# CFormItem 表单项组件

## 功能说明

CFormItem 是表单项容器组件，用于包装各种表单控件，提供表单项的标签、验证规则和错误状态管理。组件基于 async-validator 库实现表单验证功能。

## 引用方式

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

## 组件参数

- `formRes` (Object，必填)：表单资源对象，由 CForm 组件提供
- `name` (String，必填)：表单项字段键名，对应表单数据对象中的属性名
- `label` (String，可选)：表单项中文名，用于显示和错误提示
- `required` (Boolean，可选)：表单项是否必填
- `rules` (Array，可选)：表单项验证规则，基于 async-validator 的规则配置
- `disabled` (Boolean，可选)：表单项是否禁用

## 使用示例

### 基础用法

```html
<template>
  <CForm :form="form">
    <CFormItem name="username" label="用户名" required>
      <CInput type="text" placeholder="请输入用户名" />
    </CFormItem>
  </CForm>
</template>

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

export default {
  components: {
    CForm,
    CFormItem,
    CInput
  },
  data() {
    return {
      form: {
        username: ''
      }
    };
  }
};
</script>
```

### 使用验证规则

```html
<CFormItem 
  name="email" 
  label="邮箱" 
  :rules="[
    { type: 'email', message: '请输入有效的邮箱地址' }
  ]"
>
  <CInput type="text" placeholder="请输入邮箱" />
</CFormItem>
```

### 复合验证规则

```html
<CFormItem 
  name="password" 
  label="密码" 
  :rules="[
    { required: true, message: '请输入密码' },
    { type: 'string', min: 6, message: '密码长度不能少于6个字符' },
    { pattern: /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[^]{6,20}$/, message: '密码必须包含大小写字母和数字' }
  ]"
>
  <CInput type="password" placeholder="请输入密码" />
</CFormItem>
```

## 注意事项

1. CFormItem 组件需要在 CForm 组件内使用，并通过 slot 接收表单控件
2. 表单项的 name 属性必须与表单数据对象中的属性名对应
3. 验证规则基于 async-validator 库，支持多种验证类型和自定义规则
4. 常用的验证规则类型包括：
   - `type`：类型验证，如 string、number、boolean、array、object、url、email 等
   - `len`：长度验证，string 类型为字符串长度，number 类型为确定数字，array 类型为数组长度
   - `max`：最大值验证，string 类型为最大长度，number 类型为最大值，array 类型为最大长度
   - `min`：最小值验证，string 类型为最小长度，number 类型为最小值，array 类型为最小长度
   - `pattern`：正则表达式匹配
   - `required`：是否为必填字段
   - `transform`：将字段值转换成目标值后进行校验
   - `message`：错误信息，不设置时会通过模板自动生成
5. 表单验证失败时，组件会自动显示错误状态，并在 5 秒后自动清除 

 _cursor.ai/forms.doc/form.doc/CFormSubmit.doc.md

New file
@@ -0,0 +1,77 @@
# CFormSubmit 表单提交按钮组件

## 功能说明

CFormSubmit 是表单提交按钮组件，用于在表单中提供提交按钮。组件支持固定在底部显示，并可以通过插槽自定义按钮文本。

## 引用方式

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

## 组件参数

- `fixed` (Boolean，可选)：是否固定在底部显示，默认为 false

## 使用示例

### 基础用法

```html
<template>
  <CForm :form="form" :onFinish="handleFinish">
    <CFormItem name="username" label="用户名" required>
      <CInput type="text" placeholder="请输入用户名" />
    </CFormItem>
    <CFormSubmit>提交</CFormSubmit>
  </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: ''
      }
    };
  },
  methods: {
    handleFinish() {
      console.log('表单提交成功', this.form);
    }
  }
};
</script>
```

### 固定在底部显示

```html
<CFormSubmit :fixed="true">确认提交</CFormSubmit>
```

### 自定义按钮文本

```html
<CFormSubmit>
  <view class="custom-btn-text">保存并继续</view>
</CFormSubmit>
```

## 注意事项

1. CFormSubmit 组件需要在 CForm 组件内使用，才能触发表单提交和验证
2. 组件内部使用了 `form-type="submit"` 属性，可以自动触发表单提交
3. 当设置 `fixed` 为 true 时，按钮会固定在页面底部显示，适用于长表单
4. 可以通过默认插槽自定义按钮的文本内容，默认显示"提交" 

 _cursor.ai/forms.doc/imagePicker.doc/CImagePicker.doc.md

New file
@@ -0,0 +1,80 @@
# CImagePicker 图片选择器组件

## 功能说明

CImagePicker 是一个图片选择器组件，用于在表单中上传和管理图片。组件支持单张和多张图片上传，支持预览、删除等功能，并且可以限制上传图片的数量和大小。

## 引用方式

```js
import { CImagePicker } from '@components/forms/imagePicker';
```

## 组件参数

- `itemRes` (Object，必填)：表单数据资源对象，表单组件内部机制专用
- `maxCount` (Number，可选)：最大上传图片数量，默认为 9
- `maxSize` (Number，可选)：单张图片最大大小，单位为 MB，默认为 5
- `compress` (Boolean，可选)：是否压缩图片，默认为 true
- `quality` (Number，可选)：图片压缩质量，取值范围 0-1，默认为 0.8
- `placeholder` (String，可选)：选择器占位提示文本
- `readOnly` (Boolean，可选)：只读模式，默认为 false

## 使用示例

### 基础用法

```html
<template>
  <CForm :form="form">
    <CFormItem name="photos" label="图片上传">
      <CImagePicker 
        :maxCount="3" 
        placeholder="请上传图片" 
      />
    </CFormItem>
  </CForm>
</template>

<script>
import { CForm, CFormItem } from '@components/forms/form';
import { CImagePicker } from '@components/forms/imagePicker';

export default {
  components: {
    CForm,
    CFormItem,
    CImagePicker
  },
  data() {
    return {
      form: {
        photos: []
      }
    };
  }
};
</script>
```

### 自定义配置

```html
<CFormItem name="certificate" label="证书照片">
  <CImagePicker 
    :maxCount="1" 
    :maxSize="2" 
    :compress="true" 
    :quality="0.6" 
    placeholder="请上传证书照片" 
  />
</CFormItem>
```

## 注意事项

1. 组件会自动处理图片上传，支持压缩和预览功能
2. 上传的图片会被转换为 base64 格式存储在表单数据中
3. 当设置 `maxCount` 为 1 时，组件会以单图模式运行
4. 建议根据实际需求设置合适的 `maxSize` 和压缩参数
5. 在只读模式下，只能查看已上传的图片，无法进行上传和删除操作 

 _cursor.ai/forms.doc/input.doc/CInput.doc.md

New file
@@ -0,0 +1,76 @@
# CInput 文本输入框组件

## 功能说明

CInput 是一个基础的文本输入框组件，用于在表单中收集用户的文本输入。组件支持多种输入类型，可以设置占位提示文本，并且支持显示单位标识。

## 引用方式

```js
import { CInput } from '@components/forms/input';
```

## 组件参数

- `itemRes` (Object，必填)：表单数据资源对象，表单组件内部机制专用
- `type` (String，可选)：输入框类型，可选值有 text、number、password、phone、idcard、digit
- `placeholder` (String，可选)：输入框占位提示文本
- `unit` (String，可选)：输入框单位，设置后会在输入框右侧显示单位文本
- `readOnly` (Boolean，可选)：只读模式，默认为 false

## 使用示例

### 基础用法

```html
<template>
  <CForm :form="form">
    <CFormItem name="username" label="用户名">
      <CInput type="text" placeholder="请输入用户名" />
    </CFormItem>
  </CForm>
</template>

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

export default {
  components: {
    CForm,
    CFormItem,
    CInput
  },
  data() {
    return {
      form: {
        username: ''
      }
    };
  }
};
</script>
```

### 带单位的输入框

```html
<CFormItem name="weight" label="重量">
  <CInput type="digit" placeholder="请输入重量" unit="kg" />
</CFormItem>
```

### 只读模式

```html
<CFormItem name="id" label="ID">
  <CInput type="text" readOnly />
</CFormItem>
```

## 注意事项

1. CInput 组件通常需要配合 CForm 和 CFormItem 组件一起使用
2. 组件会自动处理输入值，去除首尾空格和换行符
3. 当设置 `unit` 属性时，会在输入框右侧显示单位文本
4. 在只读模式下，输入框将不可编辑 

 _cursor.ai/forms.doc/input.doc/CInputExpressCode.doc.md

New file
@@ -0,0 +1,58 @@
# CInputExpressCode 快递单号输入框组件

## 功能说明

CInputExpressCode 是一个快递单号输入框组件，集成了文本输入框和扫码功能。用户可以通过点击扫码图标调用设备的扫码功能，将扫描的快递单号自动填入输入框中。组件会验证扫描结果是否符合快递单号格式。

## 引用方式

```js
import { CInputExpressCode } from '@components/forms/input';
```

## 组件参数

- `itemRes` (Object，必填)：表单数据资源对象，表单组件内部机制专用
- `placeholder` (String，可选)：输入框占位提示文本

## 使用示例

### 基础用法

```html
<template>
  <CForm :form="form">
    <CFormItem name="expressCode" label="快递单号">
      <CInputExpressCode placeholder="请输入或扫描快递单号" />
    </CFormItem>
  </CForm>
</template>

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

export default {
  components: {
    CForm,
    CFormItem,
    CInputExpressCode
  },
  data() {
    return {
      form: {
        expressCode: ''
      }
    };
  }
};
</script>
```

## 注意事项

1. 扫码功能仅在小程序环境中可用，在其他环境中不会显示扫码图标
2. 组件会验证扫描结果是否符合快递单号格式（只允许数字和字母），不符合时会提示"请扫描快递单号！"
3. 扫码过程中，扫码图标会显示加载状态
4. 扫码取消或失败时，会显示相应的提示信息
5. 此组件主要针对快递单号的输入场景进行了优化，适用于物流、快递相关的业务场景 

 _cursor.ai/forms.doc/input.doc/CInputPhoneCode.doc.md

New file
@@ -0,0 +1,109 @@
# CInputPhoneCode 手机验证码输入框组件

## 功能说明

CInputPhoneCode 是一个手机验证码输入框组件，集成了验证码输入框和获取验证码按钮。按钮具有倒计时功能，防止用户频繁获取验证码。

## 引用方式

```js
import { CInputPhoneCode } from '@components/forms/input';
```

## 组件参数

- `itemRes` (Object，必填)：表单数据资源对象，表单组件内部机制专用
- `placeholder` (String，可选)：输入框占位提示文本
- `autoStart` (Boolean，可选)：验证码计时器开始方式，默认为 true
  - `true`：点击按钮后立即自动开始倒计时
  - `false`：后台返回成功时才开始倒计时
- `onCallPhoneCode` (Function，必填)：发送请求，通知后端给手机发送验证码的回调函数
- `onRefreshCD` (Function，可选)：刷新倒计时后，通知父组件更新图片地址的回调函数

## 实例方法

- `$resetHolding`：重置按钮的禁用状态，使按钮可以再次点击

## 使用示例

### 基础用法

```html
<template>
  <CForm :form="form">
    <CFormItem name="phone" label="手机号">
      <CInput type="phone" placeholder="请输入手机号" />
    </CFormItem>
    <CFormItem name="code" label="验证码">
      <CInputPhoneCode 
        placeholder="请输入验证码" 
        :onCallPhoneCode="handleSendCode" 
      />
    </CFormItem>
  </CForm>
</template>

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

export default {
  components: {
    CForm,
    CFormItem,
    CInput,
    CInputPhoneCode
  },
  data() {
    return {
      form: {
        phone: '',
        code: ''
      }
    };
  },
  methods: {
    handleSendCode(callback) {
      // 验证手机号
      if (!this.form.phone) {
        this.$toast('请先输入手机号');
        return;
      }
      
      // 发送验证码请求
      this.$api.sendSmsCode({
        phone: this.form.phone
      }).then(() => {
        this.$toast('验证码已发送');
        callback(); // 如果 autoStart 为 false，需要调用回调函数开始倒计时
      }).catch(err => {
        this.$toast(err.message || '发送失败');
      });
    }
  }
};
</script>
```

### 手动控制倒计时

```html
<CInputPhoneCode 
  placeholder="请输入验证码" 
  :autoStart="false"
  :onCallPhoneCode="handleSendCode" 
  ref="phoneCode"
/>
```

```js
// 在需要重置倒计时的地方调用
this.$refs.phoneCode.$resetHolding();
```

## 注意事项

1. 组件内部包含一个 60 秒的倒计时，在倒计时结束前，获取验证码按钮将处于禁用状态
2. 当 `autoStart` 设置为 false 时，需要在 `onCallPhoneCode` 回调函数中手动调用传入的回调函数来开始倒计时
3. 通常需要在 `onCallPhoneCode` 回调中验证手机号是否有效，再决定是否发送验证码请求
4. 可以通过 `$resetHolding` 方法手动重置按钮状态，适用于特殊情况下需要提前结束倒计时的场景 

 _cursor.ai/forms.doc/input.doc/CInputScanCode.doc.md

New file
@@ -0,0 +1,126 @@
# CInputScanCode 扫码输入框组件

## 功能说明

CInputScanCode 是一个扫码输入框组件，集成了文本输入框和扫码按钮。用户可以通过点击扫码按钮调用设备的扫码功能，将扫描结果自动填入输入框中。

## 引用方式

```js
import { CInputScanCode } from '@components/forms/input';
```

## 组件参数

- `itemRes` (Object，必填)：表单数据资源对象，表单组件内部机制专用
- `placeholder` (String，可选)：输入框占位提示文本
- `readOnly` (Boolean，可选)：只读模式，默认为 false，设置为 true 时扫码按钮将被禁用
- `onScaning` (Function，可选)：由业务层调用 app 的扫码功能时的回调函数，主要用于非小程序环境
- `onBlur` (Function，可选)：输入框失去焦点时的回调函数

## 使用示例

### 基础用法

```html
<template>
  <CForm :form="form">
    <CFormItem name="barcode" label="条形码">
      <CInputScanCode placeholder="请扫描条形码" />
    </CFormItem>
  </CForm>
</template>

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

export default {
  components: {
    CForm,
    CFormItem,
    CInputScanCode
  },
  data() {
    return {
      form: {
        barcode: ''
      }
    };
  }
};
</script>
```

### 在 App 中使用（非小程序环境）

```html
<template>
  <CForm :form="form">
    <CFormItem name="barcode" label="条形码">
      <CInputScanCode 
        placeholder="请扫描条形码" 
        :onScaning="handleScaning" 
      />
    </CFormItem>
  </CForm>
</template>

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

export default {
  components: {
    CForm,
    CFormItem,
    CInputScanCode
  },
  data() {
    return {
      form: {
        barcode: ''
      }
    };
  },
  methods: {
    handleScaning(callback) {
      // 调用 App 原生的扫码功能
      // 示例：通过 JSBridge 调用原生扫码
      if (window.JSBridge) {
        window.JSBridge.callNative('scanBarcode', {}, (result) => {
          if (result && result.code) {
            callback(result.code);
          } else {
            this.$toast('扫码失败');
            callback(null);
          }
        });
      } else {
        this.$toast('当前环境不支持扫码');
        callback(null);
      }
    }
  }
};
</script>
```

### 只读模式

```html
<CFormItem name="barcode" label="条形码">
  <CInputScanCode placeholder="请扫描条形码" :readOnly="true" />
</CFormItem>
```

## 注意事项

1. 组件会根据运行环境自动选择扫码方式：
   - 在小程序环境中，使用 Taro.scanCode API
   - 在 H5 环境中的微信浏览器内，也使用 Taro.scanCode API
   - 在其他浏览器环境中，通过 onScaning 回调函数调用 App 原生的扫码功能
2. 扫码过程中，扫码按钮会显示加载状态
3. 扫码取消或失败时，会显示相应的提示信息
4. 在只读模式下，扫码按钮将被禁用
5. 使用此组件时，需要确保应用有相应的扫码权限 

 _cursor.ai/forms.doc/numberStep.doc/CNumberStep.doc.md

New file
@@ -0,0 +1,94 @@
# CNumberStep 数字步进器组件

## 功能说明

CNumberStep 是一个数字步进器组件，用于在表单中输入数字并通过步进按钮增减数值。组件支持设置数值范围、步长、奇偶修正和单位显示。

## 引用方式

```js
import { CNumberStep } from '@components/forms/numberStep';
```

## 组件参数

- `itemRes` (Object，必填)：表单数据资源对象，表单组件内部机制专用
- `placeholder` (String，可选)：输入框占位提示文本
- `range` (Array，可选)：取值范围，格式为 [最小值, 最大值]，默认为 [0, 100]
- `step` (Number，可选)：步长，即每次点击增减按钮改变的数值，默认为 1
- `correct` (String，可选)：奇偶修正模式，可选值有 odd（奇数）、even（偶数），默认为空
- `unit` (String，可选)：数值单位，显示在数字输入框右侧

## 使用示例

### 基础用法

```html
<template>
  <CForm :form="form">
    <CFormItem name="quantity" label="数量">
      <CNumberStep />
    </CFormItem>
  </CForm>
</template>

<script>
import { CForm, CFormItem } from '@components/forms/form';
import { CNumberStep } from '@components/forms/numberStep';

export default {
  components: {
    CForm,
    CFormItem,
    CNumberStep
  },
  data() {
    return {
      form: {
        quantity: 1
      }
    };
  }
};
</script>
```

### 设置取值范围和步长

```html
<CFormItem name="age" label="年龄">
  <CNumberStep :range="[18, 60]" :step="1" />
</CFormItem>
```

### 奇偶修正模式

```html
<!-- 只允许选择奇数 -->
<CFormItem name="oddNumber" label="奇数">
  <CNumberStep correct="odd" />
</CFormItem>

<!-- 只允许选择偶数 -->
<CFormItem name="evenNumber" label="偶数">
  <CNumberStep correct="even" />
</CFormItem>
```

### 显示单位

```html
<CFormItem name="weight" label="重量">
  <CNumberStep :range="[0, 200]" :step="0.5" unit="kg" />
</CFormItem>
```

## 注意事项

1. CNumberStep 组件通常需要配合 CForm 和 CFormItem 组件一起使用
2. 当设置 `correct` 参数时，组件会自动修正输入值，确保符合奇数或偶数的要求
3. 奇偶修正规则：
   - 当输入值不符合奇偶要求时，如果是增加操作，会再增加 1；如果是减少操作，会再减少 1
   - 如果修正后的值超出范围，则会向相反方向修正
4. 组件支持直接输入数字，但会自动限制在设定的范围内
5. 当输入框为空时，点击步进按钮会将值设置为最小值 

 _cursor.ai/forms.doc/numberValve.doc/CNumberValve.doc.md

New file
@@ -0,0 +1,79 @@
# CNumberValve 数值滑块组件

## 功能说明

CNumberValve 是一个数值滑块组件，用于在表单中通过滑块选择数值。组件提供了滑动条和增减按钮两种方式来调整数值，并支持设置数值范围、步长和单位显示。

## 引用方式

```js
import { CNumberValve } from '@components/forms/numberValve';
```

## 组件参数

- `itemRes` (Object，必填)：表单数据资源对象，表单组件内部机制专用
- `placeholder` (String，可选)：输入框占位提示文本
- `range` (Array，可选)：取值范围，格式为 [最小值, 最大值]，默认为 [0, 100]
- `step` (Number，可选)：步长，即每次调整改变的最小数值单位，默认为 1
- `unit` (String，可选)：数值单位，仅用于显示，不影响实际值

## 使用示例

### 基础用法

```html
<template>
    <CForm :form="form">
        <CFormItem name="volume" label="音量">
            <CNumberValve placeholder="请选择音量" />
        </CFormItem>
    </CForm>
</template>

<script>
import { CForm, CFormItem } from '@components/forms/form';
import { CNumberValve } from '@components/forms/numberValve';

export default {
    components: {
        CForm,
        CFormItem,
        CNumberValve,
    },
    data() {
        return {
            form: {
                volume: 50,
            },
        };
    },
};
</script>
```

### 设置取值范围和步长

```html
<CFormItem name="temperature" label="温度">
    <CNumberValve :range="[16, 32]" :step="0.5" placeholder="请选择温度" />
</CFormItem>
```

### 显示单位

```html
<CFormItem name="distance" label="距离">
    <CNumberValve :range="[0, 1000]" :step="10" unit="米" placeholder="请选择距离" />
</CFormItem>
```

## 注意事项

1. CNumberValve 组件通常需要配合 CForm 和 CFormItem 组件一起使用
2. 点击组件会弹出滑块选择浮层，用户可以通过以下方式调整数值：
    - 拖动滑块：直接拖动滑块到所需位置
    - 点击按钮：点击"减小"或"增加"按钮按步长调整数值
3. 组件会根据设定的步长自动对数值进行修正，确保数值是步长的整数倍
4. 当设置了 `unit` 参数时，单位文本会显示在表单项的值后面，但不会影响实际存储的数值
5. 组件会自动限制数值在设定的范围内

 _cursor.ai/forms.doc/select.doc/CJumpSelect.doc.md

New file
@@ -0,0 +1,105 @@
# CJumpSelect 跳转选择组件

## 功能说明

CJumpSelect 是一个跳转选择组件，用于在表单中提供跨页面的选择功能。点击组件会触发回调函数，开发者可以在回调中实现跳转到选择页面的逻辑，并通过回调接收选择结果。

## 引用方式

```js
import { CJumpSelect } from '@components/forms/select';
```

## 组件参数

- `itemRes` (Object，必填)：表单数据资源对象，表单组件内部机制专用
- `placeholder` (String，可选)：输入框占位提示文本
- `onPageSelectCall` (Function，必填)：跨页选择模式的回调函数，用于处理页面跳转和接收选择结果
- `readOnly` (Boolean，可选)：只读模式，默认为 false

## 使用示例

### 基础用法

```html
<template>
  <CForm :form="form">
    <CFormItem name="department" label="部门">
      <CJumpSelect 
        placeholder="请选择部门" 
        :onPageSelectCall="handleDepartmentSelect" 
      />
    </CFormItem>
  </CForm>
</template>

<script>
import { CForm, CFormItem } from '@components/forms/form';
import { CJumpSelect } from '@components/forms/select';

export default {
  components: {
    CForm,
    CFormItem,
    CJumpSelect
  },
  data() {
    return {
      form: {
        department: ''
      },
      // 保存回调函数
      selectCallback: null
    };
  },
  methods: {
    handleDepartmentSelect(callback) {
      if (callback === null) {
        // 组件销毁时会传入 null，清除回调
        this.selectCallback = null;
        return;
      }
      
      // 保存回调函数
      this.selectCallback = callback;
      
      // 跳转到部门选择页面
      this.$router.push({
        path: '/pages/department-selector/index'
      });
    },
    
    // 在部门选择页面选择完成后调用
    onDepartmentSelected(department) {
      if (this.selectCallback) {
        // 调用回调函数，传递选择结果
        this.selectCallback({
          name: department.name,
          value: department.id
        });
      }
    }
  }
};
</script>
```

### 只读模式

```html
<CFormItem name="department" label="部门">
  <CJumpSelect 
    placeholder="请选择部门" 
    :onPageSelectCall="handleDepartmentSelect" 
    :readOnly="true" 
  />
</CFormItem>
```

## 注意事项

1. CJumpSelect 组件主要用于需要跳转到其他页面进行选择的场景，如选择复杂的组织架构、多级分类等
2. `onPageSelectCall` 回调函数会在组件点击时被调用，并传入一个回调函数，用于接收选择结果
3. 选择结果应包含 `name` 和 `value` 两个属性，分别表示选项的显示名称和值
4. 组件在销毁时会调用 `onPageSelectCall(null)`，开发者应在回调函数中处理这种情况，清除相关状态
5. 在只读模式下，下拉箭头图标将被隐藏，且无法触发选择操作 

 _cursor.ai/forms.doc/select.doc/CSelect.doc.md

New file
@@ -0,0 +1,132 @@
# CSelect 下拉选择组件

## 功能说明

CSelect 是一个下拉选择组件，用于在表单中提供选项选择功能。组件支持两种选择模式：下拉选择模式和跳转页面选择模式。

## 引用方式

```js
import { CSelect } from '@components/forms/select';
```

## 组件参数

- `itemRes` (Object，必填)：表单数据资源对象，表单组件内部机制专用
- `options` (Array，必填)：选择菜单选项数组，每个选项应包含 name 和 value/id 属性
- `placeholder` (String，可选)：输入框占位提示文本
- `readOnly` (Boolean，可选)：只读模式，默认为 false
- `selectByPage` (String，可选)：开启选择菜单跳转选择页面模式，值为 'on'
- `onOpenSelectorPage` (Function，可选)：页面跳转模式下，发起选择的回调函数

## 使用示例

### 基础用法（下拉选择模式）

```html
<template>
  <CForm :form="form">
    <CFormItem name="gender" label="性别">
      <CSelect :options="genderOptions" placeholder="请选择性别" />
    </CFormItem>
  </CForm>
</template>

<script>
import { CForm, CFormItem } from '@components/forms/form';
import { CSelect } from '@components/forms/select';

export default {
  components: {
    CForm,
    CFormItem,
    CSelect
  },
  data() {
    return {
      form: {
        gender: ''
      },
      genderOptions: [
        { name: '男', value: 'male' },
        { name: '女', value: 'female' }
      ]
    };
  }
};
</script>
```

### 跳转页面选择模式

```html
<template>
  <CForm :form="form">
    <CFormItem name="city" label="城市">
      <CSelect 
        selectByPage="on" 
        :onOpenSelectorPage="handleOpenCitySelector" 
        placeholder="请选择城市" 
      />
    </CFormItem>
  </CForm>
</template>

<script>
import { CForm, CFormItem } from '@components/forms/form';
import { CSelect } from '@components/forms/select';

export default {
  components: {
    CForm,
    CFormItem,
    CSelect
  },
  data() {
    return {
      form: {
        city: ''
      }
    };
  },
  methods: {
    handleOpenCitySelector() {
      // 跳转到城市选择页面
      this.$router.push({
        path: '/pages/city-selector/index',
        query: {
          callback: 'onCitySelected'
        }
      });
      
      // 在全局注册回调函数，用于接收选择结果
      this.$app.onCitySelected = (city) => {
        this.form.city = city.value;
      };
    }
  }
};
</script>
```

### 只读模式

```html
<CFormItem name="gender" label="性别">
  <CSelect 
    :options="genderOptions" 
    placeholder="请选择性别" 
    :readOnly="true" 
  />
</CFormItem>
```

## 注意事项

1. 组件支持两种选项数据格式：
   - 使用 `value` 作为选项值：`{ name: '选项名', value: '选项值' }`
   - 使用 `id` 作为选项值：`{ name: '选项名', id: '选项值' }`
2. 当选项数量较多时，建议使用跳转页面选择模式（`selectByPage="on"`）
3. 在跳转页面选择模式下，需要提供 `onOpenSelectorPage` 回调函数来处理页面跳转逻辑
4. 注意：URL 跳转模式已废弃，不再支持直接传入 URL 字符串作为 `selectByPage` 的值
5. 在只读模式下，下拉箭头图标将被隐藏，且无法触发选择操作 

 _cursor.ai/forms.doc/switch.doc/CSwitch.doc.md

New file
@@ -0,0 +1,65 @@
# CSwitch 开关组件

## 功能说明

CSwitch 是一个开关组件，用于在表单中提供开关选择功能。组件基于 AtSwitch 封装，支持只读模式，并能显示必填和错误状态。

## 引用方式

```js
import { CSwitch } from '@components/forms/switch';
```

## 组件参数

- `itemRes` (Object，必填)：表单数据资源对象，表单组件内部机制专用
- `readOnly` (Boolean，可选)：只读模式，默认为 false

## 使用示例

### 基础用法

```html
<template>
  <CForm :form="form">
    <CFormItem name="notification" label="接收通知">
      <CSwitch />
    </CFormItem>
  </CForm>
</template>

<script>
import { CForm, CFormItem } from '@components/forms/form';
import { CSwitch } from '@components/forms/switch';

export default {
  components: {
    CForm,
    CFormItem,
    CSwitch
  },
  data() {
    return {
      form: {
        notification: false
      }
    };
  }
};
</script>
```

### 只读模式

```html
<CFormItem name="notification" label="接收通知">
  <CSwitch :readOnly="true" />
</CFormItem>
```

## 注意事项

1. CSwitch 组件的值为布尔类型，表示开关的开启或关闭状态
2. 组件会根据表单项的 required 和 error 属性自动添加相应的样式
3. 在只读模式下，开关将被禁用，无法切换状态
4. 组件会自动将开关的状态同步到表单数据中 

 _cursor.ai/forms.doc/switch.doc/CSwitchRadio.doc.md

New file
@@ -0,0 +1,84 @@
# CSwitchRadio 开关式单选组件

## 功能说明

CSwitchRadio 是一个开关式单选组件，用于在表单中提供是/否选择功能。组件基于 AtSwitch 封装，提供了两个选项（是/否）供用户选择，并支持自定义选项文本和对齐方式。

## 引用方式

```js
import { CSwitchRadio } from '@components/forms/switch';
```

## 组件参数

- `itemRes` (Object，必填)：表单数据资源对象，表单组件内部机制专用
- `checkAlign` (String，可选)：选项对齐方式，可选值有 left、right，默认为 right
- `checkedLabel` (String，可选)：选中选项的文本，默认为"是"
- `uncheckedLabel` (String，可选)：未选中选项的文本，默认为"否"

## 使用示例

### 基础用法

```html
<template>
  <CForm :form="form">
    <CFormItem name="isAdult" label="是否成年">
      <CSwitchRadio />
    </CFormItem>
  </CForm>
</template>

<script>
import { CForm, CFormItem } from '@components/forms/form';
import { CSwitchRadio } from '@components/forms/switch';

export default {
  components: {
    CForm,
    CFormItem,
    CSwitchRadio
  },
  data() {
    return {
      form: {
        isAdult: null
      }
    };
  }
};
</script>
```

### 自定义选项文本

```html
<CFormItem name="hasExperience" label="是否有经验">
  <CSwitchRadio 
    checkedLabel="有" 
    uncheckedLabel="无" 
  />
</CFormItem>
```

### 左对齐选项

```html
<CFormItem name="isMarried" label="婚姻状况">
  <CSwitchRadio 
    checkAlign="left" 
    checkedLabel="已婚" 
    uncheckedLabel="未婚" 
  />
</CFormItem>
```

## 注意事项

1. CSwitchRadio 组件的值为布尔类型，表示选中的是第一个选项（true）还是第二个选项（false）
2. 组件会根据表单项的 required 和 error 属性自动添加相应的样式
3. 选项对齐方式（checkAlign）决定了选项图标的显示位置：
   - `right`：选项图标显示在文本右侧
   - `left`：选项图标显示在文本左侧
4. 组件默认提供"是/否"两个选项，可以通过 checkedLabel 和 uncheckedLabel 属性自定义选项文本 

 _cursor.ai/forms.doc/textarea.doc/CTextArea.doc.md

New file
@@ -0,0 +1,83 @@
# CTextArea 多行文本输入组件

## 功能说明

CTextArea 是一个多行文本输入组件，用于在表单中收集用户的多行文本输入。组件支持设置输入区域高度，可以通过行数或像素值来控制，并支持只读模式。

## 引用方式

```js
import { CTextArea } from '@components/forms/textarea';
```

## 组件参数

- `itemRes` (Object，必填)：表单数据资源对象，表单组件内部机制专用
- `height` (Number，可选)：文本域输入区域高度，单位为像素，默认为 94
- `rows` (Number，可选)：文本域输入区行数，设置后会覆盖 height 参数
- `readOnly` (Boolean，可选)：只读模式，默认为 false
- `placeholder` (String，可选)：输入框占位提示文本

## 使用示例

### 基础用法

```html
<template>
  <CForm :form="form">
    <CFormItem name="description" label="描述">
      <CTextArea placeholder="请输入描述内容" />
    </CFormItem>
  </CForm>
</template>

<script>
import { CForm, CFormItem } from '@components/forms/form';
import { CTextArea } from '@components/forms/textarea';

export default {
  components: {
    CForm,
    CFormItem,
    CTextArea
  },
  data() {
    return {
      form: {
        description: ''
      }
    };
  }
};
</script>
```

### 设置输入区域高度

```html
<!-- 通过像素值设置高度 -->
<CFormItem name="content" label="内容">
  <CTextArea :height="150" placeholder="请输入内容" />
</CFormItem>

<!-- 通过行数设置高度 -->
<CFormItem name="remark" label="备注">
  <CTextArea :rows="5" placeholder="请输入备注" />
</CFormItem>
```

### 只读模式

```html
<CFormItem name="description" label="描述">
  <CTextArea :readOnly="true" />
</CFormItem>
```

## 注意事项

1. CTextArea 组件通常需要配合 CForm 和 CFormItem 组件一起使用
2. 当同时设置 `height` 和 `rows` 参数时，`rows` 参数优先生效
3. `rows` 参数会按照每行 40px 的高度计算输入区域的总高度
4. 组件支持自动增高，当输入内容超过设定高度时，输入区域会自动增高
5. 在只读模式下，输入区域将不可编辑 

 _cursor.ai/forms.doc/userSignature.doc/CUserSignature.doc.md

New file
@@ -0,0 +1,84 @@
# CUserSignature 用户签名组件

## 功能说明

CUserSignature 是一个用户手写签名组件，用于在表单中收集用户的电子签名。组件提供了手写板功能，支持签名的绘制、清除和保存，适用于电子合同、协议等需要用户签名的场景。

## 引用方式

```js
import { CUserSignature } from '@components/forms/userSignature';
```

## 组件参数

- `itemRes` (Object，必填)：表单数据资源对象，表单组件内部机制专用
- `width` (Number，可选)：签名板宽度，单位为 px，默认为容器宽度
- `height` (Number，可选)：签名板高度，单位为 px，默认为 200
- `lineWidth` (Number，可选)：签名线条宽度，默认为 3
- `lineColor` (String，可选)：签名线条颜色，默认为 '#000000'
- `background` (String，可选)：签名板背景色，默认为 '#ffffff'
- `placeholder` (String，可选)：签名板占位提示文本
- `readOnly` (Boolean，可选)：只读模式，默认为 false

## 使用示例

### 基础用法

```html
<template>
  <CForm :form="form">
    <CFormItem name="signature" label="签名">
      <CUserSignature 
        placeholder="请在此处签名" 
      />
    </CFormItem>
  </CForm>
</template>

<script>
import { CForm, CFormItem } from '@components/forms/form';
import { CUserSignature } from '@components/forms/userSignature';

export default {
  components: {
    CForm,
    CFormItem,
    CUserSignature
  },
  data() {
    return {
      form: {
        signature: ''
      }
    };
  }
};
</script>
```

### 自定义配置

```html
<CFormItem name="contractSign" label="合同签名">
  <CUserSignature 
    :width="300"
    :height="150"
    :lineWidth="4"
    lineColor="#1a1a1a"
    background="#f5f5f5"
    placeholder="请在此处签署您的姓名" 
  />
</CFormItem>
```

## 注意事项

1. 组件会将签名转换为 base64 格式的图片数据存储在表单中
2. 签名板提供以下功能按钮：
   - 清除：清除当前签名
   - 确认：保存当前签名
3. 建议根据实际使用场景设置合适的签名板尺寸
4. 在移动端使用时，支持触摸书写
5. 在只读模式下，只能查看已保存的签名，无法进行签名操作
6. 为了保证签名的清晰度，建议使用适当的 `lineWidth` 值