عرض مصدر TypeScript/declaration files/publishing

<noinclude>{{DISPLAYTITLE:نشر ملفات التصريحات في TypeScript}}</noinclude>

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

# تجميعه (bundling) مع حزمة npm الخاصة بك.
# أو نشره على [https://www.npmjs.com/%7Etypes منظمة ‎@types‎]‎ على npm.

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

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

==تضمين التصريحات في حزمة npm الخاصة بك==
إذا كانت حزمتك تحتوي على ملفّ ‎<code>main.js</code>‎ رئيسيّ، فستحتاج إلى الإشارة إلى ملف التصريحات الرئيسي في ملفّ ‎<code>package.json</code>‎ كذلك. اضبط الخاصية ‎<code>types</code>‎ للإشارة إلى ملف التصريحات المُجمَّع الخاص بك. مثلًا:
<syntaxhighlight lang="typescript">
{
    "name": "awesome",
    "author": "Vandelay Industries",
    "version": "1.0.0",
    "main": "./lib/main.js",
    "types": "./lib/main.d.ts"
}
</syntaxhighlight>
لاحظ أن حقل ‎<code>‎"typings"‎</code>‎ مرادف للحقل ‎<code>‎"types"‎</code>‎ ويؤدي نفس الغرض، لذا يمكن استخدامه كذلك.

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

===الاعتماديات===
تُدير npm جميع الاعتماديات. تأكد من أنّ جميع حزم التصريحات التي تعتمد عليها موجودة بشكل صحيح في قسم ‎<code>"dependencies"</code>‎ في ملفّ ‎<code>package.json</code>‎ الخاص بك. مثلًا، تخيل أننا كتبنا حزمةً تعتمد على Browserify وTypeScript:
<syntaxhighlight lang="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"
    }
}
</syntaxhighlight>
تعتمد حزمتنا هنا على الحزمتين ‎<code>browserify</code>‎ و‎<code>typescript</code>‎. حزمة ‎<code>browserify</code>‎ لا تُحزِّم ملفات تصريحاتها في حزم npm الخاصة بها، لذا احتجنا إلى الاعتماد على ‎<code>@types/browserify</code>‎ للحصول على تصريحاتها. أمّا ‎<code>typescript</code>‎ فتُحزِّم ملفات تصريحاتها معها، لذا لا حاجة لأي اعتماديّات إضافية.

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

===أخطاء ينبغي تجنبها===
====‎<code>‎/// <reference path="..." />‎</code>‎====
لا تستخدم ‎<code>‎/// <reference path="..." />‎</code>‎ في ملفات تصريحاتك:
<syntaxhighlight lang="typescript">
/// <reference path="../typescript/lib/typescriptServices.d.ts" />
....
</syntaxhighlight>
استعمل  ‎<code>/// <reference types="..." /></code>‎ كبديل:
<syntaxhighlight lang="typescript">
/// <reference types="typescript" />
....
</syntaxhighlight>
تأكد من إلقاء نظرة مجدّدًا على قسم استخدام الاعتماديات للاستزادة.

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

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

==النشر إلى منظمة ‎@types‎==
تُنشَر الحزم الموجودة على [https://www.npmjs.com/%7Etypes منظمة ‎@types‎] تلقائيًّا من مستودع [https://github.com/DefinitelyTyped/DefinitelyTyped DefinitelyTyped] باستخدام الأداة [https://github.com/Microsoft/types-publisher types-publisher]. إن أردت أن تُنشَر تصريحاتك كحزمة من حزم ‎@types‎، فالمرجو إرسال طلب سحب (pull request) إلى مستودع [https://github.com/DefinitelyTyped/DefinitelyTyped DefinitelyTyped]. يمكنك الحصول على المزيد من التفاصيل في صفحة [http://definitelytyped.org/guides/contributing.html إرشادات المساهمة].

== مصادر ==
* [https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html صفحة Publishing في توثيق TypeScript الرسمي.]
[[تصنيف:TypeScript]]