Dropup 的工作原理

Dropup 基于无头 UI（headless UI）的概念构建 - 它处理所有复杂的文件上传逻辑，同时让您完全控制视觉呈现。

架构

┌─────────────────────────────────────────────────────────────┐
│                     Your React Component                     │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ Drop Zone   │  │ File List   │  │ Upload Button       │  │
│  │ (your UI)   │  │ (your UI)   │  │ (your UI)           │  │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
│         │                │                     │             │
│         ▼                ▼                     ▼             │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                    useDropup Hook                        ││
│  │  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌─────────┐  ││
│  │  │Validation │ │  State    │ │  Upload   │ │ Platform│  ││
│  │  │  Engine   │ │ Manager   │ │  Engine   │ │ Adapter │  ││
│  │  └───────────┘ └───────────┘ └───────────┘ └─────────┘  ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

核心组件

1. 状态管理器

Dropup 使用 React 的 useReducer 进行可预测的状态管理：

• 跟踪所有文件及其状态
• 管理拖拽状态
• 处理上传进度
• 提供计算值

2. 验证引擎

在添加文件之前，它们会经过验证：

const { files } = useDropup({
  accept: 'image/*',           // 文件类型验证
  maxSize: 5 * 1024 * 1024,    // 最大文件大小
  minSize: 1024,               // 最小文件大小
  maxFiles: 10,                // 最大文件数量
  maxWidth: 4096,              // 最大图片宽度
  maxHeight: 4096,             // 最大图片高度
  customRules: [               // 自定义验证
    (file) => file.name.length < 100 || 'Filename too long'
  ],
});

3. 上传引擎

上传引擎处理：

• 简单上传（每个文件一个请求）
• 分块上传（拆分大文件）
• 带指数退避的重试逻辑
• 并发上传管理
• 进度跟踪

4. 平台适配器

Dropup 跨平台工作：

• Web - 使用原生浏览器 API
• React Native - 使用原生文件处理
• SSR - 对服务器端渲染安全

数据流

User Action → Validation → State Update → Upload → Callbacks
     │              │            │           │          │
     ▼              ▼            ▼           ▼          ▼
  Select/     Accept/Reject   files[]    XHR/Fetch   onComplete
  Drop files                  Updated    Progress    onError

设计原则

1. 无头优先

没有内置 UI 组件 - 您可以构建所需的任何内容：

// 您可以完全控制 UI
<div {...getDropProps()}>
  <YourCustomDropZone />
  <input {...getInputProps()} />
</div>

2. 类型安全

完整的 TypeScript 支持和全面的类型定义：

import type { DropupFile, UseDropupOptions } from '@samithahansaka/dropup';

const options: UseDropupOptions = {
  accept: 'image/*',
  onUploadComplete: (file: DropupFile) => {
    console.log(file.uploadedUrl);
  },
};

3. 可摇树优化

只导入您需要的内容：

// 仅核心功能 (~10KB)
import { useDropup } from '@samithahansaka/dropup';

// 需要时添加云支持
import { createS3Uploader } from '@samithahansaka/dropup/cloud/s3';

// 需要时添加图片处理
import { compressImage } from '@samithahansaka/dropup/image';

4. 渐进增强

从简单开始，按需添加功能：

// 基本用法
const { files } = useDropup();

// 添加验证
const { files } = useDropup({ maxSize: 10_000_000 });

// 添加自动上传
const { files } = useDropup({
  maxSize: 10_000_000,
  upload: { url: '/api/upload' },
  autoUpload: true,
});

// 添加云存储
const { files } = useDropup({
  upload: createS3Uploader({ getPresignedUrl }),
});