# file-chunk

**Repository Path**: totoro110/file-chunk

## Basic Information

- **Project Name**: file-chunk
- **Description**: file-chunk是一款针对大文件，超大文件上传的全方位解决方案，支持断点续传，持久化续传，全程状态监控，严格的请求队列模式，分片传输造成高并发的同时，又保障了数据传输的稳定性。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2021-10-22
- **Last Updated**: 2021-10-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# file-chunk一款专注于前端大文件的上传插件

## 序言

> file-chunk是一款针对大文件，超大文件上传的全方位解决方案，支持断点续传，持久化续传，全程状态监控，严格的请求队列模式，分片传输造成高并发的同时，又保障了数据传输的稳定性。

## 项目信息

- 原创作者：随风
- 开源协议：MIT
- 当前版本：v1.0.0
- 发布日期：2021-06-18
- 联系方式：yangrd_bbs@aliyun.com

## 主要功能

- 文件上传：常规文件上传，大文件上传（切片）
- 数据控制：切片数据可控，可以自由定制业务逻辑
- 生命周期：文件读取中/文件读取失败/文件读取完毕/切片上传中/切片上传完毕（数据整合）/上传失败
- 可控性：支持主动【暂停/继续】传输
- 持久化续传：文件读取完毕后，可以携带文件md5询问服务端是否有该文件的分片信息（上次未上传完毕的残留）。如果有文件残留，服务端将返回文件残留信息，file-chunk根据文件残留信息，重置当前文件上传进度，直接上传服务端内缺失的数据，以此达到持久话续传。注：基于nodejs服务端示例均在serve.js文件内。
- 小功能：直接唤起文件选择窗口（直接注入内存，不插入DOM），字节大小加工格式化，百分比信息加工（进度）。文件切片工具直接对任意File文件对象进行切片处理，返回一个分片容器。这些都是文件上传常用的小工具，均内置在了file-chunk。
- 进度信息：在文件读取中可以获取文件读取进度，在分片上传中可以获取分片上传信息/大小。
- 关于小文件兼容性：如果您使用了该插件，即使小文件也是兼容的，无需在写小文件的上传逻辑

## 注意

预备技能：file-chunk默认您已经有相应JavaScript基础，如果您需要参阅nodejs服务端的DEMO，可以查阅serve.js



## 开源协议

file-chunk插件基于MIT协议开放源代码，不包含任何商业盈利行为，故此本人不对file-chunk在任何时间造成的任何损失/后果负任何责任



## 生命周期

| 方法名称        | 参数                                                  | 功能           |
| --------------- | ----------------------------------------------------- | -------------- |
| onReadFileErr   | err                                                   | 文件读取失败   |
| onReadFile      | progress: number,进度信息                             | 文件读取中     |
| onReadFileEnd   | md5: string, next，执行该方法开始上传                 | 文件读取完毕   |
| onSingleChange  | { id: string, current: number }, data(服务端返回数据) | 单切片文件上传 |
| onAllChange     | 无                                                    | 上传完毕       |
| onFailureChange | 无                                                    | 上传失败       |

## 方法

| 方法名称         | 参数                                                 |
| ---------------- | ---------------------------------------------------- |
| formatSize       | 传入字节大小返回"BKB,MB,GB,TB,PB,EB,ZB,YB-单位       |
| formatPercentage | 传入分子，分母                                       |
| FilelShow        | 唤起文件选择框（input内存调用，不插入DOM）           |
| fileSlice        | 切片工具，可对File文件对象进行切片处理               |
| chunkSwitch      | 状态切换，正常状态下执行为暂停，暂停状态下执行为续传 |
| continue         | 续传                                                 |
| stop             | 暂停                                                 |



## 基础使用方法

```
$ npm install file-chunk
```

```
$ yarn add file-chunk
```

```javascript
import CloudChunk from 'file-chunk'

// 选择文件，返回一个选中的文件列表
const files = await CloudChunk.FilelShow()
/* 
创建CloudChunk实例（每个文件一个实例）
参数1:分片上传时的服务端接口
参数2:File文件对象
*/
 const chunk = new CloudChunk({
   url: `http://127.0.0.1:8001/transmission/chunk-upload`,
   file
 });
/* 
返回一个FormData实例对象，注入chunk作为单次切片的上传数据
这是默认的数据传输，如果您没有特殊业务定制，无需实现重新覆写该方法	
*/
chunk.formdata = (fileId, file, index) => {
  // 创建数据容器
  const formdata = new FormData();
  // 文件ID（随内存清空）
  formdata.append("fileId", fileId);
  // 文件切片下标
  formdata.append("index", index.toString());
  // 文件切片
  formdata.append("file", file);
  /* 将数据注入CloudChunk实例对象 */
  return formdata;
}
/* 
 文件读取中
 参数1:当前文件读取进度的百分比1-100
*/
chunk.onReadFile = (num) => {
  // num,当前文件读取进度的百分比1-100
}

/* 
 文件读取完毕
 参数1：fileId为读取出的文件md5码
 参数2：send执行上传，接受一个参数（当前文件进度，不传参数默认从0开始）
*/
chunk.onReadFileEnd = async (fileId, send) => {
  // 
  const { data } = await axios.post(
    `http://127.0.0.1:8001/transmission/chunk-read`,
    { fileId }
  );
  // 判断如果服务端有上次传输失败的文件信息，则注入上传方法中，作为当前进度
  if (data.sliceChunks.length > 0) {
    send(data.sliceChunks)
  } else {
    send()
  }

}

/* 
切片上传中
参数1:progress当前文件进度信息
参数2:单个切片和服务端完成交互返回的数据信息
*/
chunk.onSingleChange = (progress, data) => {
  
}


/* 
 切片上传完毕 
 一般到了这个钩子函数，说明整个流程基本结束了
 您可以在这个函数方法内，执行切片合并的逻辑，以此来完成流程闭环
 git内有详细的切片合并代码示例（前后端均有）
*/
chunk.onAllChange = async () => {}

/* 
 开始读取文件
 这个方法执行了，整个流程就开始了
*/
chunk.readFileSync()


```