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

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

بعد حدوث هذا، بحثت عن طريقة للتأكد من عدم السماح لتايب سكريبت بهذه الأخطاء.

سيعرض هذا المقال لك كيفية جعل مفاتيح FormData آمنة من النوع باستخدام تايب سكريبت.

المتطلبات

للحصول على أقصى استفادة من هذا المقال، يجب أن تمتلك مفهومًا أساسيًا عن ما يلي:

  1. برمجة جافا سكريبت

  2. أساسيات تايب سكريبت، خاصة كيفية عمل الواجهات، والأنواع، وعامل keyof

  3. واجهة FormData

إذا كنت جديدًا على TypeScript أو FormData ، أوصي بالتحقق من وثائق TypeScript الرسمية و دليل MDN على FormData قبل المتابعة.

الخطوة 1: تعريف المفاتيح المسموح بها الخاصة بك

الطريقة القديمة

الطريقة الافتراضية لإضافة البيانات باستخدام FormData هي القيام بذلك يدويًا ، بسلاسل نصية بسيطة:

const payload = new FormData();

payload.append("id", "1122");
payload.append("name", "Clark Kent");

payload.append("agge", "36"); // السماح بالأخطاء الإملائية في المفتاح

في المقتطف البرمجي أعلاه ، يمكنك أن ترى أن هناك خطأ إملائيًا عند تعريف مفتاح لـ age. ولكن TypeScript لن يعتبره خطأً ، وهذا يمكن أن يؤدي إلى أخطاء عند إرسال هذه البيانات مع طلب API.

الطريقة الأفضل

بدلاً من كتابة المفاتيح يدويًا ، قم بتعريفها في مخطط كائن باستخدام واجهة TypeScript.

interface MyAllowedData {
    id: number;
    name: string;
    age: number;
}

بدلاً من ذلك ، يمكنك تعريفها باستخدام الأنواع:

type MyAllowedData = {
    id: number;
    name: string;
    age: number;
}

يمكنك استخدام الأنواع أو الواجهات ، إنها مسألة تفضيل. يمكنك معرفة المزيد حول الفروق بينهما في هذا ملعب وثائق TypeScript الرسمي.

بعد ذلك ، قم بتعريف نوع اتحادي من كل مفتاح في واجهتك.

type MyFormDataKeys = keyof MyAllowedData
// هذا هو نفسه "نوع MyFormDataKeys = 'id' | 'name' | 'age'"

يساعد مشغل keyof في إنشاء نوع اتحادي لمفاتيح نوع الكائن، لذلك يكون مفيدًا حقًا إذا لم تكن ترغب في تعريف نوع اتحادي يدويًا لكائن أكبر بعدد كبير من المفاتيح.

الخطوة 2: إنشاء وظيفة مساعدة للإلحاق

الآن بعد أن قمت بتعريف المفاتيح الخاصة بك بشكل صارم، الخطوة التالية هي إنشاء وظيفة مساعدة تضمن إلحاق فقط للمفاتيح الصالحة بـ FormData.

function appendToFormData (formData: FormData, key: MyFormDataKeys, value: string) {
  formData.append(key, value);
};

تأخذ وظيفة appendToFormData ثلاثة مُعطيات. إليك كيف يعمل كل شيء:

  • المُعطى الأول، formData، هو نموذج لكائن FormData. هنا حيث ستتم إلحاق أزواج المفتاح/القيمة قبل إرسالها في طلب API.

  • المُعطى الثاني، key، هو اسم المفتاح للحقل الذي ترغب في إلحاقه. نوعه هو MyFormDataKeys، النوع الاتحادي الذي قمنا بإنشائه لضمان إلحاق فقط لتلك المفاتيح التي قمنا بتعريفها بـ FormData.

  • المُعطى الثالث هو سلسلة value تُمثّل القيمة التي سيتم إلحاقها بالمفتاح.

لاحظ أن FormData تقبل فقط سلسلة نصية و Blob كأنواع قيم في كل زوج مفتاح/قيمة. في هذا الدليل، نعمل فقط مع قيم سلسلة نصية – ولكن تذكر أنه يمكنك استخدام قيم blob لإضافة ملفات إلى طلبات الواجهة البرمجية.

الآن، دعنا نختبر الوظيفة:

const payload = new FormData();

appendToFormData(payload, "id", "19282"); // ✅ مسموح به
appendToFormData(payload, "name", "Lenny Brown"); // ✅ مسموح به
appendToFormData(payload, "age", "20"); // ✅ مسموح به

appendToFormData(payload, "someOtherKey", "89"); // ❌ خطأ TypeScript: Argument of type 'someOtherKey' is not assignable.

الخطوة 3: استخدام الوظيفة المساعدة بعد تقديم النموذج

الآن دعنا نضيف حقولنا إلى FormData قبل إرسالها إلى واجهة برمجة التطبيقات.

const handleSubmitForm = () => {
  const payload = new FormData();
   appendToFormData(payload, "id", "19282");
   appendToFormData(payload, "name", "Lenny Brown");
   appendToFormData(payload, "age", "20");

  // أرسل الحمولة عبر واجهة برمجة التطبيقات
  fetch("/api/submit", { method: "POST", body: payload });
};

إضافة الحقول من كائن

بديلاً، إذا كانت لديك بالفعل حمولتك بأكملها في كائن، يمكنك تجنب إضافة كل حقل بشكل منفصل عن طريق تنفيذ الوظيفة بهذه الطريقة:

const handleSubmitForm = () => {
  // جميع حقولك في كائن
  const formValues: MyAllowedData = {
    id: 1123,
    name: 'John Doe',
    age: 56
  }
  const payload = new FormData();

  Object.entries(formValues).forEach(([key, value]) => {
    appendToFormData(payload, key as MyFormDataKeys, `${value}`); // استخدم القوالب النصية لتمرير القيمة
  });

  // أرسل الحمولة عبر واجهة برمجة التطبيقات
  fetch("/api/submit", { method: "POST", body: payload });
};

في المقتطف أعلاه، نستخدم Object.entries لتكرار كل زوج مفتاح/قيمة في كائن حتى يمكن إضافته إلى كائن FormData. لاحظ أن القيمة في كل زوج، سواء كانت سلسلة نصية أم رقمًا، يتم تمريرها كسلسلة باستخدام قوالب النص لمنع عدم تطابق أنواع TypeScript من الوسيط في وظيفتنا المساعدة.

الاستنتاج

من خلال استغلال أمر keyof في TypeScript، يمكننا جعل FormData.append() آمنة تمامًا من النوع. تساعد هذه التقنية البسيطة في منع عدم تطابق المفاتيح وجعل طلبات API الخاصة بك أكثر موثوقية.

أخبرني بأفكارك حول المقال، ولا تتردد في تقديم أي اقتراحات تعتقد أنها يمكن أن تحسن حلي.

شكرًا على قراءتك!