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

Bắt đầu với Dropup

Dropup là một thư viện tải lên tệp React nhẹ và headless, cho bạn toàn quyền kiểm soát giao diện trong khi xử lý tất cả logic tải lên phức tạp.

Tại sao chọn Dropup?​

  • 🪶 Nhẹ - Core chỉ khoảng ~10KB khi nén
  • 🎨 Headless - Toàn quyền kiểm soát giao diện với API dựa trên hooks
  • 📁 Kéo & Thả - Hỗ trợ kéo và thả tích hợp sẵn
  • 📊 Theo dõi tiến trình - Tiến trình tải lên thời gian thực cho từng tệp
  • 🔄 Tải lên theo khối - Chia nhỏ tệp lớn để tải lên đáng tin cậy
  • ☁️ Sẵn sàng cho đám mây - Hỗ trợ tích hợp cho S3, GCS và Azure
  • 🖼️ Xử lý hình ảnh - Nén và tạo xem trước tích hợp sẵn
  • 📱 Đa nền tảng - Hoạt động với React DOM và React Native
  • 🔒 TypeScript - Hỗ trợ TypeScript đầy đủ

Cài đặt​

Cài đặt Dropup bằng trình quản lý gói ưa thích của bạn:

npm install @samithahansaka/dropup

Phụ thuộc ngang hàng​

Dropup yêu cầu React 16.8 trở lên (để hỗ trợ hooks):

npm install react

Bắt đầu nhanh​

Đây là một ví dụ đơn giản để bạn bắt đầu:

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>
      {/* Vùng thả */}
      <div
        {...getDropProps()}
        style={{
          border: state.isDragging ? '2px dashed blue' : '2px dashed gray',
          padding: 40,
          textAlign: 'center',
          cursor: 'pointer',
        }}
      >
        <input {...getInputProps()} />
        <p>Kéo & thả tệp vào đây, hoặc nhấp để chọn</p>
      </div>

      {/* Danh sách tệp */}
      <ul>
        {files.map((file) => (
          <li key={file.id}>
            {file.name} - {file.status}
            {file.status === 'uploading' && ` (${file.progress}%)`}
            <button onClick={() => actions.remove(file.id)}>Xóa</button>
          </li>
        ))}
      </ul>

      {/* Nút tải lên */}
      {files.length > 0 && (
        <button onClick={() => actions.upload()}>
          Tải lên tất cả
        </button>
      )}
    </div>
  );
}

Khái niệm cốt lõi​

1. Hook useDropup​

Hook useDropup là điểm khởi đầu chính. Nó trả về mọi thứ bạn cần để xây dựng giao diện tải lên tệp:

const {
  files,           // Mảng các tệp với trạng thái, tiến trình, v.v.
  state,           // Trạng thái tổng thể (isDragging, isUploading, progress)
  actions,         // Các phương thức để tải lên, xóa, hủy, đặt lại
  getDropProps,    // Props cho phần tử vùng thả
  getInputProps,   // Props cho input file ẩn
} = useDropup(options);

2. Đối tượng File​

Mỗi tệp trong mảng files chứa:

{
  id: string;          // Định danh duy nhất
  file: File;          // Đối tượng File gốc
  name: string;        // Tên tệp
  size: number;        // Kích thước tệp tính bằng bytes
  type: string;        // Loại MIME
  preview?: string;    // URL xem trước (cho hình ảnh)
  status: 'idle' | 'uploading' | 'complete' | 'error';
  progress: number;    // Tiến trình tải lên (0-100)
  error?: Error;       // Đối tượng lỗi nếu tải lên thất bại
  uploadedUrl?: string; // URL sau khi tải lên thành công
}

3. Actions​

Đối tượng actions cung cấp các phương thức để điều khiển tải lên:

actions.upload(fileIds?)    // Bắt đầu tải lên (tất cả hoặc các tệp cụ thể)
actions.cancel(fileId?)     // Hủy tải lên
actions.remove(fileId)      // Xóa một tệp khỏi danh sách
actions.reset()             // Xóa tất cả tệp
actions.retry(fileIds?)     // Thử lại các tải lên thất bại

Cấu hình tải lên​

Để kích hoạt tải lên thực tế, cung cấp cấu hình tải lên:

const { files } = useDropup({
  upload: {
    url: '/api/upload',
    method: 'POST',
    headers: {
      'Authorization': 'Bearer token',
    },
  },
  autoUpload: true, // Tự động tải lên khi thêm tệp
});

Bước tiếp theo​