# 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 (
Upload Progress: {progress.toFixed(2)}%
Upload Speed: {speed}
); }; 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 (
Upload Progress: {progress.toFixed(2)}%
Upload Speed: {speed}
); }; export default FileUpload; ```