@sphinxvon/file-upload-component/README.md

一个支持分片上传、断点续传和批量上传的文件上传组件

# file-upload-component

一个功能强大的文件上传组件，支持分片上传、断点续传、批量上传和MD5校验，适用于大文件上传场景。组件核心逻辑与UI分离，可灵活适配不同的UI框架。

## 特性

- 支持分片上传，可配置分片大小
- 断点续传，支持暂停/继续上传
- 文件MD5校验，避免重复上传
- 批量上传功能
- 并发上传控制
- 实时上传进度显示
- 核心逻辑与UI分离，易于扩展和定制
- 基于Vue 3和Element Plus，也可适配其他UI框架
- 支持自定义上传API地址

## 安装

使用npm:

```bash
npm install @sphinxvon/file-upload-component --save
```

## 发布步骤

1. 确保代码已提交并推送至远程仓库
2. 更新package.json中的版本号
3. 运行构建命令:
   ```bash
   npm run build
   ```
4. 登录npm账户:
   ```bash
   npm login
   ```
5. 发布到npm:
   ```bash
   npm publish
   ```

## 组件使用说明

### 基础用法

```vue
<template>
  <FileUpload 
    :base-url="apiBaseUrl"
    @progress="handleProgress"
    @success="handleSuccess"
    @error="handleError"
  />
</template>

<script setup>
import { FileUpload } from '@sphinxvon/file-upload-component';

const apiBaseUrl = 'http://localhost:8080';

function handleProgress(progress) {
  console.log('上传进度:', progress);
}

function handleSuccess(data) {
  console.log('上传成功:', data);
}

function handleError(error) {
  console.log('上传出错:', error);
}
</script>
```

### 高级用法

```vue
<template>
  <FileUpload 
    :base-url="apiBaseUrl"
    :chunk-size="2"
    :concurrency="5"
    :max-file-size="100"
    :timeout="60"
    :tips="'请上传小于100MB的文件'"
    :drag="true"
    @progress="handleProgress"
    @success="handleSuccess"
    @error="handleError"
    @complete="handleComplete"
    @pause="handlePause"
    @resume="handleResume"
    @cancel="handleCancel"
  />
</template>

<script setup>
import { FileUpload } from '@sphinxvon/file-upload-component';

const apiBaseUrl = 'http://localhost:8080';

// 事件处理函数
function handleProgress(progress) {
  console.log('上传进度:', progress);
}

function handleSuccess(data) {
  console.log('上传成功:', data);
}

function handleError(error) {
  console.log('上传出错:', error);
}

function handleComplete(data) {
  console.log('上传完成:', data);
}

function handlePause(data) {
  console.log('上传暂停:', data);
}

function handleResume(data) {
  console.log('上传恢复:', data);
}

function handleCancel(data) {
  console.log('上传取消:', data);
}
</script>
```

### 仅使用核心上传逻辑

```javascript
import { FileUploader } from '@sphinxvon/file-upload-component';

// 创建上传器实例
const uploader = new FileUploader({
  baseUrl: 'http://localhost:8080',
  chunkSize: 5 * 1024 * 1024, // 5MB
  concurrency: 3
});

// 监听事件
uploader.on('progress', (progress) => {
  console.log('上传进度:', progress);
});

uploader.on('success', (data) => {
  console.log('上传成功:', data);
});

uploader.on('error', (error) => {
  console.log('上传出错:', error);
});

// 批量上传文件
const fileInput = document.getElementById('fileInput');
uploader.batchUpload(fileInput.files);
```

## 组件属性 (Props)

| 属性名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| baseUrl | String | 'http://localhost:8080' | API基础URL |
| chunkSize | Number | 5 | 分片大小(MB) |
| concurrency | Number | 3 | 并发上传数 |
| maxFileSize | Number | 100 | 最大文件大小(MB) |
| timeout | Number | 30 | 超时时间(秒) |
| tips | String | '请上传不超过100MB的文件' | 上传提示文案 |
| drag | Boolean | true | 是否启用拖拽上传 |

