From c27e413f71c4beb1318237fedf585770702fe3a4 Mon Sep 17 00:00:00 2001
From: Tevin <tingquanren@163.com>
Date: Thu, 13 Mar 2025 10:13:57 +0800
Subject: [PATCH] 知识库文档，添加表单组件文档
---
_cursor.ai/forms.doc/numberValve.doc/CNumberValve.doc.md | 79 ++
_cursor.ai/forms.doc/switch.doc/CSwitch.doc.md | 65 ++
_cursor.ai/forms.doc/imagePicker.doc/CImagePicker.doc.md | 80 ++
_cursor.ai/forms.doc/input.doc/CInput.doc.md | 76 ++
_cursor.ai/forms.doc/form.doc/CForm.doc.md | 142 ++++
_cursor.ai/forms.doc/form.doc/CFormItem.doc.md | 100 +++
_cursor.ai/forms.doc/textarea.doc/CTextArea.doc.md | 83 ++
_cursor.ai/forms.doc/input.doc/CInputScanCode.doc.md | 126 +++
_cursor.ai/forms.doc/form.doc/CFormSubmit.doc.md | 77 ++
_cursor.ai/forms.doc/select.doc/CJumpSelect.doc.md | 105 +++
_cursor.ai/forms.doc/userSignature.doc/CUserSignature.doc.md | 84 ++
_cursor.ai/forms.doc/checkbox.doc/CCheckBox.doc.md | 132 ++++
_cursor.ai/forms.doc/numberStep.doc/CNumberStep.doc.md | 94 ++
_cursor.ai/forms.doc/switch.doc/CSwitchRadio.doc.md | 84 ++
_cursor.ai/forms.doc/datePicker.doc/CDatePicker.doc.md | 112 +++
_cursor.ai/forms.doc/select.doc/CSelect.doc.md | 132 ++++
_cursor.ai/forms.doc/form.doc/CFormAgreement.doc.md | 88 ++
_cursor.ai/forms.doc/chinaArea.doc/CChinaArea.doc.md | 89 ++
_cursor.ai/forms.doc/input.doc/CInputExpressCode.doc.md | 58 +
_cursor.ai/forms.doc/input.doc/CInputPhoneCode.doc.md | 109 +++
20 files changed, 1,915 insertions(+), 0 deletions(-)
diff --git a/_cursor.ai/forms.doc/checkbox.doc/CCheckBox.doc.md b/_cursor.ai/forms.doc/checkbox.doc/CCheckBox.doc.md
new file mode 100644
index 0000000..1998ff2
--- /dev/null
+++ b/_cursor.ai/forms.doc/checkbox.doc/CCheckBox.doc.md
@@ -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. 组件会自动根据表单值显示已选项的文本，多个选项时用逗号分隔
\ No newline at end of file
diff --git a/_cursor.ai/forms.doc/chinaArea.doc/CChinaArea.doc.md b/_cursor.ai/forms.doc/chinaArea.doc/CChinaArea.doc.md
new file mode 100644
index 0000000..335fe08
--- /dev/null
+++ b/_cursor.ai/forms.doc/chinaArea.doc/CChinaArea.doc.md
@@ -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` 分隔
\ No newline at end of file
diff --git a/_cursor.ai/forms.doc/datePicker.doc/CDatePicker.doc.md b/_cursor.ai/forms.doc/datePicker.doc/CDatePicker.doc.md
new file mode 100644
index 0000000..2e6991d
--- /dev/null
+++ b/_cursor.ai/forms.doc/datePicker.doc/CDatePicker.doc.md
@@ -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. 在只读模式下，日期选择器将不可操作
\ No newline at end of file
diff --git a/_cursor.ai/forms.doc/form.doc/CForm.doc.md b/_cursor.ai/forms.doc/form.doc/CForm.doc.md
new file mode 100644
index 0000000..3280a71
--- /dev/null
+++ b/_cursor.ai/forms.doc/form.doc/CForm.doc.md
@@ -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. 可以通过实例方法手动控制表单的提交、验证和错误设置
\ No newline at end of file
diff --git a/_cursor.ai/forms.doc/form.doc/CFormAgreement.doc.md b/_cursor.ai/forms.doc/form.doc/CFormAgreement.doc.md
new file mode 100644
index 0000000..d5164dd
--- /dev/null
+++ b/_cursor.ai/forms.doc/form.doc/CFormAgreement.doc.md
@@ -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 组件实例中获取
\ No newline at end of file
diff --git a/_cursor.ai/forms.doc/form.doc/CFormItem.doc.md b/_cursor.ai/forms.doc/form.doc/CFormItem.doc.md
new file mode 100644
index 0000000..0fbb509
--- /dev/null
+++ b/_cursor.ai/forms.doc/form.doc/CFormItem.doc.md
@@ -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 秒后自动清除
\ No newline at end of file
diff --git a/_cursor.ai/forms.doc/form.doc/CFormSubmit.doc.md b/_cursor.ai/forms.doc/form.doc/CFormSubmit.doc.md
new file mode 100644
index 0000000..57dfc2a
--- /dev/null
+++ b/_cursor.ai/forms.doc/form.doc/CFormSubmit.doc.md
@@ -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. 可以通过默认插槽自定义按钮的文本内容，默认显示"提交"
\ No newline at end of file
diff --git a/_cursor.ai/forms.doc/imagePicker.doc/CImagePicker.doc.md b/_cursor.ai/forms.doc/imagePicker.doc/CImagePicker.doc.md
new file mode 100644
index 0000000..4af8934
--- /dev/null
+++ b/_cursor.ai/forms.doc/imagePicker.doc/CImagePicker.doc.md
@@ -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. 在只读模式下，只能查看已上传的图片，无法进行上传和删除操作
\ No newline at end of file
diff --git a/_cursor.ai/forms.doc/input.doc/CInput.doc.md b/_cursor.ai/forms.doc/input.doc/CInput.doc.md
new file mode 100644
index 0000000..a6c1dae
--- /dev/null
+++ b/_cursor.ai/forms.doc/input.doc/CInput.doc.md
@@ -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. 在只读模式下，输入框将不可编辑
\ No newline at end of file
diff --git a/_cursor.ai/forms.doc/input.doc/CInputExpressCode.doc.md b/_cursor.ai/forms.doc/input.doc/CInputExpressCode.doc.md
new file mode 100644
index 0000000..525889a
--- /dev/null
+++ b/_cursor.ai/forms.doc/input.doc/CInputExpressCode.doc.md
@@ -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. 此组件主要针对快递单号的输入场景进行了优化，适用于物流、快递相关的业务场景
\ No newline at end of file
diff --git a/_cursor.ai/forms.doc/input.doc/CInputPhoneCode.doc.md b/_cursor.ai/forms.doc/input.doc/CInputPhoneCode.doc.md
new file mode 100644
index 0000000..d7443a4
--- /dev/null
+++ b/_cursor.ai/forms.doc/input.doc/CInputPhoneCode.doc.md
@@ -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` 方法手动重置按钮状态，适用于特殊情况下需要提前结束倒计时的场景
\ No newline at end of file
diff --git a/_cursor.ai/forms.doc/input.doc/CInputScanCode.doc.md b/_cursor.ai/forms.doc/input.doc/CInputScanCode.doc.md
new file mode 100644
index 0000000..b77880a
--- /dev/null
+++ b/_cursor.ai/forms.doc/input.doc/CInputScanCode.doc.md
@@ -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. 使用此组件时，需要确保应用有相应的扫码权限
\ No newline at end of file
diff --git a/_cursor.ai/forms.doc/numberStep.doc/CNumberStep.doc.md b/_cursor.ai/forms.doc/numberStep.doc/CNumberStep.doc.md
new file mode 100644
index 0000000..3ef361c
--- /dev/null
+++ b/_cursor.ai/forms.doc/numberStep.doc/CNumberStep.doc.md
@@ -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. 当输入框为空时，点击步进按钮会将值设置为最小值
\ No newline at end of file
diff --git a/_cursor.ai/forms.doc/numberValve.doc/CNumberValve.doc.md b/_cursor.ai/forms.doc/numberValve.doc/CNumberValve.doc.md
new file mode 100644
index 0000000..347c69f
--- /dev/null
+++ b/_cursor.ai/forms.doc/numberValve.doc/CNumberValve.doc.md
@@ -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. 组件会自动限制数值在设定的范围内
diff --git a/_cursor.ai/forms.doc/select.doc/CJumpSelect.doc.md b/_cursor.ai/forms.doc/select.doc/CJumpSelect.doc.md
new file mode 100644
index 0000000..650b188
--- /dev/null
+++ b/_cursor.ai/forms.doc/select.doc/CJumpSelect.doc.md
@@ -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. 在只读模式下，下拉箭头图标将被隐藏，且无法触发选择操作
\ No newline at end of file
diff --git a/_cursor.ai/forms.doc/select.doc/CSelect.doc.md b/_cursor.ai/forms.doc/select.doc/CSelect.doc.md
new file mode 100644
index 0000000..42ab6cf
--- /dev/null
+++ b/_cursor.ai/forms.doc/select.doc/CSelect.doc.md
@@ -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. 在只读模式下，下拉箭头图标将被隐藏，且无法触发选择操作
\ No newline at end of file
diff --git a/_cursor.ai/forms.doc/switch.doc/CSwitch.doc.md b/_cursor.ai/forms.doc/switch.doc/CSwitch.doc.md
new file mode 100644
index 0000000..40f70ca
--- /dev/null
+++ b/_cursor.ai/forms.doc/switch.doc/CSwitch.doc.md
@@ -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. 组件会自动将开关的状态同步到表单数据中
\ No newline at end of file
diff --git a/_cursor.ai/forms.doc/switch.doc/CSwitchRadio.doc.md b/_cursor.ai/forms.doc/switch.doc/CSwitchRadio.doc.md
new file mode 100644
index 0000000..d464bc9
--- /dev/null
+++ b/_cursor.ai/forms.doc/switch.doc/CSwitchRadio.doc.md
@@ -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 属性自定义选项文本
\ No newline at end of file
diff --git a/_cursor.ai/forms.doc/textarea.doc/CTextArea.doc.md b/_cursor.ai/forms.doc/textarea.doc/CTextArea.doc.md
new file mode 100644
index 0000000..1a8bae5
--- /dev/null
+++ b/_cursor.ai/forms.doc/textarea.doc/CTextArea.doc.md
@@ -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. 在只读模式下，输入区域将不可编辑
\ No newline at end of file
diff --git a/_cursor.ai/forms.doc/userSignature.doc/CUserSignature.doc.md b/_cursor.ai/forms.doc/userSignature.doc/CUserSignature.doc.md
new file mode 100644
index 0000000..dcbd677
--- /dev/null
+++ b/_cursor.ai/forms.doc/userSignature.doc/CUserSignature.doc.md
@@ -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` 值
\ No newline at end of file
--
Gitblit v1.9.1