React Progress Uploader

🌍 语言: 🇨🇳 简体中文 • 🇺🇸 English

一个功能完整、高度可定制的 React 文件上传组件库。

📚 查看在线演示和文档

✨ 核心特性

• 🚀 多种上传模式：支持即时上传（Instant）、模态框上传（Modal）和拖拽区域上传（Area）。
• 🎨 高度可定制：轻松自定义颜色、图标、尺寸和主题（支持 6 种预设主题）。
• 📱 完美适配移动端：针对触摸目标、字体大小和安全区域进行了深度优化。
• 🔍 类型安全：基于 TypeScript 构建，提供完整的类型提示。
• 📦 轻量高效：实时进度跟踪，支持并发控制和上传取消。

📦 安装

npm install react-progress-uploader axios

🚀 快速开始

基础用法 (模态框模式)

import { ModalUploadButton } from "react-progress-uploader";

// 你的上传逻辑
const uploadFn = async ({ file, onProgress, signal }) => {
  // 调用 API 并通过 onProgress 更新进度...
  return { success: true, data: { url: '...' } };
};

function App() {
  return (
    <ModalUploadButton
      uploadFunction={uploadFn}
      acceptedFileTypes={[".jpg", ".png"]}
      onUploadComplete={(files) => console.log("上传成功:", files)}
    >
      选择文件上传
    </ModalUploadButton>
  );
}

即时上传 (带浮动进度卡片)

import { InstantUploadButton } from "react-progress-uploader";

function App() {
  return (
    <InstantUploadButton
      uploadFunction={uploadFn}
      floatingCardTheme="blue"
    >
      即时上传
    </InstantUploadButton>
  );
}

结合 Axios 使用 (完整封装示例)

这是一个完整的业务组件封装示例，包含了单/多文件切换、进度处理以及取消功能：

import React from 'react';
import axios from 'axios';
import { ModalUploadButton, InstantUploadButton } from "react-progress-uploader";

// 1. 封装通用的 Axios 上传逻辑
const axiosUpload = async ({ file, onProgress, signal }) => {
  try {
    const formData = new FormData();
    formData.append('file', file);

    const response = await axios.post('/api/upload', formData, {
      signal, // 传递信号以支持中途取消
      onUploadProgress: (progressEvent) => {
        if (progressEvent.total) {
          const percent = Math.round((progressEvent.loaded * 100) / progressEvent.total);
          onProgress(percent); // 反馈给组件 UI
        }
      },
    });

    return { success: true, data: response.data };
  } catch (error) {
    return {
      success: false,
      error: axios.isCancel(error) ? '已取消上传' : (error.message || '上传失败')
    };
  }
};

// 2. 业务组件：头像上传 (单文件 + 严格限制)
export const AvatarUploader = () => (
  <ModalUploadButton
    uploadFunction={axiosUpload}
    multiple={false}
    acceptedFileTypes={[".jpg", ".png"]}
    maxFileSize={1 * 1024 * 1024} // 1MB
    onUploadComplete={(files) => console.log("头像已上传:", files[0])}
  >
    更改头像
  </ModalUploadButton>
);

// 3. 业务组件：批量文档上传 (并发控制 + 浮动进度)
export const DocumentUploader = () => (
  <InstantUploadButton
    uploadFunction={axiosUpload}
    multiple={true}
    maxFiles={10}
    maxConcurrent={3} // 同时最多 3 个上传任务
    acceptedFileTypes={[".pdf", ".doc", ".docx"]}
    floatingCardTheme="blue"
    onUploadComplete={(files) => alert(`成功上传 ${files.length} 个文件`)}
  >
    批量上传文档
  </InstantUploadButton>
);

⚙️ 常用上传配置说明

| 属性 | 场景建议 | 示例值 | | :--- | :--- | :--- | | maxConcurrent | 批量上传时平衡服务器压力 | 3 (默认) | | maxFileSize | 防止超大文件耗尽带宽 | 5 * 1024 * 1024 (5MB) | | acceptedFileTypes | 限制上传格式（支持 MIME 或扩展名） | ['.jpg', 'image/png'] | | beforeEachUpload | 上传前的业务校验（如检查是否登录） | async (file) => ({ ok: true }) |

📝 核心组件概览

| 组件 | 说明 | | :--- | :--- | | InstantUploadButton | 推荐。一键选择文件并立即开始上传，配合浮动卡片显示进度。 | | ModalUploadButton | 传统按钮模式，点击后打开模态框（Modal）进行文件管理和上传。 | | FileUploader | 基础拖拽区域组件，可嵌入到任何页面布局中。 | | ModalUploader | 纯模态框上传器，方便自定义触发方式。 |

⚙️ 通用 Props

| 属性 | 类型 | 默认值 | 描述 | | :--- | :--- | :--- | :--- | | uploadFunction | Function | 必需 | 执行上传的核心异步函数 | | multiple | boolean | true | 是否支持多文件选择 | | maxFiles | number | 10 | 最大上传文件数量 | | maxFileSize | number | - | 单个文件大小限制（字节） | | acceptedFileTypes| string[] | - | 允许的文件扩展名或 MIME 类型 |

📄 许可证

MIT License © 2024