## 组件事件 (Events)

| 事件名 | 参数 | 说明 |
| --- | --- | --- |
| progress | Object | 上传进度信息 |
| success | Object | 上传成功回调 |
| error | Object | 上传出错回调 |
| complete | Object | 上传完成回调 |
| pause | Object | 上传暂停回调 |
| resume | Object | 上传恢复回调 |
| cancel | Object | 上传取消回调 |

## 核心上传器方法

### FileUploader 类

```javascript
import { FileUploader } from '@sphinxvon/file-upload-component';
```

#### 构造函数

```javascript
const uploader = new FileUploader(options);
```

**参数:**
- `options` {Object} - 配置选项
  - `baseUrl` {String} - API基础URL
  - `chunkSize` {Number} - 分片大小(字节)
  - `concurrency` {Number} - 并发上传数
  - `timeout` {Number} - 超时时间(毫秒)

#### 方法

| 方法名 | 参数 | 返回值 | 说明 |
| --- | --- | --- | --- |
| on(event, callback) | event {String}, callback {Function} | - | 设置事件回调 |
| addFile(file) | file {File} | String | 添加文件到上传队列 |
| startUpload(fileId) | fileId {String} | Promise | 开始上传文件 |
| pauseUpload(fileId) | fileId {String} | - | 暂停上传 |
| resumeUpload(fileId) | fileId {String} | - | 恢复上传 |
| cancelUpload(fileId) | fileId {String} | Promise | 取消上传 |
| batchUpload(files) | files {FileList\|Array<File>} | Array<String> | 批量上传文件 |
| getTaskProgress(fileId) | fileId {String} | Object | 获取任务进度信息 |
| getAllTaskProgress() | - | Array<Object> | 获取所有任务进度信息 |
| getOptions() | - | Object | 获取上传选项 |
| updateOptions(options) | options {Object} | - | 更新上传选项 |

## 后端 API 要求

组件需要后端提供以下API接口支持:

### 1. 初始化分片上传

**URL:** `/file/initMultipart`  
**方法:** `POST`  
**参数:**
- `fileId` {String} - 文件唯一标识
- `fileName` {String} - 文件名
- `fileSize` {Number} - 文件大小(字节)
- `contentType` {String} - 文件MIME类型
- `md5` {String} - 文件MD5值

**响应:**
```json
{
  "code": 200,
  "data": {
    "taskId": "任务ID",
    "totalChunks": 10, // 总分片数
    "uploadedChunks": 0 // 已上传分片数
  },
  "msg": "成功"
}
```

### 2. 上传分片

**URL:** `/file/uploadChunk`  
**方法:** `POST`  
**参数:**
- `taskId` {String} - 上传任务ID
- `chunkIndex` {Number} - 分片索引
- `file` {File} - 分片文件

**响应:**
```json
{
  "code": 200,
  "data": {},
  "msg": "成功"
}
```

### 3. 合并分片

**URL:** `/file/mergeChunks`  
**方法:** `POST`  
**参数:**
- `taskId` {String} - 上传任务ID
- `fileId` {String} - 文件唯一标识
- `fileName` {String} - 文件名
- `fileSize` {Number} - 文件大小(字节)
- `md5` {String} - 文件MD5值

**响应:**
```json
{
  "code": 200,
  "data": {
    "url": "文件访问地址"
  },
  "msg": "成功"
}
```

### 4. 获取上传进度

**URL:** `/file/progress`  
**方法:** `GET`  
**参数:**
- `fileId` {String} - 文件唯一标识

**响应:**
```json
{
  "code": 200,
  "data": {
    "uploadedChunks": 5,
    "totalChunks": 10
  },
  "msg": "成功"
}
```

### 5. 取消上传

**URL:** `/file/cancel`  
**方法:** `POST`  
**参数:**
- `taskId` {String} - 上传任务ID

**响应:**
```json
{
  "code": 200,
  "data": {},
  "msg": "成功"
}
```