跳至主要內容

Dropup 的運作方式

Dropup 圍繞 無樣式 UI 的概念構建 - 它處理所有複雜的檔案上傳邏輯，同時讓您完全控制視覺呈現。

架構​

┌─────────────────────────────────────────────────────────────┐
│                     您的 React 元件                          │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ 拖放區域    │  │ 檔案列表    │  │ 上傳按鈕            │  │
│  │ (您的 UI)   │  │ (您的 UI)   │  │ (您的 UI)           │  │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
│         │                │                     │             │
│         ▼                ▼                     ▼             │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                    useDropup Hook                        ││
│  │  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌─────────┐  ││
│  │  │驗證引擎   │ │狀態管理器 │ │上傳引擎   │ │平台適配 │  ││
│  │  │          │ │          │ │          │ │器       │  ││
│  │  └───────────┘ └───────────┘ └───────────┘ └─────────┘  ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

關鍵元件​

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 || '檔案名稱過長'
  ],
});

3. 上傳引擎​

上傳引擎處理：

  • 簡單上傳（每個檔案一個請求）
  • 分塊上傳（分割大檔案）
  • 指數退避重試邏輯
  • 並行上傳管理
  • 進度追蹤

4. 平台適配器​

Dropup 跨平台運作：

  • Web - 使用原生瀏覽器 API
  • React Native - 使用原生檔案處理
  • SSR - 支援伺服器端渲染

資料流​

使用者操作 → 驗證 → 狀態更新 → 上傳 → 回呼
     │          │         │        │       │
     ▼          ▼         ▼        ▼       ▼
  選擇/     接受/拒絕   files[]  XHR/Fetch  onComplete
  拖放檔案             已更新    進度       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 }),
});