توسيع الوحدات في TypeScript والتعامل مع ملفات JavaScript المتداخلة

لقد كانت TypeScript إضافة قيمة إلى نظام JavaScript البيئي لأكثر من عقد من الزمن، حيث اكتسبت شعبية بسبب قدرتها على توفير أمان الأنواع لأكواد JavaScript.

الأنواع لحزم JavaScript#

للتوافق العكسي والمرونة، تسمح TypeScript لمؤلفي الحزم بتوفير تعريفات الأنواع لحزم JavaScript الخاصة بهم. عادةً ما يتم تخزين هذه التعريفات في مستودع "DefinitelyTyped". يمكنك استخدام النطاق @types لتثبيت هذه التعريفات، على سبيل المثال، @types/react هو تعريف النوع لحزمة React.

بعد تثبيت هذه التعريفات، يمكنك استخدام الحزمة مع ثقة في أمان النوع. إليك مثال على تعريف مكون React مع أمان النوع:

توسيع الوحدات#

بينما تحتوي معظم حزم JavaScript الشهيرة على تعريفات أنواع متاحة بسهولة في نطاق @types، قد تفتقر بعض الحزم لتعريفات الأنواع أو قد تكون تعريفاتها قديمة. في مثل هذه الحالات، توفر TypeScript ميزة قوية تعرف بـ "توسيع الوحدة" لإضافة تعريفات الأنواع لهذه الحزم. لنلقِ نظرة على مثال:

الآن يمكنك استخدام هذا التعريف الموسع في الشيفرة الخاصة بك:

لا يقتصر توسيع الوحدات على إضافة تعريفات الأنواع للحزم فحسب، بل يمتد أيضًا لتوسيع تعريفات الأنواع الحالية. على سبيل المثال، يمكنك إضافة خاصية جديدة إلى كائن window:

واستخدامها في الشيفرة الخاصة بك:

في منشور سابق، تحدثنا عن مشكلة نوع في مكتبة React Router، وكان علينا التغلب على التأثير من خلال تمديد وتوسيع النوع الموجود من خلال ملف إعلان مخصص.

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

التوسيع العام#

أحيانًا قد تواجه نصوصًا برمجية تقدم متغيرات عامة، وربما ترغب في توفير تعريفات الأنواع لهذه المتغيرات العامة لاستخدامها في شيفرة TypeScript الخاصة بك. على سبيل المثال، إذا كان لديك نص برمجي يضع متغيرًا عامًا يسمى __DEV__:

يمكنك إضافة تعريفات الأنواع لهذا المتغير العام على النحو التالي:

الآن يمكنك استخدامه في شيفرة TypeScript الخاصة بك:

بدمج توسيع الوحدات والتوسيع العام، يمكنك حتى تمديد تعريفات الأنواع للنماذج الأولية في JavaScript. ومع ذلك، لا يُنصح بذلك عمومًا لأنه يمكن أن يلوث النطاق العام.

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

ملفات JavaScript المتداخلة#

في الأمثلة المذكورة أعلاه، افترضنا أن الواردات يمكن حلها من خلال ملف الدخول للحزمة. ومع ذلك، بعض الحزم تصدر ملفات JavaScript المتداخلة بدون تعريفات الأنواع المقابلة. لنعتبر حزمة تسمى foo بالهيكل التالي:

تقوم حزمة foo بتصدير ملف index.js كنقطة دخول وتصدر أيضًا دليل bar.

لزيادة تعريفات الأنواع لحزمة foo، يمكنك إنشاء ملف foo.d.ts:

ومع ذلك، إذا حاولت استيراد ملف baz.js في TypeScript، ستواجه خطأ:

لزيادة تعريفات الأنواع لملف baz.js، تحتاج إلى إنشاء ملف baz.d.ts منفصل:

هذا يضمن أن TypeScript يمكنه العثور على الوحدة وتعريفات الأنواع الخاصة بها:

للمحافظة على تعريفات الأنواع منظمة، يمكنك محاكاة هيكل الحزمة في ملفات تعريف النوع الخاصة بك:

هذا النهج يبقي شيفرة TypeScript الخاصة بك منظمة وآمنة من حيث النوع، حتى عند التعامل مع ملفات JavaScript المتداخلة.