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

# Upload 组件

通用的文件上传组件，基于 Ant Design 的 Upload 组件封装。

## 组件列表

### UploadComponent

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

#### 使用方法

```tsx
import UploadComponent from '@/components/Upload';

// 基础用法
<UploadComponent
  value={imageUrls}
  onChange={setImageUrls}
  count={9}
  accept="image/*"
/>

// 单文件上传
<UploadComponent
  value={[singleImage]}
  onChange={(urls) => setSingleImage(urls[0])}
  count={1}
  listType="picture-card"
/>
```

#### Props

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

### VideoUpload

专门的视频上传组件，支持单文件上传。

#### 使用方法

```tsx
import VideoUpload from '@/components/Upload/VideoUpload';

<VideoUpload
  value={videoUrl}
  onChange={setVideoUrl}
  disabled={false}
/>
```

#### Props

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

## 技术实现

### 上传接口

- **接口地址**: `/v1/attachment/upload`
- **请求方式**: `POST`
- **请求格式**: `multipart/form-data`
- **文件字段名**: `file`

### 响应格式

组件会自动处理以下响应格式：

```json
{
  "code": 200,
  "data": "https://example.com/file.jpg",
  "message": "success"
}
```

或者：

```json
{
  "code": 200,
  "data": {
    "url": "https://example.com/file.jpg"
  },
  "message": "success"
}
```

### 文件限制

- **图片文件**: 最大 5MB
- **视频文件**: 最大 50MB
- **支持格式**: 根据 `accept` 属性设置

### 状态管理

组件内部管理以下状态：

- `uploading`: 文件上传中
- `done`: 文件上传完成
- `error`: 文件上传失败
- `removed`: 文件已删除

## 注意事项

1. **API 集成**: 组件使用 Ant Design Upload 的 `action` 属性，直接调用 `/v1/attachment/upload` 接口
2. **文件验证**: 在 `beforeUpload` 中进行文件类型和大小验证
3. **状态同步**: 组件会自动同步 `value` 和内部 `fileList` 状态
4. **错误处理**: 上传失败时会显示错误提示并自动清理失败的文件
5. **进度显示**: 上传过程中会显示加载状态和进度指示

## 样式定制

组件使用 SCSS Modules，可以通过修改 `index.module.scss` 文件来自定义样式：

```scss
.upload-container {
  // 容器样式
}

.upload-button {
  // 上传按钮样式
}

.upload-icon {
  // 图标样式
}

.upload-text {
  // 文字样式
}

.uploading {
  // 上传中状态样式
}
```