Bỏ qua để đến nội dung chính

Cách Dropup hoạt động

Dropup được xây dựng dựa trên khái niệm headless UI - nó xử lý tất cả logic tải lên tệp phức tạp trong khi cho phép bạn kiểm soát hoàn toàn về mặt hiển thị.

Kiến trúc​

┌─────────────────────────────────────────────────────────────┐
│                   React Component của bạn                    │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ Vùng thả    │  │ Danh sách   │  │ Nút tải lên         │  │
│  │ (UI của bạn)│  │ (UI của bạn)│  │ (UI của bạn)        │  │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
│         │                │                     │             │
│         ▼                ▼                     ▼             │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                    Hook useDropup                        ││
│  │  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌─────────┐  ││
│  │  │Engine xác │ │ Quản lý   │ │  Engine   │ │ Adapter │  ││
│  │  │  thực     │ │ trạng thái│ │  tải lên  │ │nền tảng │  ││
│  │  └───────────┘ └───────────┘ └───────────┘ └─────────┘  ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

Các thành phần chính​

1. Trình quản lý trạng thái​

Dropup sử dụng useReducer của React để quản lý trạng thái có thể dự đoán:

  • Theo dõi tất cả tệp và trạng thái của chúng
  • Quản lý trạng thái kéo
  • Xử lý tiến trình tải lên
  • Cung cấp các giá trị được tính toán

2. Engine xác thực​

Trước khi tệp được thêm, chúng đi qua xác thực:

const { files } = useDropup({
  accept: 'image/*',           // Xác thực loại tệp
  maxSize: 5 * 1024 * 1024,    // Kích thước tệp tối đa
  minSize: 1024,               // Kích thước tệp tối thiểu
  maxFiles: 10,                // Số lượng tệp tối đa
  maxWidth: 4096,              // Chiều rộng hình ảnh tối đa
  maxHeight: 4096,             // Chiều cao hình ảnh tối đa
  customRules: [               // Xác thực tùy chỉnh
    (file) => file.name.length < 100 || 'Tên tệp quá dài'
  ],
});

3. Engine tải lên​

Engine tải lên xử lý:

  • Tải lên đơn giản (một yêu cầu cho mỗi tệp)
  • Tải lên theo khối (chia nhỏ tệp lớn)
  • Logic thử lại với exponential backoff
  • Quản lý tải lên đồng thời
  • Theo dõi tiến trình

4. Adapter nền tảng​

Dropup hoạt động trên các nền tảng:

  • Web - Sử dụng API trình duyệt gốc
  • React Native - Sử dụng xử lý tệp native
  • SSR - An toàn cho render phía máy chủ

Luồng dữ liệu​

Hành động người dùng → Xác thực → Cập nhật trạng thái → Tải lên → Callbacks
         │                 │              │                │           │
         ▼                 ▼              ▼                ▼           ▼
      Chọn/           Chấp nhận/      files[]         XHR/Fetch   onComplete
      Thả tệp         Từ chối        Đã cập nhật     Tiến trình    onError

Nguyên tắc thiết kế​

1. Headless First​

Không có component UI tích hợp sẵn - bạn xây dựng chính xác những gì bạn cần:

// Bạn kiểm soát toàn bộ UI
<div {...getDropProps()}>
  <YourCustomDropZone />
  <input {...getInputProps()} />
</div>

2. An toàn kiểu​

Hỗ trợ TypeScript đầy đủ với các kiểu toàn diện:

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

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

3. Tree Shakeable​

Import chỉ những gì bạn cần:

// Chỉ core (~10KB)
import { useDropup } from '@samithahansaka/dropup';

// Thêm hỗ trợ cloud khi cần
import { createS3Uploader } from '@samithahansaka/dropup/cloud/s3';

// Thêm xử lý hình ảnh khi cần
import { compressImage } from '@samithahansaka/dropup/image';

4. Nâng cao dần​

Bắt đầu đơn giản, thêm tính năng khi cần:

// Sử dụng cơ bản
const { files } = useDropup();

// Thêm xác thực
const { files } = useDropup({ maxSize: 10_000_000 });

// Thêm tự động tải lên
const { files } = useDropup({
  maxSize: 10_000_000,
  upload: { url: '/api/upload' },
  autoUpload: true,
});

// Thêm lưu trữ cloud
const { files } = useDropup({
  upload: createS3Uploader({ getPresignedUrl }),
});