# enlarge-file-upload
**Repository Path**: zychhf/enlarge-file-upload
## Basic Information
- **Project Name**: enlarge-file-upload
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-05
- **Last Updated**: 2025-06-05
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# File Upload Tool
**如果你是中文母语者,请前往https://www.npmjs.com/package/enlarge-file-upload?activeTab=readme 阅读文档
**
**请优先下载最新版本库**
这是一个用于大文件上传的工具包,提供了系列函数用来支持暂停、恢复、上传进度等功能,内置了错误重传策略,支持断点续传、重传、重试等功能(此库上传基于 axios 库,如果项目不支持 axios,勿用...)
## 安装
```sh
npm install enlarge-file-upload
```
## 参数介绍
```js
/**
* descript 入参详解
* @param {Number} chunkSize? 文件单个切片大小,默认5MB
* @param {Number} concurrency? 并发上传数量,默认5
* @param {Number} maxRetries? 失败重试次数,默认3
* @param {Number} startOffset? 断点续传偏移量,默认0
* @param {Array} includeChunks? 需要上传的切片索引,默认上传所有切片
* 如果startOffset和includeChunks参数同时存在,且startOffset不为0,默认优先使用startOffset参数
* @param {Boolen} hash? 是否开启hash计算(总文件hash值),默认不开启,可选参数
* @param {Boolen} awaitHash? 是否等待hash值,默认等待,可选参数(仅在hash为true时生效)
* awaitHash参数,如果上传文件较小时可以开启等待;如果文件超大,建议关闭,大文件hash值计算时间较长,避免等待阻塞主线程
* @param {Boolen | Object} chunkMap? 所有文件切片hash计算,返回为一个Map结构,默认不开启,可选参数
* @param {Function} uploadFunction 上传函数,必传参数
* @param {Function} onProgress? 上传进度回调函数,可选
* @param {Function} onSpeed? 上传速度回调函数,可选
* @param {Function} onSuccess? 上传成功后回调函数,可选
* @param {Function} beginHash? 开始计算Hash值回调函数,可选(只会在上传前调用一次,且hash.open必须true)
* @param {Function} endHash? Hash值计算完毕回调函数,可选(只会在上传前调用一次,且hash.open必须true)
*/
// Parameter example
const config = {
chunkSize: 5 * 1024 * 1024,
concurrency: 5,
maxRetries: 3,
startOffset: 0,
includeChunks,
hash: false,
awaitHash: false,
uploadFunction,
onProgress,
onSuccess,
onSpeed,
beginHash,
endHash,
};
/**
* descript fileUploadTool方法返回一个对象,包含上传方法、暂停方法、继续方法等
* upload 上传方法
* pause 暂停方法
* resume 继续方法
* state 状态对象,包含上传进度、hash值、上传速度等(具体请看对应的TS属性State)
*/
// Method call
const { upload, pause, resume, state } = fileUploadTool(config);
```
## 案例
### 原生 js 中使用示例
```html
File Upload
Upload Progress: 0%
Upload Speed: 0 MB/s
```
### 在 vue2 中使用
```vue
```
### 在 vue3 中使用
```vue
```
### React 中使用示例
**在 react 中,这里的 useMemo 是必须要使用的,避免组件渲染的时候,重新创建 uploader 对象**
```tsx
import React, { useState, useMemo } from 'react';
import createUploader from 'enlarge-file-upload';
import axios from 'axios';
const FileUpload = () => {
const [progress, setProgress] = useState(0);
const [speed, setSpeed] = useState('0 MB/s');
// Define the upload function
async function uploadFunction({ chunk, index, hash, cancelToken }) {
const formData = new FormData();
formData.append('chunk', chunk);
formData.append('hash', hash);
formData.append('index', index);
await axios.post('http://localhost:3000/api/users', formData, {
cancelToken,
});
}
const uploaderConfig = useMemo(
() => ({
chunkSize: 5 * 1024 * 1024, // 5MB
concurrency: 5,
maxRetries: 3,
// startOffset: 6, // Start upload from chunk index 6
// includeChunks:[1,6], // Only upload chunks with index 1 and 6, effective only if startOffset is 0 or empty
uploadFunction,
onProgress: progress => {
setProgress(progress);
},
onSuccess: () => {
console.log('Upload complete');
},
onSpeed: speed => {
setSpeed(speed);
},
}),
[]
);
const uploader = useMemo(
() => createUploader(uploaderConfig),
[uploaderConfig]
);
const handleFileChange = event => {
const file = event.target.files[0];
uploader?.upload(file);
};
const handlePause = () => {
uploader?.pause();
};
const handleResume = () => {
uploader?.resume();
};
return (
);
};
export default FileUpload;
```
### 封装为 react Hooks
**一个简单的封装,如有特殊需求,可以基于这个 hooks 进行二次修改**
```tsx
import { useState, useMemo, useCallback } from 'react';
import createUploader from 'enlarge-file-upload';
import axios from 'axios';
const useFileUploader = () => {
const [progress, setProgress] = useState(0);
const [speed, setSpeed] = useState('0 MB/s');
const uploadFunction = useCallback(
async ({ chunk, index, hash, cancelToken }) => {
const formData = new FormData();
formData.append('chunk', chunk);
formData.append('hash', hash);
formData.append('index', index);
await axios.post('http://localhost:3000/api/users', formData, {
cancelToken,
});
},
[]
);
const uploaderConfig = useMemo(
() => ({
chunkSize: 5 * 1024 * 1024, // 5MB
concurrency: 5,
maxRetries: 3,
// startOffset: 6, // Start upload from chunk index 6
// includeChunks:[1,6], // Only upload chunks with index 1 and 6, effective only if startOffset is 0 or empty
uploadFunction,
onProgress: progress => {
setProgress(progress);
},
onSuccess: () => {
console.log('Upload complete');
},
onSpeed: speed => {
setSpeed(speed);
},
}),
[uploadFunction]
);
const uploader = useMemo(
() => createUploader(uploaderConfig),
[uploaderConfig]
);
const uploadFile = useCallback(
file => {
uploader?.upload(file);
},
[uploader]
);
const pauseUpload = useCallback(() => {
uploader?.pause();
}, [uploader]);
const resumeUpload = useCallback(() => {
uploader?.resume();
}, [uploader]);
return {
progress,
speed,
uploadFile,
pauseUpload,
resumeUpload,
};
};
export default useFileUploader;
```
#### 使用封装好的 Hooks 示例
```tsx
import React from 'react';
import useFileUploader from './useFileUploader.tsx';
const FileUpload = () => {
const { progress, speed, uploadFile, pauseUpload, resumeUpload } =
useFileUploader();
const handleFileChange = event => {
const file = event.target.files[0];
uploadFile(file);
};
return (
);
};
export default FileUpload;
```