JavaScript Academy · درس

كائن FormData

أنشئوا حمولات متعددة الأجزاء من النماذج.

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

ما هي FormData؟

FormData هي واجهة برمجة تطبيقات في المتصفح لإنشاء مجموعة من أزواج المفتاح/القيمة التي تمثل حقول النموذج وقيمها. وهي الطريقة القياسية لتجميع البيانات، بما فيها الملفات، لإرسالها إلى خادم.

تُرمّز بصيغة multipart/form-data، التي تدعم تحميل الملفات الثنائية.

إنشاء FormData فارغ

أنشئ FormData فارغًا وأضف الحقول واحدًا تلو الآخر باستخدام append.

const data = new FormData();
data.append('username', 'ada');
data.append('email', 'ada@example.com');

console.log(data.get('username'));

الإنشاء من عنصر نموذج

مرّر عنصر <form> إلى المُنشئ، وسيُلتقط كل حقل إدخال يحمل اسمًا تلقائيًا. وهذا هو الاستخدام الأكثر شيوعًا.

const form = document.querySelector('#signup');
const data = new FormData(form);

for (const [key, value] of data.entries()) {
  console.log(key, value);
}

append مقابل set

تضيف append قيمة حتى إذا كان المفتاح موجودًا من قبل، ما يتيح تخزين قيم متعددة للمفتاح نفسه. أما set فتستبدل جميع القيم الموجودة لذلك المفتاح.

const data = new FormData();
data.append('tag', 'a');
data.append('tag', 'b');
console.log(data.getAll('tag'));

data.set('tag', 'only');
console.log(data.getAll('tag'));

قراءة القيم

تعيد get القيمة الأولى لمفتاح ما، وتعيد getAll جميع القيم في شكل مصفوفة، بينما تتحقق has من وجود المفتاح.

const data = new FormData();
data.append('color', 'red');
data.append('color', 'blue');

console.log(data.get('color'));
console.log(data.getAll('color'));
console.log(data.has('color'));

حذف الحقول

تحذف delete جميع القيم لمفتاح ما. وهذا مفيد لإزالة الحقول قبل الإرسال.

const data = new FormData();
data.append('keep', '1');
data.append('remove', '2');

data.delete('remove');
console.log(data.has('remove'));
console.log(data.has('keep'));

التكرار عبر الإدخالات

كائن FormData قابل للتكرار. استخدم entries أو keys أو values، أو حلقة for...of، للمرور على جميع الأزواج.

const data = new FormData();
data.append('a', '1');
data.append('b', '2');

for (const key of data.keys()) {
  console.log('field: ' + key);
}

إرفاق الملفات

يمكن أن تتلقى append كائنًا من نوع File أو Blob كقيمة. وتحدد الوسيطة الثالثة الاختيارية اسم الملف الذي سيُرسل إلى الخادم.

const fileInput = document.querySelector('#avatar');
const data = new FormData();
data.append('avatar', fileInput.files[0], 'profile.png');

console.log(data.get('avatar').name);

لماذا multipart/form-data

تُسلسل FormData بصيغة multipart/form-data، التي يمكنها نقل حقول نصية ومحتويات ملفات ثنائية معًا في جسم طلب واحد. ولهذا فهي الصيغة الأساسية لتحميل الملفات.

const data = new FormData();
data.append('title', 'Vacation Photo');
data.append('photo', new Blob(['binary'], { type: 'image/png' }), 'pic.png');

console.log(data.has('photo'));

التحويل إلى كائن

بالنسبة إلى النماذج البسيطة التي تحتوي على نصوص فقط، يمكن لـ Object.fromEntries تحويل FormData إلى كائن عادي. لاحظ أن هذا يحتفظ بقيمة واحدة فقط لكل مفتاح متكرر.

const form = document.querySelector('#login');
const data = new FormData(form);
const plain = Object.fromEntries(data.entries());

console.log(plain);

أهمية FormData

تُعد FormData حلقة الوصل بين نماذج HTML وطلبات الشبكة. فهي تجمع الحقول والملفات، وتدعم المفاتيح المتكررة، وتُرمّز البيانات الثنائية بأمان. ستقرأ بعد ذلك محتويات الملفات باستخدام FileReader، ثم ترسل FormData باستخدام fetch.

const form = document.querySelector('#contact');
const data = new FormData(form);
data.append('source', 'web');

console.log([...data.keys()]);

اختبار سريع

ما الفرق بين append وset في FormData؟

مراجعة: كائن FormData

لقد تعلمتم تجميع بيانات النموذج:

يلتقط new FormData(form) حقول الإدخال المسماة تلقائيًا.
يتيح append استخدام مفاتيح متكررة، بينما يستبدلها set.
اقرأ القيم باستخدام get وgetAll وhas، وكرّر عليها باستخدام entries.
تُرمّز البيانات بصيغة multipart/form-data، التي تدعم الملفات والبيانات الثنائية.

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

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

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

ماذا ستتعلم في «كائن FormData»؟

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

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

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

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

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

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

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

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

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