كيف يعمل Dropup

تم بناء Dropup حول مفهوم واجهة مستخدم بدون تصميم - يتعامل مع جميع منطق رفع الملفات المعقد بينما يمنحك التحكم الكامل في العرض المرئي.

البنية

┌─────────────────────────────────────────────────────────────┐
│                     مكون React الخاص بك                      │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ منطقة الإفلات│  │ قائمة الملفات│  │ زر الرفع          │  │
│  │ (واجهتك)   │  │ (واجهتك)   │  │ (واجهتك)           │  │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
│         │                │                     │             │
│         ▼                ▼                     ▼             │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                    خطاف useDropup                        ││
│  │  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌─────────┐  ││
│  │  │محرك التحقق│ │ مدير الحالة│ │ محرك الرفع│ │محول المنصة│  ││
│  │  └───────────┘ └───────────┘ └───────────┘ └─────────┘  ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

المكونات الرئيسية

1. مدير الحالة

يستخدم Dropup useReducer من React لإدارة الحالة بشكل متوقع:

• يتتبع جميع الملفات وحالاتها
• يدير حالة السحب
• يتعامل مع تقدم الرفع
• يوفر قيماً محسوبة

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 عبر المنصات:

• الويب - يستخدم واجهات برمجة المتصفح الأصلية
• React Native - يستخدم معالجة الملفات الأصلية
• SSR - آمن للتصيير من جانب الخادم

تدفق البيانات

إجراء المستخدم → التحقق → تحديث الحالة → الرفع → الاستدعاءات
     │              │            │           │          │
     ▼              ▼            ▼           ▼          ▼
  تحديد/      قبول/رفض     files[]    XHR/Fetch   onComplete
  إفلات الملفات            محدثة      التقدم     onError

مبادئ التصميم

1. بدون واجهة أولاً

لا توجد مكونات واجهة مستخدم مدمجة - أنت تبني بالضبط ما تحتاجه:

// أنت تتحكم في الواجهة بالكامل
<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 }),
});