عرض مصدر TypeScript/declaration merging

<noinclude>{{DISPLAYTITLE:دمج التصريحات في TypeScript}}</noinclude>
==مقدمة==
تصِف بعض المبادئ الفريدة الموجودة في لغة  TypeScript شكل كائنات JavaScript على مستوى الأنواع. مبدأ دمج التصريحات (declaration merging) من المزايا التي تنفرد بها TypeScript. سيُساعد فهم هذا المبدأ على العمل مع شيفرة  JavaScript الموجودة مسبقًا. إضافة إلى أنّها توفّر قدرة على إعمال مبادئ تجريد (abstraction concepts) أكثر تقدّمًا.

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

==المبادئ الأساسيّة==
تُنشئ التصريحات في TypeScript الكائنات من مجموعة واحدة على الأقل من أصل ثلاثة مجموعات: مجال أسماء (namespace)، أو نوع (type)، أو قيمة (value). تُنشئ تصريحات مجالات الأسماء مجال أسماء يحتوي على أسماء يُمكن الوصول إليها عن طريق النقاط (‎<code>.</code>‎ مثل ‎<code>User.Login</code>‎). تُنشئ تصريحات الأنواع نوعًا مرئيًّا ذو الشكل المُصرَّح عنه ومرتبطٍ بالاسم المعطى له. أمّا تصريحات القيم فتنشئ قيمًا مرئيّةً في شيفرة  JavaScript المُخرَجَة.

