declare في TypeScript: لماذا هو ضروري وكيفية استخدامه

لماذا تحتاج TypeScript إلى الكلمة المفتاحية declare؟

تخيل أنك تبني منزلاً، لكن بعض الغرف موجودة بالفعل - بناها شخص آخر (مثل مكتبة JavaScript). لا يمكنك الدخول إليها وإعادة بناء الجدران، لكنك تحتاج إلى معرفة تخطيطها لوضع الأثاث بشكل صحيح. هذا هو بالضبط الدور الذي تؤديه الكلمة المفتاحية declare في TypeScript.

إذا كنت قد عملت مع مكتبات شائعة (jQuery, Lodash, D3.js)، فمن المحتمل أنك صادفت ملفات .d.ts - هذه هي "التخطيطات" التي تم إنشاؤها باستخدام declare. في هذه المقالة، سنشرح ما هو declare، ولماذا هو ضروري، وكيفية استخدامه عمليًا. استعد - سيكون هناك الكثير من الكود وقليل من الحشو.

ما هو declare في TypeScript؟

declare هي كلمة مفتاحية تخبر مترجم TypeScript: "مرحبًا، هذا الشيء (متغير، دالة، كلاس أو وحدة) موجود، لكنه مُعرّف في مكان آخر. فقط صدقني واسمح لي باستخدامه في الكود."

من المهم أن تفهم: declare لا يُنشئ أي كود JavaScript. إنها بنية معلوماتية بحتة للمترجم. إذا كتبت declare const x: number = 5، فبعد التجميع سيختفي x - لن يكون موجودًا في الملف النهائي.

متى نحتاج إلى ذلك؟

\n
• العمل مع المتغيرات العامة - مثل window، document أو المتغيرات المضافة عبر CDN.
\n
• كتابة الأنواع لمكتبات JavaScript - عندما تكون المكتبة مكتوبة بلغة JS خالصة، لكنك تريد استخدامها مع TypeScript.
\n
• إنشاء أنواع لملفات التكوين - وحدات CSS، الصور، ملفات JSON.
\n

صياغة declare: أمثلة أساسية

1. إعلان المتغيرات

لنفترض أن لديك متغيرًا عامًا VERSION، مُعرّف في ملف HTML عبر <script>. TypeScript لا يعرف عنه شيئًا، لذا تكتب:

declare const VERSION: string;\n\nconsole.log(VERSION); // حسنًا، TypeScript يعرف أنه نص\n

بعد التجميع، سيختفي declare const VERSION: string، وسيبقى console.log(VERSION).

2. إعلان الدوال

تخيل أن لديك دالة عامة trackEvent من نظام التحليلات:

declare function trackEvent(eventName: string, properties?: Record<string, any>): void;\n\n// الاستخدام\ntrackEvent("button_click", { buttonId: "submit" });\n

لن يتحقق المترجم من التنفيذ - إنه يعرف التوقيع فقط.

3. إعلان الكلاسات

توفر المكتبة كلاس Moment من مساحة الأسماء العامة:

declare class Moment {\n    constructor(date: string);\n    format(pattern: string): string;\n}\n\n// الاستخدام\nconst now = new Moment("2024-01-01");\nconsole.log(now.format("YYYY-MM-DD"));\n

4. إعلان الوحدات

هذا هو السيناريو الأكثر شيوعًا. على سبيل المثال، لديك وحدات CSS أو ملفات JSON:

// styles.d.ts\ndeclare module "*.css" {\n    const styles: Record<string, string>;\n    export default styles;\n}\n\n// images.d.ts\ndeclare module "*.png" {\n    const src: string;\n    export default src;\n}\n

الآن يمكنك استيراد CSS والصور دون أخطاء من TypeScript.

declare وملفات .d.ts

الملفات ذات الامتداد .d.ts (إعلانات الأنواع) هي "موطن" الكلمة المفتاحية declare. تحتوي فقط على إعلانات ولا يتم تجميعها إلى JavaScript. عادةً ما تكون موجودة في مجلد types/ أو تأتي مع المكتبة (مثل @types/lodash).

مثال: إنشاء أنواع لـ jQuery