0Pricing
React Academy · درس

رفع الملفات إلى واجهة برمجة خلفية

استخدم FormData وfetch لإرسال الملفات عبر POST وتتبع تقدم الرفع.

رفع الملفات إلى واجهة برمجة خلفية درس مجاني في React Academy على CoddyKit. هذا هو الدرس 4 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في React Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة React Academy 4 دروس في المجموع.

مرحبًا

في هذا الدرس، ستستخدمون API الخاص بـ FormData وfetch لإرسال الملفات باستخدام POST إلى خادم خلفي، وتتبع تقدم الرفع باستخدام XMLHttpRequest، وعرض حالة الرفع في React.

واجهة FormData البرمجية

FormData هي واجهة برمجية في المتصفح تنشئ أجسام طلبات من نوع multipart/form-data، وهو التنسيق الذي تتوقعه الخوادم لرفع الملفات. أضيفوا الملف وأي حقول بيانات وصفية إلى كائن FormData.
const formData = new FormData();
formData.append('file', selectedFile);
formData.append('description', 'Profile photo');

الرفع باستخدام fetch

مرّروا كائن FormData باعتباره جسم طلب fetch. لا تضبطوا Content-Type يدويًا — إذ يضبط المتصفح الحد الفاصل الصحيح لـ multipart تلقائيًا.
const response = await fetch('/api/upload', {
  method: 'POST',
  body: formData,
  // Do not set Content-Type header here!
});

إدارة حالة الرفع

تتبّعوا حالة الرفع باستخدام ثلاثة متغيرات للحالة: `uploading` (قيمة منطقية)، و`progress` (من 0 إلى 100)، و`error` (سلسلة نصية أو null). اعرضوا مؤشرات الانتظار وأشرطة التقدم ورسائل الخطأ بناءً على هذه القيم.
const [uploading, setUploading] = useState(false);
const [progress, setProgress] = useState(0);
const [error, setError] = useState(null);

تقدم الرفع باستخدام XMLHttpRequest

لا تدعم واجهة fetch أحداث تقدم الرفع. استخدموا حدث `upload.onprogress` في XMLHttpRequest للحصول على تحديثات النسبة المئوية.
const xhr = new XMLHttpRequest();
xhr.upload.onprogress = (e) => {
  if (e.lengthComputable) {
    setProgress(Math.round((e.loaded / e.total) * 100));
  }
};
xhr.open('POST', '/api/upload');
xhr.send(formData);

تغليف XHR داخل Promise

غلّفوا استدعاء XMLHttpRequest داخل Promise حتى تتمكنوا من انتظاره باستخدام await ومعالجة الأخطاء عبر async/await.
function uploadFile(file) {
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    xhr.onload = () => resolve(xhr.response);
    xhr.onerror = () => reject(new Error('Upload failed'));
    xhr.upload.onprogress = (e) => setProgress(Math.round(e.loaded / e.total * 100));
    xhr.open('POST', '/api/upload');
    xhr.send(new FormData().set && (() => { const f = new FormData(); f.append('file', file); xhr.send(f); })());
  });
}

معالجة استجابة الخادم

حلّلوا استجابة JSON من الخادم بعد نجاح الرفع. حدّثوا حالة واجهة المستخدم بعنوان URL أو المعرّف المُعاد.
const res = await fetch('/api/upload', { method: 'POST', body: fd });
if (!res.ok) throw new Error('Upload failed');
const { url } = await res.json();
setUploadedUrl(url);

معالجة الأخطاء

التقطوا دائمًا أخطاء الشبكة والخادم. اعرضوا رسالة خطأ واضحة للمستخدم واسمحوا بإعادة المحاولة. أعيدوا ضبط حالتي التقدم وuploading داخل كتلة catch.
try {
  setUploading(true);
  await uploadToServer(file);
} catch (err) {
  setError(err.message);
} finally {
  setUploading(false);
}

إلغاء عملية رفع

استخدموا AbortController مع fetch لإلغاء عملية رفع جارية. خزّنوا وحدة التحكم في ref حتى تتمكنوا من استدعاء abort() من زر الإلغاء.
const abortRef = useRef();

const start = async () => {
  abortRef.current = new AbortController();
  await fetch('/api/upload', { body: fd, signal: abortRef.current.signal });
};
const cancel = () => abortRef.current?.abort();

رفع ملفات متعددة

ارفعوا ملفات متعددة بالتوازي باستخدام Promise.all، أو بالتتابع باستخدام حلقة for-of. تتبّعوا التقدم لكل ملف على حدة باستخدام كائن مفاتيحه أسماء الملفات.

تحقق سريع

لماذا يجب ألّا تضبطوا ترويسة Content-Type يدويًا عند استخدام fetch مع FormData؟

مراجعة

استخدموا FormData لإنشاء حمولات الرفع. استخدموا fetch من دون Content-Type ليتولى المتصفح إنشاء الحد الفاصل تلقائيًا. استخدموا upload.onprogress في XMLHttpRequest لتتبع التقدم. عالجوا الأخطاء بسلاسة وادعموا الإلغاء باستخدام AbortController.

اكتمل المقرر

تهانينا! لقد أنهيتم **المكوّنات غير المتحكم بها ورفع الملفات**. يمكنكم الآن التعامل مع حقول الإدخال غير المتحكم بها، وتحديد الملفات، والسحب والإفلات، وعمليات الرفع متعددة الأجزاء مع تتبع التقدم.

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

هل درس «رفع الملفات إلى واجهة برمجة خلفية» مجاني؟

نعم — نص درس «رفع الملفات إلى واجهة برمجة خلفية» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة React Academy، انتقل إلى CoddyKit PRO. تتضمن دورة React Academy 4 دروس في المجموع.

ماذا ستتعلم في «رفع الملفات إلى واجهة برمجة خلفية»؟

استخدم FormData وfetch لإرسال الملفات عبر POST وتتبع تقدم الرفع. تتمرن على React Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ React Academy؟

لا تُشترط خبرة سابقة. React Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 4 من أصل 4.

كم من الوقت يستغرق درس «رفع الملفات إلى واجهة برمجة خلفية»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس React Academy هذا؟

نعم. كل درس في React Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

  1. المدخلات غير المتحكَّم بها باستخدام useRef
  2. إدخال الملفات وقراءة بياناتها
  3. واجهة تحميل الملفات بالسحب والإفلات
  4. رفع الملفات إلى واجهة برمجة خلفية
← العودة إلى React Academy