cunkebao_v3/nkebao/src/components/Upload/README.md

# Upload 上传组件

基于 antd-mobile 的 ImageUploader 组件封装的上传组件，支持图片上传、预览、删除等功能。

## 功能特性

- ✅ 支持单张/多张图片上传
- ✅ 文件类型和大小验证
- ✅ 上传进度显示
- ✅ 图片预览功能
- ✅ 删除确认
- ✅ 数量限制
- ✅ 编辑和新增状态支持
- ✅ 响应式设计
- ✅ 头像上传专用组件

## 组件列表

### 1. UploadComponent (图片上传)

通用的图片上传组件，支持多张图片上传。

### 2. AvatarUpload (头像上传)

专门的头像上传组件，支持圆形头像显示、删除功能。

### 3. VideoUpload (视频上传)

视频上传组件，支持视频文件上传和预览。

## 使用方法

### 基础用法

```tsx
import React, { useState } from "react";
import UploadComponent from "@/components/Upload";

const MyComponent = () => {
  const [images, setImages] = useState<string[]>([]);

  return (
    <UploadComponent
      value={images}
      onChange={setImages}
      count={5}
      accept="image/*"
    />
  );
};
```

### 头像上传

```tsx
import React, { useState } from "react";
import AvatarUpload from "@/components/Upload/AvatarUpload";

const AvatarComponent = () => {
  const [avatar, setAvatar] = useState<string>("");

  return (
    <AvatarUpload
      value={avatar}
      onChange={setAvatar}
      size={100}
      disabled={false}
    />
  );
};
```

### 编辑模式

```tsx
const EditComponent = () => {
  const [images, setImages] = useState<string[]>([
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg",
  ]);

  return (
    <UploadComponent
      value={images}
      onChange={setImages}
      count={9}
      disabled={false}
    />
  );
};
```

### 禁用状态

```tsx
<UploadComponent value={images} onChange={setImages} disabled={true} />
```

## API

### UploadComponent Props

| 参数      | 说明           | 类型                       | 默认值      |
| --------- | -------------- | -------------------------- | ----------- |
| value     | 图片URL数组    | `string[]`                 | `[]`        |
| onChange  | 图片变化回调   | `(urls: string[]) => void` | -           |
| count     | 最大上传数量   | `number`                   | `9`         |
| accept    | 接受的文件类型 | `string`                   | `"image/*"` |
| disabled  | 是否禁用       | `boolean`                  | `false`     |
| className | 自定义类名     | `string`                   | -           |

### AvatarUpload Props

| 参数      | 说明         | 类型                    | 默认值  |
| --------- | ------------ | ----------------------- | ------- |
| value     | 头像URL      | `string`                | `""`    |
| onChange  | 头像变化回调 | `(url: string) => void` | -       |
| disabled  | 是否禁用     | `boolean`               | `false` |
| className | 自定义类名   | `string`                | -       |
| size      | 头像尺寸     | `number`                | `100`   |

### VideoUpload Props

| 参数      | 说明         | 类型                    | 默认值  |
| --------- | ------------ | ----------------------- | ------- |
| value     | 视频URL      | `string`                | `""`    |
| onChange  | 视频变化回调 | `(url: string) => void` | -       |
| disabled  | 是否禁用     | `boolean`               | `false` |
| className | 自定义类名   | `string`                | -       |

### 事件

| 事件名   | 说明               | 回调参数                   |
| -------- | ------------------ | -------------------------- |
| onChange | 文件列表变化时触发 | `(urls: string[]) => void` |

## 注意事项

1. **文件大小限制**: 默认限制为 5MB
2. **文件类型**: 默认只接受图片文件
3. **上传接口**: 使用 `/v1/attachment/upload` 接口
4. **认证**: 自动携带 token 进行认证
5. **预览**: 点击图片可预览
6. **删除**: 删除图片会有确认提示
7. **头像组件**: 支持圆形显示、删除按钮、上传覆盖层

## 样式定制

组件支持通过 CSS 模块进行样式定制：

```scss
.uploadContainer {
  // 自定义样式
  :global {
    .adm-image-uploader {
      // 覆盖 antd-mobile 默认样式
    }
  }
}

.avatarUploadContainer {
  // 头像上传组件样式
  .avatarWrapper {
    // 头像容器样式
  }
}
```

## 错误处理

- 文件类型不匹配时会显示错误提示
- 文件大小超限时会显示错误提示
- 上传失败时会显示错误提示
- 网络错误时会显示错误提示

## 头像上传特性

- **圆形显示**: 头像以圆形方式显示
- **占位符**: 无头像时显示用户图标
- **上传覆盖**: 鼠标悬停显示上传图标
- **删除功能**: 右上角删除按钮
- **加载状态**: 上传时显示加载提示
- **尺寸可调**: 支持自定义头像尺寸