TypeScript / المتوسط / الدرس 10
الوحدات وحل المسارات والتصريحات
وائم الفاحص مع مضيف الوحدات وميّز اعتماديات الأنواع من الاستيراد التنفيذي وعامل التصريحات كادعاءات عن تطبيقات فعلية.
في هذه الصفحة
أهداف الدرس
- شرح ESM وCommonJS وحل المسارات المرتبط بالمضيف.
- استخدام استيراد وتصدير الأنواع بوعي.
- تشخيص افتراضات التصريحات والاختصارات دون اختلاق دعم تنفيذي.
تحدد البيئة أو أداة التجميع تحميل الوحدات
يحمّل المضيف مثل Node أو المتصفح أو المجمّع الوحدات. تحتاج TypeScript نموذجًا متوافقًا للحل والتوليد ولا تستبدله. يختلف ESM وCommonJS في الصياغة وتفسير الملفات والبيانات والتوافق. اختر module وmoduleResolution للبيئة؛ وتمثل NodeNext قواعد Node لا سياسة عامة. يعتمد السلوك على الامتدادات وtype في package.json. سجّلها ولا تفترض تنفيذ كل استيراد يفهمه المحرر.
تصدير العمليات والأوصاف النوعية بوعي
تصدّر الوحدة نوعًا ودالة وتختبر الدالة محليًا. تُمحى export type وتبقى الدالة قيمة تنفيذ. يحتاج مستورد آخر مسارًا مولدًا وصيغة صحيحة. يتجنب العرض المحلي ادعاء تشغيل ترتيب حزم غير محدد. تمنع import type تحويل علاقة نوعية إلى استيراد فعلي وفق الخيارات، ولا تعفي من منشئ أو أثر تنفيذي مطلوب.
export type Count = { value: number };
export function describe(count: Count): string { return `count=${count.value}`; }
console.log(describe({ value: 3 }));
count=3
توفر Count معلومات الفحص وتُولد describe لتعطي النص المطبوع.
تصف التصريحات القيم ولا توفرها
تصف .d.ts تنفيذًا يجب أن يوجد في موضع آخر. قد تزيل declare التشخيص وتترك ReferenceError أو فشل تحميل. يوفر المثال كائنًا فعليًا يطابق الواجهة، وهو ما لا يقدمه التصريح وحده. افحص exports ومداخل JavaScript والأنواع والصيغ للحزمة. يجب مطابقة التصريح للسلوك والاختيار والفشل. تتجاوز skipLibCheck فحوصًا ولا تصلح وصفًا كاذبًا أو توفر شيفرة غائبة.
export {};
interface Formatter { format(value: number): string }
const formatter: Formatter = { format: value => `value:${value}` };
console.log(formatter.format(8));
value:8
يعمل الأسلوب لأن الحرفي ينشئه، ولا ينشئ تصريح محيطي formatter الكائن.
اختصار المسار ليس إعادة كتابة للناتج
تساعد paths الفاحص وفق خريطة ولا تعيد عادة كتابة اسم الوحدة المولد إلى ملف نسبي. يحتاج المضيف دعمًا مطابقًا أو أسماء قابلة للحل. تسمي استيرادات Node ESM النسبية امتداد .js المولد غالبًا رغم مصدر .ts وفق القواعد المختارة. لميزات إعادة كتابة امتدادات TypeScript إصدار ونطاق محددان وليست تحويل اختصارات عامة. اختبر المدخل الناتج في المضيف.
فحص حد الحزمة كمستهلك
استخدم تجربة ملفات صغيرة ببيانات الحزمة والخيارات والامتدادات وأمر التنفيذ نفسها. افحص الحل والتنفيذ؛ فلا يكفي أحدهما. اختبر الحزمة المنشورة من مستهلك منفصل بدل مسارات المصدر التي تتجاوز exports. أبقِ الإعداد التابع غير قابل للتشغيل دون ملفاته. ثبّت الإصدار عند التشخيص لتغير السلوك، وتجنب تصريحات عامة تخفي كل استيراد غير محلول واعتمادية مفقودة.
الأخطاء الشائعة وإصلاحها
اختصار يفحص بنجاح ويفشل تحميله في Node.
- لماذا يحدث؟
- لا يملك المضيف محلل الاختصار المطابق.
- كيف تصلحه؟
- استخدم اسمًا يحله المضيف أو إعدادًا مدعومًا.
- كيف تتجنب تكراره؟
- شغّل المداخل المولدة ضمن التحقق.
متغير مصرّح به غائب أثناء التنفيذ.
- لماذا يحدث؟
- اعتُبرت التصريحات المحيطية تنفيذًا.
- كيف تصلحه؟
- وفر الاعتمادية الفعلية أو أزل الفرض.
- كيف تتجنب تكراره؟
- طابق التصريحات مع JavaScript الحزمة.
توليد استيراد ESM لمضيف غير متوافق.
- لماذا يحدث؟
- اختلفت خيارات الوحدة وتفسير الحزمة.
- كيف تصلحه؟
- وائم الوحدة والحل والامتداد وبيانات الحزمة.
- كيف تتجنب تكراره؟
- احفظ تجربة ملفات مكتملة.
اختبر فهمك
1. يُحل @app/math عبر paths ويبقى في JavaScript. اشرح الفحصين المستقلين.
اعرض الحل المشروح
افحص توجيه الفاحص للملف المقصود ثم قدرة المضيف أو المجمّع على تحميل الاسم المولد. تثبت paths الأولى فقط. أصلح باستيراد نسبي صالح أو آلية اختصار مدعومة واختبر التنفيذ.
2. تعلن .d.ts دالة format(number): string وتعيد JavaScript undefined. ما الطبقة الخاطئة وما دليل التقرير؟
اعرض الحل المشروح
يختلف عقد التصريح والتنفيذ ولا يستنتج الفاحص الواقع من التصريح. أدرج إصداري الحزمة والمترجم والاستيراد ومسار النوع ومدخلًا صغيرًا وناتجًا. أصلح العقد أو التنفيذ بدل تأكيد أن undefined نص.
أهم ما تعلمته
- طابق إعداد الوحدات مع المضيف.
- تختلف اعتماديات الأنواع والقيم التنفيذية.
- افحص المسارات والتصريحات بمستهلك فعلي.