أسرار *.d.ts: كيف يرى TypeScript الكود الخارجي

تعلم Python بسهولة دون إرهاق نظري. حل مهام عملية مع التحقق التلقائي واكتب الكود مباشرة في المتصفح.

مقدمة: لماذا يتوافق كودك مع lodash؟

هل تساءلت يومًا كيف يتعرف TypeScript على الأنواع لمكتبة جافا سكريبت عادية مثل lodash أو jQuery؟ فأنت فقط تكتب import _ from 'lodash'، وفجأة يظهر لديك الإكمال التلقائي والتحقق من الأنواع. سحر؟ لا، إنه عمل الملفات الغامضة *.d.ts.

على Stack Overflow، حصد سؤال "About \"*.d.ts\" in TypeScript" آلاف المشاهدات — يريد المطورون فهم ما يختبئ وراء هذا الامتداد. اليوم سننظر تحت غطاء TypeScript ونشرح كيفية عمل تصريحات الأنواع. ستتعلم ليس فقط النظرية، بل ستحصل أيضًا على أمثلة عملية ستساعدك في إنشاء أنواعك الخاصة لأي مشاريع جافا سكريبت.

ما هو .d.ts في الواقع؟

الملفات ذات الامتداد .d.ts هي ملفات تصريح TypeScript. تحتوي فقط على أوصاف للأنواع، وليس التنفيذ. فكر فيها كـ "عقد": ينظر TypeScript إلى هذا الملف ويفهم أي الدوال والفئات والمتغيرات موجودة، وما هي أنواعها.

الفرق الرئيسي عن ملفات .ts العادية: .d.ts لا يتم ترجمتها إلى جافا سكريبت. إنها موجودة فقط للتحليل الثابت والإكمال التلقائي.

// myLibrary.d.tsexport function greet(name: string): void;export const VERSION: string;

الآن، إذا قمت باستيراد هذه المكتبة، سيعرف TypeScript: greet تأخذ سلسلة نصية ولا تُرجع شيئًا، و VERSION هي سلسلة نصية. بدون هذا الملف، كنت ستحصل على خطأ "Could not find a declaration file for module".

كيف يجد TypeScript ملف .d.ts؟

آلية البحث عن التصريحات تعمل على عدة مراحل:

البحث التلقائي: إذا كان بجانب ملف .js ملف .d.ts بنفس الاسم، سيلتقطه TypeScript تلقائيًا.
حقل types أو typings في package.json: العديد من المكتبات تشير إلى مسار ملف التصريح الخاص بها. مثال: "types": "./lib/index.d.ts".
التوجيه /// <reference path="" />: الإشارة اليدوية إلى ملف التصريح (طريقة قديمة ولكنها لا تزال موجودة).
حزم @types: إذا كانت المكتبة لا تحتوي على أنواعها الخاصة، ينشرها المجتمع على npm تحت اسم @types/اسم-المكتبة.

عندما تكتب npm install @types/react، فأنت تقوم بتنزيل مجموعة من ملفات .d.ts التي تصف React.

تحت الغطاء: كيف يعالج TypeScript ملف .d.ts

دعنا نتخيل أن TypeScript هو محقق يحقق في "قضية الأنواع". ملفات .d.ts هي شهادات الشهود. تقول: "هذه هي الدالة add، تأخذ رقمين وتُرجع رقمًا". يصدق TypeScript هذه الشهادات ولا يتحقق مما إذا كانت صحيحة بالفعل (لأنه لا يوجد تنفيذ).

التصريحات المحيطة (Ambient declarations)

واحدة من أقوى إمكانيات .d.ts هي إعلان الوحدات المحيطة. هذا يسمح بوصف أنواع للوحدات غير الموجودة في كودك. مثال، تريد استخدام المتغير العام $ من jQuery:

// globals.d.tsdeclare var $: (selector: string) => any;

أو وصف وحدة كاملة:

// my-custom-module.d.tsdeclare module 'my-custom-module' {    export function doSomething(x: number): string;    export interface Config {        timeout: number;    }}

الآن يمكنك كتابة import { doSomething } from 'my-custom-module' — وسيعرف TypeScript الأنواع.