ข้ามไปยังเนื้อหาหลัก

เริ่มต้นใช้งาน Dropup

Dropup เป็นไลบรารีอัปโหลดไฟล์ React แบบ headless ที่มีขนาดเล็ก ให้คุณควบคุม UI ได้อย่างสมบูรณ์ในขณะที่จัดการตรรกะการอัปโหลดที่ซับซ้อนทั้งหมด

ทำไมต้อง Dropup?​

  • 🪶 เบา - แกนหลักเพียง ~10KB gzipped
  • 🎨 Headless - ควบคุม UI ได้เต็มที่ด้วย API แบบ hooks
  • 📁 ลากและวาง - รองรับการลากและวางในตัว
  • 📊 ติดตามความคืบหน้า - ความคืบหน้าการอัปโหลดแบบเรียลไทม์สำหรับแต่ละไฟล์
  • 🔄 อัปโหลดแบบแบ่งส่วน - แบ่งไฟล์ขนาดใหญ่สำหรับการอัปโหลดที่เชื่อถือได้
  • ☁️ พร้อมสำหรับคลาวด์ - ตัวช่วยสำเร็จรูปสำหรับ S3, GCS และ Azure
  • 🖼️ ประมวลผลรูปภาพ - บีบอัดและสร้างพรีวิวในตัว
  • 📱 ข้ามแพลตฟอร์ม - ใช้งานได้กับ React DOM และ React Native
  • 🔒 TypeScript - รองรับ TypeScript เต็มรูปแบบ

การติดตั้ง​

ติดตั้ง Dropup โดยใช้ package manager ที่คุณต้องการ:

npm install @samithahansaka/dropup

Peer Dependencies​

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. Hook useDropup​

Hook useDropup เป็นจุดเริ่มต้นหลัก ส่งคืนทุกอย่างที่คุณต้องการเพื่อสร้าง UI อัปโหลดไฟล์:

const {
  files,           // อาร์เรย์ของไฟล์พร้อมสถานะ, ความคืบหน้า, ฯลฯ
  state,           // สถานะโดยรวม (isDragging, isUploading, progress)
  actions,         // เมธอดสำหรับอัปโหลด, ลบ, ยกเลิก, รีเซ็ต
  getDropProps,    // Props สำหรับ element โซนวาง
  getInputProps,   // Props สำหรับ file input ที่ซ่อน
} = useDropup(options);

2. File Objects​

แต่ละไฟล์ในอาร์เรย์ files ประกอบด้วย:

{
  id: string;          // ตัวระบุเฉพาะ
  file: File;          // File object ดั้งเดิม
  name: string;        // ชื่อไฟล์
  size: number;        // ขนาดไฟล์เป็นไบต์
  type: string;        // MIME type
  preview?: string;    // URL พรีวิว (สำหรับรูปภาพ)
  status: 'idle' | 'uploading' | 'complete' | 'error';
  progress: number;    // ความคืบหน้าการอัปโหลด (0-100)
  error?: Error;       // Error object ถ้าอัปโหลดล้มเหลว
  uploadedUrl?: string; // URL หลังจากอัปโหลดสำเร็จ
}

3. Actions​

Object 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, // อัปโหลดอัตโนมัติเมื่อเพิ่มไฟล์
});

ขั้นตอนถัดไป​