# file-chunk

**Repository Path**: font-size/file-chunk

## Basic Information

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

## Statistics

- **Stars**: 55
- **Forks**: 3
- **Created**: 2021-05-24
- **Last Updated**: 2025-03-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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

## 序言

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

## 项目信息

1. 原创作者：梦客
2. 开源协议：MIT
3. 发布日期：2021-06-18
4. 联系方式：yangrd@tom.com
5. 开源地址：https://github.com/yangrds/file-chunk
6. 演示地址：http://101.34.62.75:8007/

## 项目前后端代码示例（已闭环）

demo目录内有简单的前后端配套代码示例

**前端代码**：file-chunk的基本批量上传操作示例（文档内没有的可以查阅示例）

**后端代码**：配套file-chunk的服务端接口（基于nodejs）

**这里提供的服务端代码仅供参考，希望能帮到需要的朋友**，**API接口如下**：

文件读取，该接口向服务器查询上次未完成的任务，如果存在则返回已完成的切片信息，以便于前端直接继续上次的任务继续上传

`/transmission/chunk-read`

切片上传，该接口接收前端传递的FormData对象，根据fileId创建一个临时目录，然后将切片存储于该临时目录（切片合并为文件后，会删除该目录）

`/transmission/chunk-upload`

切片合并，该接口会根据fileid将临时目录内的所有切片文件，合并为一个新文件写入指定文件夹，最后将删除临时目录内的切片文件（如果分片上传失败，分片文件就不会被清理，下次上传就会做为文件的进度续传）

`/transmission/chunk-all`

**注：切片上传往往用于大文件，超大文件上传的业务场景，比传统的文件流直接上传要复杂很多，一些同学可能对这方面的业务逻辑理解起来不是那么透彻。如果需要帮助的话我们可以一起交流：yangrd@tom.com**

## 主要功能

**文件上传**：常规文件上传，大文件上传（切片）

**数据控制**：切片数据可控，可以自由定制业务逻辑

**生命周期**：文件读取中/文件读取失败/文件读取完毕/切片上传中/切片上传完毕（数据整合）/上传失败

**可控性**：支持主动【暂停/继续】传输

**持久化续传**：文件读取完毕后，可以携带文件md5询问服务端是否有该文件的分片信息（上次未上传完毕的残留）。如果有文件残留，服务端将返回文件残留信息，file-chunk根据文件残留信息，重置当前文件上传进度，直接上传服务端内缺失的数据，以此达到持久话续传。注：基于nodejs服务端示例均在serve.js文件内。

**小功能**：直接唤起文件选择窗口（直接注入内存，不插入DOM），字节大小加工格式化，百分比信息加工（进度）。文件切片工具直接对任意File文件对象进行切片处理，返回一个分片容器。这些都是文件上传常用的小工具，均内置在了file-chunk。

**进度信息**：在文件读取中可以获取文件读取进度，在分片上传中可以获取分片上传信息/大小。

**关于小文件兼容性**：如果您使用了该插件，即使小文件也是兼容的，无需在写小文件的上传逻辑

## 开源协议

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()


```