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

كل ما يُرجعه خطاف useDropup.

نظرة عامة

const {
  files,          // مصفوفة كائنات الملفات
  state,          // الحالة الحالية
  actions,        // الإجراءات المتاحة
  getDropProps,   // خصائص منطقة الإفلات
  getInputProps,  // خصائص عنصر الإدخال
  openFileDialog, // فتح منتقي الملفات
} = useDropup();

files

مصفوفة من كائنات DropupFile تمثل جميع الملفات المضافة.

const { files } = useDropup();

files.forEach(file => {
  console.log(file.id);          // "abc123"
  console.log(file.name);        // "photo.jpg"
  console.log(file.size);        // 1234567
  console.log(file.type);        // "image/jpeg"
  console.log(file.status);      // "idle" | "uploading" | "complete" | "error"
  console.log(file.progress);    // 0-100
  console.log(file.preview);     // "blob:http://..." (للصور فقط)
  console.log(file.uploadedUrl); // "https://..." (بعد الرفع)
  console.log(file.error);       // DropupError (في حالة الفشل)
});

خصائص DropupFile

الخاصية	النوع	الوصف
id	string	معرف فريد
file	File	كائن File الأصلي من المتصفح
name	string	اسم الملف
size	number	الحجم بالبايتات
type	string	نوع MIME
status	FileStatus	الحالة الحالية
progress	number	تقدم الرفع (0-100)
preview	string | undefined	رابط المعاينة للصور
uploadedUrl	string | undefined	الرابط بعد نجاح الرفع
response	unknown	بيانات استجابة الخادم
error	DropupError | undefined	الخطأ في حالة فشل الرفع
meta	Record<string, unknown>	بيانات وصفية مخصصة

قيم FileStatus

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

state

الحالة الحالية لمنطقة الإفلات.

const { state } = useDropup();

console.log(state.isDragging);   // true عند السحب فوقها
console.log(state.isDragAccept); // true عندما تكون الملفات المسحوبة صالحة
console.log(state.isDragReject); // true عندما تكون الملفات المسحوبة غير صالحة
console.log(state.isUploading);  // true عندما يكون أي ملف قيد الرفع
console.log(state.progress);     // التقدم الإجمالي 0-100
console.log(state.status);       // 'idle' | 'uploading' | 'complete' | 'error'

خصائص State

الخاصية	النوع	الوصف
isDragging	boolean	الملفات تُسحب فوق منطقة الإفلات
isDragAccept	boolean	الملفات المسحوبة تجتاز التحقق
isDragReject	boolean	الملفات المسحوبة تفشل في التحقق
isUploading	boolean	أي ملف قيد الرفع حالياً
progress	number	متوسط تقدم جميع الملفات (0-100)
status	DropupStatus	حالة الرفع الإجمالية

قيم DropupStatus

الحالة	الوصف
'idle'	لا توجد عمليات رفع قيد التقدم
'uploading'	ملف واحد أو أكثر قيد الرفع
'complete'	اكتملت جميع عمليات الرفع بنجاح
'error'	فشلت عملية رفع واحدة أو أكثر

actions

كائن يحتوي على جميع الإجراءات المتاحة.

const { actions } = useDropup();

// بدء الرفع
actions.upload();              // رفع جميع الملفات الخاملة
actions.upload(['id1', 'id2']); // رفع ملفات محددة

// إلغاء الرفع
actions.cancel();              // إلغاء جميع عمليات الرفع
actions.cancel('file-id');     // إلغاء ملف محدد

// إزالة الملفات
actions.remove('file-id');     // إزالة ملف محدد
actions.reset();               // إزالة جميع الملفات

// إعادة محاولة الرفع الفاشل
actions.retry();               // إعادة محاولة جميع الفاشلة
actions.retry(['id1']);        // إعادة محاولة ملفات محددة

// إضافة ملفات برمجياً
actions.addFiles(fileList);    // إضافة File[] أو FileList

// تحديث البيانات الوصفية للملف
actions.updateFileMeta('file-id', { tag: 'important' });

طرق الإجراءات

upload(fileIds?)

بدء رفع الملفات.

// رفع جميع الملفات الخاملة
actions.upload();

// رفع ملفات محددة
actions.upload(['file-id-1', 'file-id-2']);

المعامل	النوع	الوصف
fileIds	string[] (اختياري)	معرفات ملفات محددة للرفع

cancel(fileId?)

إلغاء عمليات الرفع الجارية.

// إلغاء جميع عمليات الرفع
actions.cancel();

// إلغاء ملف محدد
actions.cancel('file-id');

المعامل	النوع	الوصف
fileId	string (اختياري)	معرف ملف محدد للإلغاء

remove(fileId)

إزالة ملف من القائمة.

actions.remove('file-id');

المعامل	النوع	الوصف
fileId	string	معرف الملف للإزالة

