التحقق من الملفات

يوفر Dropup تحققاً شاملاً من الملفات لضمان قبول الملفات الصالحة فقط.

خيارات التحقق

Accept (أنواع الملفات)

حدد أنواع الملفات المقبولة:

// قبول الصور فقط
useDropup({ accept: 'image/*' });

// قبول أنواع محددة
useDropup({ accept: 'image/png, image/jpeg' });

// قبول حسب الامتداد
useDropup({ accept: '.pdf, .doc, .docx' });

// فئات متعددة
useDropup({ accept: ['image/*', 'application/pdf', '.txt'] });

أنماط Accept الشائعة

النمط	الوصف
image/*	جميع الصور
image/png, image/jpeg	PNG و JPEG فقط
video/*	جميع الفيديوهات
audio/*	جميع ملفات الصوت
application/pdf	ملفات PDF فقط
.doc, .docx	مستندات Word
*/*	جميع الملفات (الافتراضي)

حدود حجم الملف

useDropup({
  maxSize: 10 * 1024 * 1024, // 10MB كحد أقصى
  minSize: 1024,              // 1KB كحد أدنى
});

حد عدد الملفات

useDropup({
  maxFiles: 5, // 5 ملفات كحد أقصى
});

حدود أبعاد الصورة

useDropup({
  accept: 'image/*',
  maxWidth: 4096,   // الحد الأقصى للعرض بالبكسل
  maxHeight: 4096,  // الحد الأقصى للارتفاع بالبكسل
  minWidth: 100,    // الحد الأدنى للعرض بالبكسل
  minHeight: 100,   // الحد الأدنى للارتفاع بالبكسل
});

قواعد التحقق المخصصة

أنشئ منطق تحقق مخصص:

useDropup({
  customRules: [
    // القاعدة 1: التحقق من طول اسم الملف
    (file) => {
      if (file.name.length > 100) {
        return 'يجب أن يكون اسم الملف أقل من 100 حرف';
      }
      return true;
    },

    // القاعدة 2: التحقق من محتوى معين
    (file) => {
      if (file.name.includes('draft')) {
        return 'ملفات المسودة غير مسموح بها';
      }
      return true;
    },

    // القاعدة 3: تحقق غير متزامن
    async (file) => {
      const hash = await calculateHash(file);
      const exists = await checkDuplicate(hash);
      if (exists) {
        return 'هذا الملف تم رفعه بالفعل';
      }
      return true;
    },
  ],
});

قيم إرجاع القاعدة

القيمة المُرجعة	المعنى
true	نجح التحقق
false	فشل التحقق (خطأ عام)
string	فشل التحقق مع رسالة مخصصة

معالجة أخطاء التحقق

استخدم استدعاء onValidationError:

useDropup({
  accept: 'image/*',
  maxSize: 5 * 1024 * 1024,
  onValidationError: (errors) => {
    errors.forEach(({ file, errors: fileErrors }) => {
      console.log(`${file.name} فشل في التحقق:`);
      fileErrors.forEach(error => console.log(`  - ${error}`));
    });

    // عرض رسالة صديقة للمستخدم
    toast.error(`${errors.length} ملف(ات) فشلت في التحقق`);
  },
});

بنية خطأ التحقق

interface ValidationError {
  file: File;              // الملف الذي فشل
  errors: string[];        // مصفوفة رسائل الخطأ
}

قواعد التحقق المدمجة

يتضمن Dropup قواعد تحقق شائعة:

import { commonRules } from '@samithahansaka/dropup';

useDropup({
  customRules: [
    commonRules.noExecutables,     // حظر .exe، .bat، إلخ.
    commonRules.noHiddenFiles,     // حظر الملفات التي تبدأ بـ .
    commonRules.maxFilenameLength(50),
    commonRules.allowedExtensions(['.jpg', '.png', '.pdf']),
  ],
});

ردود فعل التحقق أثناء السحب

قدم ردود فعل بصرية أثناء السحب:

function DropZone() {
  const { getDropProps, state } = useDropup({
    accept: 'image/*',
  });

  // state.isDragAccept - الملفات تطابق معايير القبول
  // state.isDragReject - الملفات لا تطابق

  return (
    <div
      {...getDropProps()}
      style={{
        borderColor: state.isDragAccept
          ? 'green'
          : state.isDragReject
          ? 'red'
          : 'gray',
      }}
    >
      {state.isDragReject && <p>نوع الملف غير مقبول!</p>}
    </div>
  );
}

مثال تحقق كامل

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

function SecureUploader() {
  const { files, state, getDropProps, getInputProps } = useDropup({
    // نوع الملف
    accept: ['image/jpeg', 'image/png', 'application/pdf'],

    // حدود الحجم
    maxSize: 10 * 1024 * 1024, // 10MB
    minSize: 100,              // 100 بايت (منع الملفات الفارغة)

    // حد العدد
    maxFiles: 10,

    // أبعاد الصورة (للصور فقط)
    maxWidth: 8000,
    maxHeight: 8000,

    // قواعد مخصصة
    customRules: [
      commonRules.noExecutables,
      commonRules.maxFilenameLength(100),

      // مخصص: لا ملفات بها مسافات
      (file) => {
        if (file.name.includes(' ')) {
          return 'أسماء الملفات لا يمكن أن تحتوي على مسافات';
        }
        return true;
      },
    ],

    // معالجة الأخطاء
    onValidationError: (errors) => {
      errors.forEach(({ file, errors }) => {
        alert(`${file.name}: ${errors.join(', ')}`);
      });
    },
  });

  return (
    <div
      {...getDropProps()}
      className={`dropzone ${
        state.isDragReject ? 'reject' : state.isDragAccept ? 'accept' : ''
      }`}
    >
      <input {...getInputProps()} />
      {state.isDragReject ? (
        <p>بعض الملفات سيتم رفضها</p>
      ) : (
        <p>أفلت الملفات هنا (JPEG، PNG، PDF فقط، الحد الأقصى 10MB)</p>
      )}
    </div>
  );
}