{| class="wikitable"
!نوع التصريح
!|مجال أسماء
!نوع
!قيمة
|-
![[TypeScript/namespaces|مجال أسماء]]
|X
|
|X
|-
![[TypeScript/classes|صنف]]
|
|X
|X
|-
![[TypeScript/enums|ثابت متعدّد]]
|
|X
|X
|-
![[TypeScript/interfaces|واجهة]]
|
|X
|
|-
![[TypeScript/advanced types#.D8.A3.D8.B3.D9.85.D8.A7.D8.A1 .D8.A7.D9.84.D8.A3.D9.86.D9.88.D8.A7.D8.B9 .D8.A7.D9.84.D8.A8.D8.AF.D9.8A.D9.84.D8.A9 .28Type Aliases.29|تسمية نوع بديلة]]
|
|X
|
|-
![[TypeScript/functions|دالة]]
|
|
|X
|-
![[TypeScript/variable declarations|متغير]]
|
|
|X
|}

سيساعدك فهم ما يُنشأ عند كل تصريح على فهم ما يُدمج عندما تؤدي عمليّة دمج التصريحات.

==دمج الواجهات==
دمج الواجهات أبسط وأشهر نوع من أنواع دمج التصريحات. يقوم الدمج على أبسط نحو بجمع عناصر التصريحين في واجهة واحدة بنفس الاسم.
<syntaxhighlight lang="typescript">
interface Box {
    height: number;
    width: number;
}

interface Box {
    scale: number;
}

let box: Box = {height: 5, width: 6, scale: 10};
</syntaxhighlight>
يجب على عناصر الواجهتين أن تكون فريدة (باستثناء الدوال). إذا لم تكن فريدة فيجب عليها أن تكون من نفس النوع. سيطلق المترجم خطأ إذا صرّحت كلا الواجهتان عن عنصر بنفس الاسم ومن نوعين مختلفين (إلا إذا كان هذا العنصر دالة).

أما العناصر التي تكون دالة فسيُعامَل كل عنصر دالة من نفس الاسم على أنّه يصف حملًا زائدًا (overload) لنفس الدالة. لاحظ كذلك أنّه عند دمج واجهةٍ ‎<code>A</code>‎ مع واجهة أخرى تسمى كذلك ‎<code>A</code>‎، فسيكون للواجهة الثانيّة أسبقيّة أعلى من الأولى (أي أن عناصر الواجهة الثانية ستسبق عناصر الواجهة الأولى في الواجهة المندمجة الناتجة).

هذا المثال يوضح الفكرة:
<syntaxhighlight lang="typescript">
interface Cloner {
    clone(animal: Animal): Animal;
}

interface Cloner {
    clone(animal: Sheep): Sheep;
}

interface Cloner {
    clone(animal: Dog): Dog;
    clone(animal: Cat): Cat;
}
</syntaxhighlight>
ستُدمَج الواجهات الثلاثة لإنشاء تصريح واحد:
<syntaxhighlight lang="typescript">
interface Cloner {
    clone(animal: Dog): Dog;
    clone(animal: Cat): Cat;
    clone(animal: Sheep): Sheep;
    clone(animal: Animal): Animal;
}
</syntaxhighlight>
لاحظ أن عناصر كل مجموعة تُبقي على نفس الترتيب، لكن المجموعات ذاتها تُدمَج بوضع مجموعة الأحمال الزائدة اللاحقة في البداية أولًا.

التوقيعات المخصّصة (specialized signatures) استثناءٌ لهذه القاعدة. إذا كان لتوقيعٍ معاملٌ نوعُه [[TypeScript/advanced types#.D8.A3.D9.86.D9.88.D8.A7.D8.B9 .D8.A7.D9.84.D8.B3.D9.84.D8.A7.D8.B3.D9.84 .D8.A7.D9.84.D9.86.D8.B5.D9.8A.D9.91.D8.A9 .D8.A7.D9.84.D8.AD.D8.B1.D9.81.D9.8A.D9.91.D8.A9 .28String Literal Types.29|نوعُ سلسلة نصيّة حرفيّة]] (string literal type) واحد، عوضًا عن اتحاد أنواع سلاسل نصيّة حرفية، فعندئذ سيُنقل إلى أعلى قائمة الأحمال الزائدة المدمجة.

مثلًا، ستُدمَج الواجهات التالية:
<syntaxhighlight lang="typescript">
interface Document {
    createElement(tagName: any): Element;
}
interface Document {
    createElement(tagName: "div"): HTMLDivElement;
    createElement(tagName: "span"): HTMLSpanElement;
}
interface Document {
    createElement(tagName: string): HTMLElement;
    createElement(tagName: "canvas"): HTMLCanvasElement;
}
</syntaxhighlight>
وستكون نتيجة دمج تصريحات ‎<code>Document</code>‎ كالتالي:
<syntaxhighlight lang="typescript">
interface Document {
    createElement(tagName: "canvas"): HTMLCanvasElement;
    createElement(tagName: "div"): HTMLDivElement;
    createElement(tagName: "span"): HTMLSpanElement;
    createElement(tagName: string): HTMLElement;
    createElement(tagName: any): Element;
}
</syntaxhighlight>
==دمج مجالات الأسماء==
تُدمَج عناصر مجالات الأسماء ذات نفس الاسم كذلك كما هي الحال مع الواجهات. ولأنّ مجالات الأسماء تُنشئ كلًّا من مجال أسماء وقيمة في نفس الوقت، فنحتاج أولًا إلى فهم آلية اندماجهما.

لدمج مجالات الأسماء، تُدمَج تعريفات الأنواع من الواجهات المُصدَّرة التي يُصرَّح عنها في كل مجال أسماء، وينتج عن ذلك مجال أسماء واحد تعريفات واجهاته مُندمجة داخله.

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

دمج التصريح عن ‎<code>Animals</code>‎ في هذا المثال:
<syntaxhighlight lang="typescript">
namespace Animals {
    export class Zebra { }
}

namespace Animals {
    export interface Legged { numberOfLegs: number; }
    export class Dog { }
}
</syntaxhighlight>
مكافئ لما يلي:
<syntaxhighlight lang="typescript">
namespace Animals {
    export interface Legged { numberOfLegs: number; }

    export class Zebra { }
    export class Dog { }
}
</syntaxhighlight>
نموذج دمج مجالات الأسماء هذا مفيدٌ كبداية، لكننا نحتاج كذلك إلى فهم ما يحدث للعناصر التي لم تُصدَّر بالكلمة المفتاحية ‎<code>export</code>‎. تكون العناصر غير المصدّرة مرئيّةً فقط في مجال الأسماء الأصلي الذي لم يُدمَج. هذا يعني أن العناصر التي دُمجَت مع عناصر التصريحات الأخرى لا يُمكنها الوصول إلى العناصر التي لم تُصدّر في مجالات الأسماء الأخرى (ولو بعد دمجها معًا).

بالمثال يتّضح المقال:
<syntaxhighlight lang="typescript">
namespace Animal {
    let haveMuscles = true;

    export function animalsHaveMuscles() {
        return haveMuscles; // يمكننا الوصول إلى المتغير لأننا في نفس مجال الأسماء الذي عُرِّف فيه
    }
}

namespace Animal {
    export function doAnimalsHaveMuscles() {
       // خطأ، لا يمكن الوصول هنا إلى العنصر
       // haveMuscles
       // لأنه لم يُصدَّر
        return haveMuscles;
    }
}
</syntaxhighlight>
الدالة ‎<code>animalsHaveMuscles</code>‎ وحدها فقط من يُمكنها الوصول إلى الرمز ‎<code>haveMuscles</code>‎ لأنّهما يشتركان في نفس مجال الأسماء قبل الدمج. أمّا الدالة ‎<code>doAnimalsHaveMuscles</code>‎ فلا يُمكنها رؤية هذا العنصر غير المُصدَّر ولو كانت جزءًا من مجال الأسماء ‎<code>Animal</code>‎ المندمج.

==دمج مجالات الأسماء مع الأصناف، والدوال، والثوابت المتعددة==
تُدمج مجالات الأسماء بسبب مرونتها مع أنواع التصريحات الأخرى كذلك. وللقيام بهذه العمليّة، يجب على التصريح عن مجال الأسماء أن يتبع التصريح الذي سيُدمَج معه. سيملك التصريح الناتج خاصيات كل من نوعيّ التصريحات. تستخدم TypeScript هذه القدرة لتمثيل بعض أنماط JavaScript وبعض لغات البرمجة الأخرى.
===دمج أسماء المجالات مع الأصناف===
يعطي هذا للمستخدم طريقة لوصف الأصناف الداخليّة:
<syntaxhighlight lang="typescript">
class Album {
    label: Album.AlbumLabel;
}
namespace Album {
    export class AlbumLabel { }
}
</syntaxhighlight>
تَتبّع قواعد الظهور (التي تحدد متى تكون العناصر التي دُمجَت مرئيّةً أو غير مرئيّة) نفس القواعد المشروحة في قسم دمج مجالات الأسماء أعلاه، لذا من الواجب تصدير الصّنف ‎<code>AlbumLabel</code>‎ ليتمكّن الصنف المُدمَج من الوصول إليه. النتيجة النهائية هي صنفٌ موجود داخل صنف آخر. يُمكنك كذلك استخدام مجالات الأسماء لإضافة المزيد من العناصر الساكنة لصنف موجود مسبقًا.

إضافةً إلى نمط الأصناف الداخلية، يُمكن كذلك أن تعتاد على إنشاء دالّة في JavaScript ثمّ توسيع هذه الدالة عبر إضافة خاصيّات لها. تعتمد TypeScript على دمج التصريحات لبناء تعريفاتٍ كهذه بطريقة تحفظ أمان الأنواع (type-safe):
<syntaxhighlight lang="typescript">
function buildLabel(name: string): string {
    return buildLabel.prefix + name + buildLabel.suffix;
}

namespace buildLabel {
    export let suffix = "";
    export let prefix = "Hello, ";
}

console.log(buildLabel("Sam Smith"));
</syntaxhighlight>
وبالمثل يُمكن استخدام مجالات الأسماء لتوسيع الثوابت المتعددة ذات عناصر ساكنة:
<syntaxhighlight lang="typescript">
enum Color {
    red = 1,
    green = 2,
    blue = 4
}

namespace Color {
    export function mixColor(colorName: string) {
        if (colorName == "yellow") {
            return Color.red + Color.green;
        }
        else if (colorName == "white") {
            return Color.red + Color.green + Color.blue;
        }
        else if (colorName == "magenta") {
            return Color.red + Color.blue;
        }
        else if (colorName == "cyan") {
            return Color.green + Color.blue;
        }
    }
}
</syntaxhighlight>
==أنواع الدمج المرفوضة==
لا يُسمح بجميع أنواع الدمج في TypeScript. إذ لا يمكن في الوقت الحالي دمج الأصناف مع أصناف أخرى أو مع المتغيرات. انظر توثيق [[TypeScript/mixins|المخاليط في TypeScript]] للمزيد من المعلومات حول محاكاة دمج الأصناف.

==تنمية الوحدات (Module Augmentation)==
رغم أنّ وحدات  JavaScript لا تدعم الدمج، إلا أنّك تستطيع ترقيع الكائنات الموجودة عبر استيرادها ثمّ تحديثها. لنلق نظرة على مثال مزيّف لنمط Observable:
<syntaxhighlight lang="typescript">
// observable.js
export class Observable<T> {
    // ... التفاصيل لا تهم هنا ...
}

// map.js
import { Observable } from "./observable";
Observable.prototype.map = function (f) {
    // ... تفاصيل آلية العمل غير مهمّة في هذا المثال
}
</syntaxhighlight>
هذا يعمل في TypeScript كذلك، لكن المترجم لا يملك أية معلومات عن ‎<code>Observable.prototype.map</code>‎. يُمكنك الاعتماد على تنمية الوحدات لإعلام المترجم عنها:
<syntaxhighlight lang="typescript">
// يبقى الملفّ
// observable.ts
// كما هو

// map.ts
import { Observable } from "./observable";
declare module "./observable" {
    interface Observable<T> {
        map<U>(f: (x: T) => U): Observable<U>;
    }
}
Observable.prototype.map = function (f) {
    // ... تفاصيل آلية العمل غير مهمّة في هذا المثال
}


// consumer.ts
import { Observable } from "./observable";
import "./map";
let o: Observable<number>;
o.map(x => x.toFixed());
</syntaxhighlight>
يُقرَّر اسم الوحدة بنفس طريقة مُحدِّدات الوحدات في الجملة ‎<code>import</code>‎ والجملة ‎<code>export</code>‎. انظر [[TypeScript/modules|توثيق الوحدات]] للاستزادة. تُدمج التصريحات في تنمية الوحدة وكأنها صُرِّحت في نفس الملف الأصلي. لكن لا يُمكنك التصريح عن تصريحات جديدة في المستوى الأعلى (top-level) في التنمية (يُسمَح فقط بترقيع التصريحات الموجودة أصلًا).

===التنمية العامّة (Global augmentation)===
يُمكن كذلك إضافة التصريحات إلى المجال العام من داخل وحدة معيّنة:
<syntaxhighlight lang="typescript">
// observable.ts
export class Observable<T> {
    // ...
}

declare global {
    interface Array<T> {
        toObservable(): Observable<T>;
    }
}

Array.prototype.toObservable = function () {
    // ...
}
</syntaxhighlight>
تسلك التنميات العامّة نفس سلوك الوحدات وعليها نفس القيود كذلك.
== مصادر ==
* [https://www.typescriptlang.org/docs/handbook/declaration-merging.html صفحة Declaration Merging في توثيق TypeScript الرسمي.]
[[تصنيف:TypeScript]]