HTML Academy · درس

FormData API

جمع بيانات النماذج برمجيًا باستخدام الواجهة FormData

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

ما هي FormData

FormData كائن مضمّن يمثّل حقول النموذج وقيمها، ومناسب للإرسال المباشر عبر fetch أو XMLHttpRequest. وهو يتعامل مع عمليات رفع الملفات والترميز متعدد الأجزاء وأزواج المفتاح والقيمة العشوائية من دون إجراء تسلسل يدوي.

الإنشاء من نموذج

مرّر عنصر

إلى المُنشئ: const data = new FormData(formElement). وتحتوي النتيجة على كل عنصر تحكم ناجح في النموذج، مثل حقول الإدخال المسماة وعناصر select ومناطق النص ومربعات الاختيار المحددة والملفات. وتُستبعد عناصر التحكم المعطّلة وغير المحددة تلقائيًا.

document.forms.checkout.addEventListener("submit", async (e) => {
  e.preventDefault();
  const data = new FormData(e.target);
  await fetch("/api/checkout", { method: "POST", body: data });
});

الإرسال باستخدام fetch

يؤدي تمرير FormData إلى body الخاص بـ fetch إلى ضبط Content-Type للطلب على multipart/form-data تلقائيًا، مع boundary الصحيح. لا تضبط Content-Type يدويًا — إذ يحتاج fetch إلى إنشاء boundary بنفسه.

الإضافة والتعيين والحذف

يضيف data.append(key, value) مفتاحًا، مع السماح بالتكرارات. ويستبدل data.set(key, value) أي قيمة موجودة للمفتاح. ويزيل data.delete(key) جميع قيم مفتاح معين. ويتحقق data.has(key) من وجود المفتاح.

const data = new FormData();
data.append("tag", "html");
data.append("tag", "css");
console.log(data.getAll("tag")); // ["html", "css"]

رفع الملفات

يتعامل FormData مع الملفات بشفافية: data.append("avatar", fileInput.files[0]). ويتلقى الخادم عملية رفع متعددة الأجزاء تتضمن اسم الملف ونوع MIME الخاص به. وهذه هي الطريقة القياسية لرفع الملفات باستخدام fetch في الشيفرة الحديثة.

التكرار

يمكن تكرار FormData: for (const [key, value] of data) { ... }. استخدم data.entries() أو data.keys() أو data.values() لإجراء تكرارات محددة. ويفيد ذلك في التسجيل أو التحقق أو إنشاء نسخة JSON من النموذج.

التحويل إلى JSON

للإرسال بصيغة JSON بدلًا من multipart، ينتج Object.fromEntries(data) كائنًا عاديًا — لكنه يفقد المفاتيح المكررة. وللتعامل الصحيح مع التكرارات، كرّر على الإدخالات واجمعها يدويًا. وبالنسبة إلى واجهات JSON الخالصة، من الأبسط إنشاء الكائن مباشرةً من دون المرور عبر FormData.

الملء برمجيًا

أنشئ FormData فارغًا وأضف القيم يدويًا: const data = new FormData(); data.append("title", title); data.append("file", file);. ويفيد ذلك عند إرسال بيانات لم تأتِ من نموذج، مثل الملفات المسحوبة بالإفلات واستجابات API والحمولات المُنشأة.

اكتشاف زر الإرسال

إذا وُجدت أزرار إرسال متعددة، فمرّر زر الإرسال باعتباره الوسيط الثاني إلى FormData: new FormData(form, e.submitter). ويُدرج اسم زر الإرسال وقيمته في البيانات — وهذا مهم للنماذج متعددة الإجراءات.

شبيه FormData: URLSearchParams

بالنسبة إلى ترميز application/x-www-form-urlencoded، وهو ترميز النموذج الافتراضي من دون ملفات، أنشئ URLSearchParams من FormData باستخدام new URLSearchParams(data). وهو أقل تكلفة من multipart للنماذج النصية فقط.

خطأ شائع

يؤدي ضبط رأس Content-Type الخاص بـ fetch صراحةً على "multipart/form-data" إلى إفساد عملية الرفع — إذ لا يعود المتصفح قادرًا على إضافة boundary المطلوب. احذف Content-Type عند إرسال FormData، ودع fetch يتولى الأمر.

اختبار المعرفة

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

الملخص

يمثّل FormData محتوى النموذج ويُرسل بسهولة باستخدام fetch، بما في ذلك رفع الملفات عبر multipart/form-data. أنشئه من عنصر نموذج، وأضف الإدخالات أو عيّنها أو احذفها، وكرّر عليها عند الحاجة. لا تضبط Content-Type عند الإرسال — إذ ينشئ fetch الـ boundary تلقائيًا. استخدم URLSearchParams للنماذج النصية فقط المرمّزة بصيغة urlencoded.

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

هل درس «FormData API» مجاني؟

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

ماذا ستتعلم في «FormData API»؟

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

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

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

كم من الوقت يستغرق درس «FormData API»؟

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

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

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

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

← العودة إلى HTML Academy