نشر ملفات التصريحات في TypeScript

من موسوعة حسوب
اذهب إلى: تصفح، ابحث


مقدمة

بعد أن كتبتَ ملفّ تصريحاتٍ باتباع الخطوات في هذا الدليل، حان الوقت الآن لنشره على منصّة npm. هناك طريقتان رئيسيتان لنشر ملفات تصريحاتك على npm:

  1. تجميعه (bundling) مع حزمة npm الخاصة بك.
  2. أو نشره على منظمة ‎@types‎‎ على npm.

إذا كانت حزمتك مكتوبة بلغة TypeScript، فمن الأفضل اتباع الطريقة الأولى. استعمل الخيار ‎‎--declaration‎‎ لتوليد ملفات التصريحات. بهذه الطريقة ستكون تصريحاتك متزامنة دائمًا مع شيفرة JavaScript.

إن لم تكن حزمتك مكتوبة بلغة TypeScript، عندها فالطريقة الثانية أفضل.

تضمين التصريحات في حزمة npm الخاصة بك

إذا كانت حزمتك تحتوي على ملفّ ‎main.js‎ رئيسيّ، فستحتاج إلى الإشارة إلى ملف التصريحات الرئيسي في ملفّ ‎package.json‎ كذلك. اضبط الخاصية ‎types‎ للإشارة إلى ملف التصريحات المُجمَّع الخاص بك. مثلًا:

{
    "name": "awesome",
    "author": "Vandelay Industries",
    "version": "1.0.0",
    "main": "./lib/main.js",
    "types": "./lib/main.d.ts"
}

لاحظ أن حقل ‎‎"typings"‎‎ مرادف للحقل ‎‎"types"‎‎ ويؤدي نفس الغرض، لذا يمكن استخدامه كذلك.

لاحظ كذلك أنّه إذا كان ملف تصريحاتك مسمًّى بالاسم ‎index.d.ts‎ وكان في جذر الحزمة (بجانب الملف ‎index.js‎) فلا حاجة لتحديد الخاصية ‎"types"‎، لكن من المفضَّل فعل ذلك.

الاعتماديات

تُدير npm جميع الاعتماديات. تأكد من أنّ جميع حزم التصريحات التي تعتمد عليها موجودة بشكل صحيح في قسم ‎"dependencies"‎ في ملفّ ‎package.json‎ الخاص بك. مثلًا، تخيل أننا كتبنا حزمةً تعتمد على Browserify وTypeScript:

{
    "name": "browserify-typescript-extension",
    "author": "Vandelay Industries",
    "version": "1.0.0",
    "main": "./lib/main.js",
    "types": "./lib/main.d.ts",
    "dependencies": {
        "browserify": "latest",
        "@types/browserify": "latest",
        "typescript": "next"
    }
}

تعتمد حزمتنا هنا على الحزمتين ‎browserify‎ و‎typescript‎. حزمة ‎browserify‎ لا تُحزِّم ملفات تصريحاتها في حزم npm الخاصة بها، لذا احتجنا إلى الاعتماد على ‎@types/browserify‎ للحصول على تصريحاتها. أمّا ‎typescript‎ فتُحزِّم ملفات تصريحاتها معها، لذا لا حاجة لأي اعتماديّات إضافية.

تعرِض حزمتنا التصريحات من كلا هاتين الحزمتين، لذا إن استخدم أي مستخدم حزمتنا فسيحتاج إلى امتلاك هذه الاعتماديات كذلك. لذا استعملنا الخاصية ‎"dependencies"‎ عوضًا عن ‎"devDependencies"‎، لأنّنا لو لم نفعل لَاحتاج مستخدم الحزمة إلى تثبيت هذه الاعتماديات يدويا. لو برمجنا مثلًا تطبيق سطر أوامر، ولو لم تكن الحزمة قابلة للاستخدام كمكتبة لاستعملنا في هذه الحالة الخاصية ‎"devDependencies"‎.

أخطاء ينبغي تجنبها

‎/// <reference path="..." />‎

لا تستخدم ‎‎/// <reference path="..." />‎‎ في ملفات تصريحاتك:

/// <reference path="../typescript/lib/typescriptServices.d.ts" />
....

استعمل ‎/// <reference types="..." />‎ كبديل:

/// <reference types="typescript" />
....

تأكد من إلقاء نظرة مجدّدًا على قسم استخدام الاعتماديات للاستزادة.

تحزيم التصريحات التي تعتمد على اعتماديات أخرى

إذا كانت تعريفات أنواعك تعتمد على حزمة أخرى، فاتبع القواعد التالية:

  • لا تدمج الحزمة مع حزمتك، أبق على كل واحدة في ملفّ خاص بها.
  • لا تنسخ كذلك التصريحات في حزمتك إلى الحزمة التي تعتمد عليها.
  • اعتمد على حزمة تصريحات الأنواع الخاصة بها في npm إذا لم تُحزَّم ملفات التصريحات مع الحزمة.

النشر إلى منظمة ‎@types‎

تُنشَر الحزم الموجودة على منظمة ‎@types‎ تلقائيًّا من مستودع DefinitelyTyped باستخدام الأداة types-publisher. إن أردت أن تُنشَر تصريحاتك كحزمة من حزم ‎@types‎، فالمرجو إرسال طلب سحب (pull request) إلى مستودع DefinitelyTyped. يمكنك الحصول على المزيد من التفاصيل في صفحة إرشادات المساهمة.

مصادر