reset()

إزالة جميع الملفات وإعادة تعيين الحالة.

actions.reset();

retry(fileIds?)

إعادة محاولة الرفع الفاشل.

// إعادة محاولة جميع الرفع الفاشل
actions.retry();

// إعادة محاولة ملفات محددة
actions.retry(['file-id-1']);

المعامل	النوع	الوصف
fileIds	string[] (اختياري)	معرفات ملفات محددة لإعادة المحاولة

addFiles(files)

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

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

// من مصدر آخر
actions.addFiles([file1, file2]);

المعامل	النوع	الوصف
files	File[] | FileList	الملفات للإضافة

updateFileMeta(fileId, meta)

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

actions.updateFileMeta('file-id', {
  description: 'صورتي',
  tags: ['إجازة', '2024'],
});

المعامل	النوع	الوصف
fileId	string	معرف الملف للتحديث
meta	Record<string, unknown>	البيانات الوصفية للدمج

getDropProps

تُرجع خصائص لنشرها على عنصر منطقة الإفلات.

const { getDropProps, getInputProps } = useDropup();

<div {...getDropProps()}>
  <input {...getInputProps()} />
  أفلت الملفات هنا
</div>

مع خصائص مخصصة

<div
  {...getDropProps({
    className: 'my-dropzone',
    onClick: (e) => {
      // معالج النقر المخصص الخاص بك
      console.log('تم النقر!');
    },
  })}
>
  <input {...getInputProps()} />
</div>

الخصائص المُرجعة

الخاصية	النوع	الوصف
onDragEnter	function	معالج دخول السحب
onDragOver	function	معالج السحب فوق
onDragLeave	function	معالج مغادرة السحب
onDrop	function	معالج الإفلات
onClick	function	معالج النقر (يفتح الحوار)
role	string	دور إمكانية الوصول
tabIndex	number	فهرس التبويب للتركيز

getInputProps

تُرجع خصائص لنشرها على إدخال الملف المخفي.

const { getInputProps } = useDropup();

<input {...getInputProps()} />

مع خصائص مخصصة

<input
  {...getInputProps({
    id: 'file-input',
    name: 'files',
  })}
/>

الخصائص المُرجعة

الخاصية	النوع	الوصف
type	'file'	نوع الإدخال
accept	string	أنواع الملفات المقبولة
multiple	boolean	السماح بملفات متعددة
onChange	function	معالج التغيير
style	object	أنماط الإخفاء

openFileDialog

دالة لفتح منتقي الملفات برمجياً.

const { openFileDialog } = useDropup();

<button onClick={openFileDialog}>
  تصفح الملفات
</button>

أمثلة الاستخدام

قائمة ملفات كاملة

function FileList() {
  const { files, actions, state } = useDropup({
    upload: { url: '/api/upload' },
  });

  return (
    <div>
      <h3>الملفات ({files.length})</h3>

      {files.map(file => (
        <div key={file.id}>
          {file.preview && (
            <img src={file.preview} alt="" width={50} />
          )}
          <span>{file.name}</span>
          <span>{(file.size / 1024).toFixed(1)} KB</span>
          <span>{file.status}</span>

          {file.status === 'uploading' && (
            <progress value={file.progress} max={100} />
          )}

          {file.status === 'error' && (
            <>
              <span style={{ color: 'red' }}>{file.error?.message}</span>
              <button onClick={() => actions.retry([file.id])}>إعادة المحاولة</button>
            </>
          )}

          <button onClick={() => actions.remove(file.id)}>إزالة</button>
        </div>
      ))}

      {state.isUploading && (
        <p>جاري الرفع... {state.progress}%</p>
      )}

      <button
        onClick={() => actions.upload()}
        disabled={state.isUploading || files.length === 0}
      >
        رفع الكل
      </button>

      <button onClick={() => actions.reset()}>
        مسح الكل
      </button>
    </div>
  );
}

تنسيق حالة السحب

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

  const getStyle = () => {
    if (state.isDragAccept) return { borderColor: 'green', backgroundColor: '#e8f5e9' };
    if (state.isDragReject) return { borderColor: 'red', backgroundColor: '#ffebee' };
    if (state.isDragging) return { borderColor: 'blue', backgroundColor: '#e3f2fd' };
    return { borderColor: 'gray', backgroundColor: 'white' };
  };

  return (
    <div
      {...getDropProps()}
      style={{
        border: '2px dashed',
        borderRadius: 8,
        padding: 40,
        textAlign: 'center',
        transition: 'all 0.2s',
        ...getStyle(),
      }}
    >
      <input {...getInputProps()} />
      {state.isDragReject ? (
        <p>يُقبل الصور فقط!</p>
      ) : (
        <p>أفلت الصور هنا</p>
      )}
    </div>
  );
}