更新所有表单组件文档和头注释

Tevin

2025-03-18 fdeb869c386da95150a087bc22bcebc4e57d0f76

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

@@ -2,7 +2,7 @@

## 功能说明

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

## 引用方式

@@ -13,12 +13,16 @@
## 组件参数

- `itemRes` (Object，必填)：表单数据资源对象，表单组件内部机制专用
- `maxCount` (Number，可选)：最大上传图片数量，默认为 9
- `maxSize` (Number，可选)：单张图片最大大小，单位为 MB，默认为 5
- `compress` (Boolean，可选)：是否压缩图片，默认为 true
- `quality` (Number，可选)：图片压缩质量，取值范围 0-1，默认为 0.8
- `placeholder` (String，可选)：选择器占位提示文本
- `readOnly` (Boolean，可选)：只读模式，默认为 false
- `count` (Number，可选)：最大图片张数，默认为 1
- `sourceType` (Array，可选)：图片来源，默认为 ['album', 'camera']
  - `album`：从相册选择
  - `camera`：使用相机
- `params` (Object，可选)：上传图片的附加参数，默认为空对象
- `needThumb` (Boolean，可选)：是否开启缩略图，默认为 false

## 实例方法

- `$uploadImage(callback)`：上传图片到服务器，参数为回调函数，回调函数接收两个参数：状态和结果

## 使用示例

@@ -29,7 +33,7 @@
  <CForm :form="form">
    <CFormItem name="photos" label="图片上传">
      <CImagePicker 
        :maxCount="3" 
        :count="3" 
        placeholder="请上传图片" 
      />
    </CFormItem>
@@ -57,24 +61,58 @@
</script>
```

### 自定义配置
### 限制图片来源

```html
<CFormItem name="certificate" label="证书照片">
<CFormItem name="idCard" label="身份证照片">
  <CImagePicker 
    :maxCount="1" 
    :maxSize="2" 
    :compress="true" 
    :quality="0.6" 
    placeholder="请上传证书照片" 
    :count="1" 
    :sourceType="['camera']" 
    placeholder="请拍摄身份证照片" 
  />
</CFormItem>
```

### 使用上传方法

```html
<template>
  <CForm :form="form">
    <CFormItem name="certificate" label="证书照片">
      <CImagePicker 
        ref="imagePicker"
        :count="1" 
        :params="{type: 'certificate'}" 
        :needThumb="true"
        placeholder="请上传证书照片" 
      />
    </CFormItem>
    <button @tap="evt => handleUpload()">上传图片</button>
  </CForm>
</template>

<script>
export default {
  // ...
  methods: {
    handleUpload() {
      this.$refs.imagePicker.$uploadImage((state, result) => {
        if (state === 'success') {
          console.log('上传成功', result);
        } else {
          console.error('上传失败', result);
        }
      });
    }
  }
};
</script>
```

## 注意事项

1. 组件会自动处理图片上传，支持压缩和预览功能
2. 上传的图片会被转换为 base64 格式存储在表单数据中
3. 当设置 `maxCount` 为 1 时，组件会以单图模式运行
4. 建议根据实际需求设置合适的 `maxSize` 和压缩参数
5. 在只读模式下，只能查看已上传的图片，无法进行上传和删除操作 
1. 组件会自动过滤不支持的图片格式，只允许上传 gif、png、jpg、jpeg 格式的图片
2. 图片大小超过 1MB 的会自动进行压缩处理
3. 通过 `$uploadImage` 方法可以将图片上传到服务器，上传成功后会自动更新表单值
4. 如果设置了 `needThumb` 为 true，上传时会同时生成缩略图
5. 组件内部集成了图片预览功能，点击已上传的图片可以放大查看