npm package: @oceans/transfer
Description: big file transfer lib
Latest version: 1.3.3

# Transfer

用于文件上传下载

### 安装
使用 npm:
```javascript
$ npm install @oceans/transfer
```

### 如何使用
> 先将 dist 目录中的 md5-worker.{flag}.js 和 spark-md5.js 两个文件放到可以通过网络可以访问到的地方，静态服务器或CDN

#### 文件上传

#### 步骤 1 
```jsx harmony
// react
<input type="file" onCHange={(e) => { 
  const file = e.target.files[0]
  // todo... 继续下边的步骤   
}}/>
```

#### 步骤 2 
> 初始化 HttpClient(options) 

```javascript
import { HttpClient } from "@oceans/transfer"

const client = new HttpClient({
  file,
  uploadServer: 'https://xxx', 
  callbackURL: 'https://xxx', 
  getFilePath: 'https://xxx', 
})
```

#### 步骤 3
form表单上传，适用于小文件上传

```javascript
await client.formUpload()
```

大文件上传，将对文件进行分片上传（需要支持HTML5 File Api的浏览器）
```javascript
await client.start()
```

#### 文件下载
```
import { HttpClient } from "@oceans/transfer"
// downloadService 下载服务域名：https://xxx.xx.xx
// file 文件下载地址，可以传入获取文件地址接口，也可以是文件在服务器上的相对路径
HttpClient.download(downloadService, file)
```

### 接口参数说明
> 初始化时传入的参数为config对像
  
```javascript
const client = new HttpClient(config)
```

#### 1、上传
> form表单上传，适用于小文件上传
```
await client.formUpload()
```
> 大文件上传，将对文件进行分片上传，一般情况下不论大小，使用此方法就好。
```
await client.start()
```

#### 2、暂停或停止
```
await client.stop()
```

#### Config
```
{
  // 必须填写， 文件对象，像上面onChange之后可以取得一个文件对像
  file: '',

  // 必须填写，文件上传地址，写上服务器地址，如https://upload.xxx.com  
  uploadServer: '',

  // 必须填写，获取文件上传的地址，如果不是一个http链接，
  // 那么将使用服务器存放根路径加上此参数构成文件的绝对地址
  getFilePath: '',

  // 用户ID，传输任务会记录记录此ID，【可选】
  uId： '',

  // 文件上传下载过程会将进度信息发送到此接口
  callbackURL: '',
  
  // 可选，请求文件头，如果以【t-】开头，那么会将此参数传给 getFilePath, callbackURL
  // 这两个请求的请求头，并去掉【t-】
  headers: {
    't-xxx': 'xxxx' 
  },

  // 可选，可以将远程服务信息与传输服务信息进行绑定
  flag: '',

  // 可选，文件上传过程关闭了传输页，重新打开页面重传的时候，需要将传输服务的_id
  restoreId: '',
 
  // 可选，作用同上，可以传flag，此参数与restoreId两者传其一
  restoreFlag: '',
 
  // 必须填写，用于计算文件的MD5，此参数与文件重传有关，不正确配置将影响文件重传功能  
  md5Config: {
    // md5-worker.{flag}.js 文件的URL
    md5Worker: '',
 
    // spark-md5.js 文件的URL
    sparkMd5: '',

    // 可选，文件计算完md5值后回调
    onComplete: () => {  },

    // 文件md5计算方式，sample为局部计算方式，此方式计算速度很快，
    // all模式则计算整个文件，文件大时，会消耗很多时间，建议使用sample方式  
    type: 'sample'
  },

  // 可选，文件开始上传时回调
  onStart: (taskInfo) => {},

  // 可选，文件上传过程回调
  onProgress: (taskInfo) => {},

  // 可选，文件上传结束回调
  onComplete: (taskInfo) => {},

  // 可选，文件上传出错回调
  onError: (e, taskInfo) => {}  
}
```
#### 3、获取任务列表
```
import { HttpClient } from "@oceans/transfer"

const rs = await HttpClient.listTaskAPI({
  status: '', // 任务状态，【可选】
  uId: '', // 用户ID，【可选】
  limit: 30, // 返回数据数量，每页数据条数
  page: 1, // 页码
  uploadServer: '', // 必填，服务地址 
  headers: {} // 可选，请求文件头
})
```
文件状态：
```
const TASK_STATUS = {
    WAITING: '0', // 等待
    READY: '1', // 准备接收数据
    RUNNING: '2', // 数据传输中
    SUCCESS: '3', // 任务完成
    ABORT: '4', // 目前当成暂停使用
    FAIL: '1000',
  };
```
#### 4、删除任务
删除任务的同时也会将文件碎片删除
```
import { HttpClient } from "@oceans/transfer"

const rs = await HttpClient.deleteTaskAPI({
  id: '',
  uploadServer: '', // 必填，服务地址 
  headers: {} // 可选，请求文件头
})
```

#### 5、删除文件碎片
只有在任务停止的时候才可以对文件碎片进行删除，删除文件碎片的同时也会将任务信息删除
```
import { HttpClient } from "@oceans/transfer"

const rs = await HttpClient.clearChunkFile({
  id: '',
  uploadServer: '', // 必填，服务地址 
  headers: {} // 可选，请求文件头
})
```

#### 6、更新文件状态为停止
在上传过程中，如果页面刷新后上传实例丢失，需要重新上传，那么需要先将任务状态变更为停止后，再调用上传接口。
```
import { HttpClient } from "@oceans/transfer"

const rs = await HttpClient.stopTaskAPI({
  taskId: '', // 任务id
  flag: '', // 可选，如果任务ID不知道，可以使用此参数，作用见config配置参数说明
  headers: {}
  uploadServer: '', // 必填，服务地址 
  headers: {} // 可选，请求文件头
})
```