.d.ts ملفات التصريح
آخر تحديث: 2026-10-22
.d.ts ملفات التصريح
ملفات التصريح (.d.ts) تصف «شكل مكتبة ما» دون أن تحوي أي تنفيذ، فيتمكن TypeScript من توفير الفحص النوعي لمكتبات JS المجردة. وتأتي الأنواع من ثلاثة مصادر: مرفقة مع المكتبة (الأفضل)، حزم @types المجتمعية (npm i -D @types/xxx)، أو كتابة يدوية. وجوهر الكتابة اليدوية الكلمة المفتاحية declare — إعلان أن «هذه القيمة/الدالة منفَّذة في مكان آخر»، فلا يولّد المترجم لها أي شيفرة.
| المجموعة | الإعداد والتطبيق |
|---|---|
| النوع | إعداد |
| الوضع الصارم | غير مطلوب |
ℹ️ معلومة يحوّل المحرر لغة TypeScript إلى JavaScript ثم يشغّلها (بدون فحص أنواع)؛ راجع ناتج كل مثال لنتيجة فحص الأنواع.
📝 الصيغة
// my-lib.d.ts — ملف تعريفات: أنواع فقط، يُمحى بعد التجميع
declare const APP_VERSION: string;
declare function log(msg: string): void;
interface Config {
host: string;
port: number;
debug?: boolean;
}
// ثبّت أنواع المجتمع: npm i -D @types/lodash⚙️ المعاملات
| declare const / let | التصريح بقيمة توفرها البيئة المضيفة (مكتبة، متغير عام من CDN، ...) ونوعها يأتي من وصفك |
|---|---|
| declare function | التصريح بتوقيع دالة منفَّذة مسبقًا — أنواع فقط دون متن |
| @types/* | حزم التصريح التي يحتفظ بها المجتمع (DefinitelyTyped)؛ تُثبَّت في devDependencies وتعمل تلقائيًا دون إعداد |
القيمة المُعادة：لا قيمة معادة — لا تنتج ملفات .d.ts أي JS بعد الترجمة؛ إنها تزوّد المترجم بمعلومات الأنواع في وقت الترجمة فقط.
▶ مثال
عدّل الكود أدناه واضغط «جرّب» لرؤية نتيجة التحويل:
الناتج：
info app booted
[10:24:00] OK db connected
(مخرجات التشغيل بعد الترجمة؛ شكل LogOptions تقدمه ملفات .d.ts — وإدخال { timestamps: "yes" } يعطي error TS2322)💡 نقاط مهمة
ℹ️ معلومة أولوية إيجاد الأنواع: ملف .d.ts الذي يشير إليه حقل types في package.json للمكتبة له الأولوية، ثم حزم @types، وأخيرًا التصريحات المكتوبة يدويًا في مشروعك.
💡 تلميح عند كتابة التصريحات يدويًا شغّل المكتبة مرة واحدة عبر console.log وسجّل شكلها الحقيقي بوصفه interface — فهذا أصدق كثيرًا من تخمين الأنواع من الوثائق؛ ووسم الحقول غير المؤكدة اختيارية (optional) أولًا.
⚠️ تنبيه المتغيرات المُصرَّح بها declare ليس لها شيفرة JS مقابلة بعد الترجمة — يجب أن توفرها البيئة المضيفة. فإذا صُرِّح بـ LOG_LEVEL ولم يعيّنه أحد حصلت على undefined في التشغيل ولم يحذرك TS.
🏷️ الإعداد والتطبيق ذو صلة
💡 حالات ذات صلة
المزيد من الحالات قادم قريبًا.
📚 دروس ذات صلة
❓ أسئلة شائعة
س ثبّتُّ npm i -D @types/xxx وما زالت الأنواع غائبة — ماذا أفعل؟
ج تحقق أولًا من اسم الحزمة (@types/ متبوعة باسم الحزمة الأصلية) ونطاق include في tsconfig؛ وإن لم توجد الحزمة على DefinitelyTyped فعليك كتابتها يدويًا: أنشئ ملف .d.ts وصف به APIs التي تستخدمها عبر declare وأبقه داخل نطاق الترجمة (عامًّا أو حسب الوحدة).
س ما الفرق بين declare const و const العادية؟
ج تُترجم const العادية إلى متغير JS حقيقي؛ أما declare const فهي «وعد» على مستوى الأنواع يخبر المترجم أن «هذا الاسم سيوجد في التشغيل» ولا يوجد شيء منها في ناتج الترجمة إطلاقًا. لهذا لا يجوز أن تحمل تعليمات declare قيمة تهيئة.
س ما وظيفة declare module "xxx"؟
ج تصريح وحدة بيئية: يضيف أنواعًا لحزمة npm أو مورد غير TS. ولها استخدامان نموذجيان — كتابة declare module "pkg" { ... } لحزم خارجية بلا أنواع، وdeclare module "*.css" حتى تتوقف استيرادات الأنماط عن الإبلاغ عن «تعذر إيجاد الوحدة».
