معالجة الملفات

يوفر Dropup تجربة سلسة للتعامل مع الملفات من لحظة اختيارها حتى رفعها.

طرق اختيار الملفات

السحب والإفلات

استخدم getDropProps() لتمكين السحب والإفلات على أي عنصر:

function DropZone() {
  const { getDropProps, getInputProps, state } = useDropup();

  return (
    <div
      {...getDropProps()}
      style={{
        border: state.isDragging ? '2px dashed blue' : '2px dashed gray',
        backgroundColor: state.isDragging ? '#f0f8ff' : 'transparent',
      }}
    >
      <input {...getInputProps()} />
      <p>أفلت الملفات هنا</p>
    </div>
  );
}

النقر للاختيار

منطقة الإفلات قابلة للنقر بشكل افتراضي:

<div {...getDropProps()}>
  <input {...getInputProps()} />
  <p>انقر أو اسحب الملفات هنا</p>
</div>

الاختيار البرمجي

افتح حوار الملفات برمجياً:

const { openFileDialog } = useDropup();

<button onClick={openFileDialog}>
  اختر الملفات
</button>

إضافة الملفات برمجياً

أضف الملفات مباشرة (مفيد لأحداث اللصق أو التكاملات):

const { actions } = useDropup();

// من الحافظة
document.addEventListener('paste', (e) => {
  const files = e.clipboardData?.files;
  if (files?.length) {
    actions.addFiles(files);
  }
});

بنية كائن الملف

كل ملف في مصفوفة files له هذه البنية:

interface DropupFile {
  // التعريف
  id: string;              // معرف فريد (مولد تلقائياً)
  file: File;              // كائن File الأصلي من المتصفح

  // البيانات الوصفية
  name: string;            // اسم الملف
  size: number;            // الحجم بالبايتات
  type: string;            // نوع MIME (مثل "image/png")

  // المعاينة (للصور)
  preview?: string;        // رابط Object URL للمعاينة

  // حالة الرفع
  status: FileStatus;      // 'idle' | 'uploading' | 'complete' | 'error' | 'paused'
  progress: number;        // 0-100

  // النتائج
  uploadedUrl?: string;    // الرابط بعد نجاح الرفع
  response?: unknown;      // استجابة الخادم
  error?: DropupError;     // تفاصيل الخطأ في حالة الفشل

  // بيانات مخصصة
  meta?: Record<string, unknown>;
}

دورة حياة حالة الملف

idle → uploading → complete
                 ↘ error → (retry) → uploading
                 ↘ paused → (resume) → uploading

قيم الحالة

الحالة	الوصف
idle	الملف مضاف لكن لم يبدأ الرفع بعد
uploading	قيد الرفع حالياً
complete	الرفع ناجح
error	فشل الرفع
paused	الرفع متوقف مؤقتاً (للرفع القابل للاستئناف)

العمل مع الملفات

الوصول للملفات

const { files } = useDropup();

// جميع الملفات
console.log(files);

// التصفية حسب الحالة
const uploading = files.filter(f => f.status === 'uploading');
const completed = files.filter(f => f.status === 'complete');
const failed = files.filter(f => f.status === 'error');

إزالة الملفات

const { files, actions } = useDropup();

// إزالة ملف واحد
actions.remove(files[0].id);

// إزالة جميع الملفات
actions.reset();

تحديث البيانات الوصفية للملف

const { actions } = useDropup();

// إضافة بيانات وصفية مخصصة
actions.updateFileMeta(fileId, {
  customField: 'value',
  category: 'documents',
});

معاينات الملفات

لملفات الصور، يمكن لـ Dropup إنشاء روابط معاينة:

const { files } = useDropup({
  generatePreviews: true, // الافتراضي: true
});

// استخدام المعاينة في واجهتك
{files.map(file => (
  file.preview && (
    <img
      src={file.preview}
      alt={file.name}
      style={{ maxWidth: 100, maxHeight: 100 }}
    />
  )
))}

إدارة الذاكرة

روابط المعاينة هي Object URLs التي تستهلك الذاكرة. يقوم Dropup تلقائياً بإلغائها عند إزالة الملفات أو إلغاء تحميل المكون.

تنسيق حجم الملف

مساعد لعرض أحجام الملفات:

function formatFileSize(bytes: number): string {
  if (bytes === 0) return '0 بايت';
  const k = 1024;
  const sizes = ['بايت', 'KB', 'MB', 'GB'];
  const i = Math.floor(Math.log(bytes) / Math.log(k));
  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
}

// الاستخدام
{files.map(file => (
  <span>{formatFileSize(file.size)}</span>
))}

التعامل مع الملفات الكبيرة

للملفات الكبيرة، ضع في اعتبارك الرفع المجزأ:

import { useDropup, createChunkedUploader } from '@samithahansaka/dropup';

const { files } = useDropup({
  upload: createChunkedUploader({
    url: '/api/upload',
    chunkSize: 5 * 1024 * 1024, // أجزاء 5MB
  }),
});

راجع الرفع المجزأ لمزيد من التفاصيل.