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

الأسئلة الشائعة

أسئلة وأجوبة شائعة حول Dropup.

عام​

ما هو Dropup؟​

Dropup هي مكتبة React خفيفة الوزن بدون واجهة مستخدم لرفع الملفات. توفر وظائف السحب والإفلات، والتحقق من صحة الملفات، وتتبع تقدم الرفع، ودعم التخزين السحابي - كل ذلك في حزمة أقل من 10KB مضغوطة.

لماذا "بدون واجهة مستخدم"؟​

بدون واجهة مستخدم يعني أن Dropup لا تتضمن أي مكونات واجهة مستخدم. توفر المنطق وإدارة الحالة، بينما تبني أنت واجهة المستخدم كما تريد. هذا يمنحك التحكم الكامل في الشكل والمظهر.

ما هو حجم الحزمة؟​

  • النواة (@samithahansaka/dropup): < 10KB مضغوطة
  • مع دعم السحابة: +2KB لكل مزود
  • مع معالجة الصور: +5KB
  • مع بروتوكول tus: +3KB (يتطلب tus-js-client)

هل يدعم TypeScript؟​

نعم! Dropup مكتوب بـ TypeScript ويتضمن تعريفات أنواع شاملة. لا حاجة لحزمة @types.

ما هو إصدار React المطلوب؟​

React 16.8+ (يتطلب دعم الخطافات).

الاستخدام​

كيف أرفع الملفات؟​

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

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

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

كيف أتعامل مع أخطاء التحقق؟​

useDropup({
  accept: 'image/*',
  maxSize: 5 * 1024 * 1024,

  onValidationError: (errors) => {
    errors.forEach(({ file, errors }) => {
      console.log(`${file.name}: ${errors.join(', ')}`);
    });
  },
});

هل يمكنني استخدام منطق رفع مخصص؟​

نعم! مرر دالة بدلاً من كائن التكوين:

useDropup({
  upload: async (file, options) => {
    const { signal, onProgress } = options;

    // منطق الرفع المخصص الخاص بك
    const response = await customUpload(file.file, {
      signal,
      onProgress,
    });

    return { url: response.url };
  },
});

كيف أضيف ملفات برمجياً؟​

const { actions } = useDropup();

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

هل يمكنني الحصول على مناطق إفلات متعددة؟​

نعم! كل استدعاء لـ useDropup ينشئ نسخة مستقلة:

const images = useDropup({ accept: 'image/*' });
const documents = useDropup({ accept: '.pdf' });

// استخدمها بشكل منفصل
<div {...images.getDropProps()}>...</div>
<div {...documents.getDropProps()}>...</div>

الرفع​

كيف أعرض تقدم الرفع؟​

const { files } = useDropup({ upload: { url: '/api/upload' } });

{files.map(file => (
  <div key={file.id}>
    {file.name}: {file.progress}%
  </div>
))}

كيف ألغي رفعاً؟​

const { actions } = useDropup();

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

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

كيف أعيد محاولة الرفع الفاشل؟​

const { actions } = useDropup();

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

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

هل يدعم الرفع المجزأ؟​

نعم! استخدم createChunkedUploader:

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

useDropup({
  upload: createChunkedUploader({
    url: '/api/upload/chunk',
    chunkSize: 5 * 1024 * 1024, // 5MB
  }),
});

هل يمكنني الرفع إلى S3 مباشرة؟​

نعم! استخدم رافع السحابة:

import { createS3Uploader } from '@samithahansaka/dropup/cloud/s3';

useDropup({
  upload: createS3Uploader({
    getPresignedUrl: async (file) => {
      const res = await fetch('/api/s3/presign', {
        method: 'POST',
        body: JSON.stringify({ filename: file.name }),
      });
      return res.json();
    },
  }),
});

التحقق​

كيف أقيد أنواع الملفات؟​

// حسب نوع MIME
useDropup({ accept: 'image/*' });

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

// متعدد
useDropup({ accept: ['image/*', 'application/pdf'] });

كيف أحدد حدود الحجم؟​

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

كيف أحدد عدد الملفات؟​

useDropup({
  maxFiles: 5,
});

هل يمكنني إضافة تحقق مخصص؟​

نعم! استخدم customRules:

useDropup({
  customRules: [
    (file) => {
      if (file.name.includes('draft')) {
        return 'ملفات المسودة غير مسموح بها';
      }
      return true;
    },
  ],
});

المعاينات​

كيف أعرض معاينات الصور؟​

المعاينات مفعلة بشكل افتراضي:

const { files } = useDropup();

{files.map(file => (
  file.preview && <img src={file.preview} alt="" />
))}

هل أحتاج لتنظيف روابط المعاينة؟​

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

هل يمكنني تعطيل المعاينات؟​

useDropup({ generatePreviews: false });

استكشاف الأخطاء​

الملفات لا ترفع​

  1. تحقق من أن upload مُكوَّن:

    useDropup({ upload: { url: '/api/upload' } });

  2. تأكد من استدعاء actions.upload() (إلا إذا كان autoUpload: true)

  3. تحقق من وحدة تحكم المتصفح لأخطاء الشبكة

روابط المعاينة لا تعمل​

  1. تأكد من أن الملف صورة
  2. تحقق من أن generatePreviews ليس false
  3. تحقق من أن كائن الملف له خاصية preview صالحة

السحب والإفلات لا يعمل​

  1. تأكد من نشر getDropProps() على عنصر حاوية
  2. ضمّن المدخل المخفي: <input {...getInputProps()} />
  3. تحقق من أن disabled ليس true

أخطاء TypeScript​

  1. حدّث إلى أحدث إصدار من Dropup
  2. تأكد من أن tsconfig.json لديه moduleResolution مناسب
  3. تحقق من أن @samithahansaka/dropup في dependencies، وليس devDependencies

تسريبات الذاكرة​

  1. تأكد من أن المكونات التي تستخدم useDropup تُلغى بشكل صحيح
  2. استدعِ actions.reset() قبل الإلغاء إذا لزم الأمر
  3. لا تخزن الملفات في حالة خارجية بدون تنظيف

التوافق​

هل يعمل مع Next.js؟​

نعم! استخدم توجيه 'use client':

'use client';
import { useDropup } from '@samithahansaka/dropup';

هل يعمل مع React Native؟​

نعم! استخدم المحول الأصلي:

import { NativeAdapter } from '@samithahansaka/dropup/native';

useDropup({ adapter: NativeAdapter });

هل يدعم SSR؟​

نعم! Dropup آمن للـ SSR. يستخدم فقط واجهات برمجة المتصفح عندما تكون متاحة.

دعم المتصفحات؟​

جميع المتصفحات الحديثة:

  • Chrome 60+
  • Firefox 55+
  • Safari 12+
  • Edge 79+

المساهمة​

كيف يمكنني المساهمة؟​

  1. انسخ المستودع
  2. أنشئ فرع ميزة
  3. أرسل طلب سحب

راجع CONTRIBUTING.md للتفاصيل.

كيف أبلغ عن الأخطاء؟​

افتح مشكلة في github.com/samithahansaka/dropup/issues.

هل هناك خارطة طريق؟​

تحقق من مشاكل ومناقشات GitHub للميزات المخطط لها.