TypeScript Academy · درس

التعامل مع مكتبات الجهات الخارجية غير محددة الأنواع

استخدموا حزم @types واكتبوا تصريحات يدوية

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

المشكلة: الأنواع المفقودة

لا توفّر بعض حزم npm تصريحات TypeScript ولا تملك حزمة @types/. ويتعامل TypeScript معها افتراضيًا على أنها any، مما يؤدي إلى فقدان أمان الأنواع عند حدود الحزمة.

import legacyLib from "untyped-lib"; // legacyLib: any

حزم @types

يوفر مشروع DefinitelyTyped تصريحات أنواع تديرها جهات من المجتمع لآلاف المكتبات. ابحث في npm عن @types/library-name.

npm install --save-dev @types/lodash
npm install --save-dev @types/express
# Now lodash and express have full TypeScript types

كتابة ملف تصريحات (.d.ts)

إذا لم توجد حزمة @types، فاكتب ملف تصريحات بسيطًا في مشروعك لتعريف الوحدة وأنواعها.

// src/types/untyped-lib.d.ts
declare module "untyped-lib" {
  export function doSomething(x: string): number;
  export const version: string;
}

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

وسّع أنواع الجهات الخارجية الحالية بإضافة تصريحاتك إلى وحدة موجودة، من دون إنشاء نسخة متفرعة منها.

// Extend Express Request with a custom property
declare namespace Express {
  interface Request {
    user?: AuthUser;
  }
}

تصريحات الوحدات العامة

بالنسبة إلى فئات كاملة من عمليات الاستيراد التي لا تحتوي على أنواع، مثل ملفات الأصول، استخدم تصريحات الوحدات العامة.

// src/types/assets.d.ts
declare module "*.svg" {
  const content: string;
  export default content;
}
declare module "*.json" {
  const value: Record<string, unknown>;
  export default value;
}

noImplicitAny والمكتبات غير المحددة الأنواع

عند استخدام noImplicitAny: true، يؤدي استيراد وحدة لا تحتوي على أنواع إلى خطأ في التجميع. استخدم ملف تصريحات أو عطّل noImplicitAny لكل ملف باستخدام // @ts-ignore.

// Quick fix for a single untyped import:
// @ts-ignore
import untypedLib from "untyped-lib";

المساهمة في DefinitelyTyped

إذا كتبت أنواعًا عالية الجودة لمكتبة لا تحتوي على أنواع، فأرسلها إلى DefinitelyTyped لمساعدة المجتمع.

# Fork DefinitelyTyped and add:
# types/your-library/index.d.ts
# types/your-library/package.json
# Submit a PR at github.com/DefinitelyTyped/DefinitelyTyped

استخدام any كحل أخير

عندما يتعذر عليك الحصول على الأنواع بسرعة، استخدم any صراحةً مع تعليق يتتبع هذا الدين التقني. فهذا أفضل من any الضمنية لأنه مقصود وواضح.

// eslint-disable-next-line @typescript-eslint/no-explicit-any
const lib: any = require("untyped-lib"); // TODO: add types

skipLibCheck لأخطاء التصريحات

إذا احتوى ملف .d.ts تابع لجهة خارجية على أخطاء داخلية، فإن skipLibCheck: true يخفيها من دون التأثير في فحص الأنواع الخاص بك.

{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

مغلفات الأنواع للمكتبات غير الآمنة

اكتب وحدة مغلّفة ومحددة الأنواع حول مكتبة لا تحتوي على أنواع، لحصر استخدام any وتوفير واجهة برمجية آمنة ومحددة الأنواع لبقية قاعدة الشيفرة.

// src/lib/safe-legacy.ts
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const raw: any = require("untyped-lib");
export function doSomething(x: string): number { return raw.doSomething(x); }

مراجعة: المكتبات غير المحددة الأنواع

للتعامل مع المكتبات غير المحددة الأنواع: تحقّق أولًا من حزم @types/، واكتب ملفات تصريحات بسيطة، واستخدم توسيع الوحدات، وأنشئ مغلفات محددة الأنواع، واستخدم skipLibCheck لأخطاء التصريحات في التبعيات.

تحقق سريع

ما أول مكان ينبغي البحث فيه عن تصريحات الأنواع لحزمة npm لا تحتوي على أنواع؟

ما تعلمته

المكتبات غير المحددة الأنواع: تحقّق من حزم @types/، واكتب ملفات تصريحات، ووسّع الأنواع الحالية، واستخدم تصريحات الوحدات العامة، وضع المكتبات غير الآمنة داخل واجهات مغلفة ومحددة الأنواع، واستخدم skipLibCheck لأخطاء التبعيات.

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

هل درس «التعامل مع مكتبات الجهات الخارجية غير محددة الأنواع» مجاني؟

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

ماذا ستتعلم في «التعامل مع مكتبات الجهات الخارجية غير محددة الأنواع»؟

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

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

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

كم من الوقت يستغرق درس «التعامل مع مكتبات الجهات الخارجية غير محددة الأنواع»؟

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

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

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

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

بدء الترحيل: ‏allowJs وcheckJs
تعليقات أنواع JSDoc كجسر للترحيل
استراتيجية التحويل ملفًا بعد ملف
التعامل مع مكتبات الجهات الخارجية غير محددة الأنواع

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