تخطي إلى المحتوى الرئيسي

البدء مع Dropup

Dropup هي مكتبة React خفيفة الوزن بدون واجهة مستخدم لرفع الملفات، تمنحك التحكم الكامل في واجهة المستخدم الخاصة بك بينما تتعامل مع جميع منطق الرفع المعقد.

لماذا Dropup؟​

  • 🪶 خفيف الوزن - الحجم الأساسي فقط ~10KB مضغوطة
  • 🎨 بدون واجهة مستخدم - تحكم كامل في واجهة المستخدم الخاصة بك باستخدام API قائم على الخطافات
  • 📁 السحب والإفلات - دعم مدمج للسحب والإفلات
  • 📊 تتبع التقدم - تقدم الرفع في الوقت الفعلي لكل ملف
  • 🔄 الرفع المجزأ - تقسيم الملفات الكبيرة لرفع موثوق
  • ☁️ جاهز للسحابة - مساعدين معدين مسبقاً لـ S3 و GCS و Azure
  • 🖼️ معالجة الصور - ضغط مدمج وإنشاء معاينات
  • 📱 متعدد المنصات - يعمل مع React DOM و React Native
  • 🔒 TypeScript - دعم كامل لـ TypeScript

التثبيت​

قم بتثبيت Dropup باستخدام مدير الحزم المفضل لديك:

npm install @samithahansaka/dropup

التبعيات المشتركة​

يتطلب Dropup إصدار React 16.8 أو أعلى (لدعم الخطافات):

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. خطاف useDropup​

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

const {
  files,           // مصفوفة الملفات مع الحالة والتقدم وما إلى ذلك.
  state,           // الحالة العامة (isDragging، isUploading، progress)
  actions,         // طرق للرفع والإزالة والإلغاء والإعادة
  getDropProps,    // خصائص لعنصر منطقة الإفلات الخاص بك
  getInputProps,   // خصائص لإدخال الملف المخفي
} = useDropup(options);

2. كائنات الملفات​

يحتوي كل ملف في مصفوفة files على:

{
  id: string;          // معرف فريد
  file: File;          // كائن الملف الأصلي
  name: string;        // اسم الملف
  size: number;        // حجم الملف بالبايتات
  type: string;        // نوع MIME
  preview?: string;    // رابط المعاينة (للصور)
  status: 'idle' | 'uploading' | 'complete' | 'error';
  progress: number;    // تقدم الرفع (0-100)
  error?: Error;       // كائن الخطأ في حالة فشل الرفع
  uploadedUrl?: string; // الرابط بعد نجاح الرفع
}

3. الإجراءات​

يوفر كائن 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, // رفع تلقائي عند إضافة الملفات
});

الخطوات التالية​