Dropup 快速开始
Dropup 是一个轻量级的无头 React 文件上传库，让您完全掌控 UI 设计的同时处理所有复杂的上传逻辑。
为什么选择 Dropup？
- 轻量级 - 核心包仅约 10KB（gzip 压缩后）
- 无头设计 - 基于 hooks 的 API，完全掌控您的 UI
- 拖放支持 - 内置拖放功能
- 进度追踪 - 实时追踪每个文件的上传进度
- 分块上传 - 将大文件分块以实现可靠上传
- 云端就绪 - 预置 S3、GCS 和 Azure 的辅助工具
- 图片处理 - 内置压缩和预览生成功能
- 跨平台 - 支持 React DOM 和 React Native
- TypeScript - 完整的 TypeScript 支持
安装
使用您喜欢的包管理器安装 Dropup：
npm install @samithahansaka/dropup
对等依赖
Dropup 需要 React 16.8 或更高版本（需要 hooks 支持）：
npm install react
快速开始
这是一个简单的入门示例：
import { useDropup } from '@samithahansaka/dropup';
function FileUploader() {
const {
files,
state,
actions,
getDropProps,
getInputProps
} = useDropup({
accept: 'image/*',
maxSize: 10 * 1024 * 1024, // 10MB
multiple: true,
});
return (
<div>
{/* 拖放区域 */}
<div
{...getDropProps()}
style={{
border: state.isDragging ? '2px dashed blue' : '2px dashed gray',
padding: 40,
textAlign: 'center',
cursor: 'pointer',
}}
>
<input {...getInputProps()} />
<p>拖放文件到此处，或点击选择</p>
</div>
{/* 文件列表 */}
<ul>
{files.map((file) => (
<li key={file.id}>
{file.name} - {file.status}
{file.status === 'uploading' && ` (${file.progress}%)`}
<button onClick={() => actions.remove(file.id)}>移除</button>
</li>
))}
</ul>
{/* 上传按钮 */}
{files.length > 0 && (
<button onClick={() => actions.upload()}>
上传全部
</button>
)}
</div>
);
}
核心概念
1. useDropup Hook
useDropup hook 是主要入口点。它返回构建文件上传 UI 所需的一切：
const {
files, // 包含状态、进度等信息的文件数组
state, // 整体状态（isDragging、isUploading、progress）
actions, // 上传、移除、取消、重置等方法
getDropProps, // 拖放区域元素的属性
getInputProps, // 隐藏文件输入框的属性
} = useDropup(options);
2. 文件对象
files 数组中的每个文件包含：
{
id: string; // 唯一标识符
file: File; // 原始 File 对象
name: string; // 文件名
size: number; // 文件大小（字节）
type: string; // MIME 类型
preview?: string; // 预览 URL（仅限图片）
status: 'idle' | 'uploading' | 'complete' | 'error';
progress: number; // 上传进度（0-100）
error?: Error; // 上传失败时的错误对象
uploadedUrl?: string; // 上传成功后的 URL
}
3. 操作方法
actions 对象提供控制上传的方法：
actions.upload(fileIds?) // 开始上传（全部或指定文件）
actions.cancel(fileId?) // 取消上传
actions.remove(fileId) // 从列表中移除文件
actions.reset() // 清除所有文件
actions.retry(fileIds?) // 重试失败的上传
配置上传
要启用实际上传功能，请提供上传配置：
const { files } = useDropup({
upload: {
url: '/api/upload',
method: 'POST',
headers: {
'Authorization': 'Bearer token',
},
},
autoUpload: true, // 添加文件时自动开始上传
});