عرض مصدر TypeScript/declaration files/by example

<noinclude>{{DISPLAYTITLE:ملفات التصريحات اعتمادًا على الأمثلة في TypeScript}}</noinclude>

==مقدمة==
الهدف من هذا الدليل هو تعليمك كيفيّة كتابة ملف تعريف عالي الجودة. هذا الدليل يريك أولًا توثيق واجهة برمجية (API) معيّنة مع طريقة استعمالها، ثم يشرح كيفية كتابة التصريح الملائم.

هذه الأمثلة مرتبة تصاعديا حسب التعقيد، من الأبسط إلى الأعقد:

* المتغيرات العامة (Global Variables). 
* الدوال العامة (Global Functions).
* الكائنات ذات الخاصيات.
* الدوال ذات الأحمال الزائدة (Overloaded Functions).
* الأنواع القابلة لإعادة الاستخدام (الواجهات).
*  الأنواع القابلة لإعادة الاستخدام (أسماء الأنواع البديلة [Type Aliases]).
* تنظيم الأنواع.
* الأصناف.

==الأمثلة==
===المتغيرات العامة===
'''التوثيق:'''

يحتوي المتغير العام ‎<code>foo</code>‎ على عدد الأدوات (widgets) الموجودة.

'''الشيفرة:'''
<syntaxhighlight lang="typescript">
console.log("Half the number of widgets is " + (foo / 2));
</syntaxhighlight>

'''التصريح:'''

استعمل ‎<code>declare var</code>‎ للتصريح عن المتغيرات. إذا كان المتغير قابلًا للقراءة فقط (read-only) فيُمكنك استعمال ‎<code>declare const</code>‎. يمكنك كذلك استعمال ‎<code>declare let</code>‎ إذا كان المتغير محصورًا داخل كتلة (block-scoped).
<syntaxhighlight lang="typescript">
/** عدد الأدوات الموجودة */
declare var foo: number;
</syntaxhighlight>
===الدوال العامة===
'''التوثيق:'''

يمكنك استدعاء الدالة ‎<code>greet</code>‎ مع تمرير سلسلة نصية لإظهار ترحيب للمستخدم.

'''الشيفرة:'''
<syntaxhighlight lang="typescript">
greet("hello, world");
</syntaxhighlight>

'''التصريح:'''

استعمل ‎<code>declare function</code>‎ للتصريح عن الدوال:
<syntaxhighlight lang="typescript">
declare function greet(greeting: string): void;
</syntaxhighlight>
===الكائنات ذات الخاصيات===
'''التوثيق:'''

لدى المتغير العام ‎<code>myLib</code>‎ دالةٌ باسم ‎<code>makeGreeting</code>‎ لإنشاء الترحيبات، وخاصيّة باسم ‎<code>numberOfGreetings</code>‎ تشير إلى عدد الترحيبات التي تمّت إلى الآن.

'''الشيفرة:'''
<syntaxhighlight lang="typescript">
let result = myLib.makeGreeting("hello, world");
console.log("The computed greeting is:" + result);

let count = myLib.numberOfGreetings;
</syntaxhighlight>

'''التصريح:'''

استعمل ‎<code>declare namespace</code>‎ لوصف الأنواع أو القيم التي يمكن الوصول إليها عبر النقطة (‎<code>.</code>‎).
<syntaxhighlight lang="typescript">
declare namespace myLib {
    function makeGreeting(s: string): string;
    let numberOfGreetings: number;
}
</syntaxhighlight>
===الدوال ذات الأحمال الزائدة===
'''التوثيق:'''

تستقبل الدالة ‎<code>getWidget</code>‎ عددًا وتُعيد كائنًا من النوع ‎<code>Widget</code>‎، أو تستقبل سلسلة نصية وتعيد مصفوفة تحتوي على عدّة كائنات من النوع ‎<code>Widget</code>‎.

'''الشيفرة:'''
<syntaxhighlight lang="typescript">
let x: Widget = getWidget(43);

let arr: Widget[] = getWidget("all of them");
</syntaxhighlight>
'''التصريح:'''
<syntaxhighlight lang="typescript">
declare function getWidget(n: number): Widget;
declare function getWidget(s: string): Widget[];
</syntaxhighlight>
===الأنواع القابلة لإعادة الاستخدام (الواجهات)===
'''التوثيق:'''

عند تحديد ترحيب معيّن، يجب عليك تمرير كائن من النوع ‎<code>GreetingSettings</code>‎، يمتلك هذا الكائن الخاصيات التاليّة:
# ‎<code>greeting</code>‎: سلسلة نصية مطلوبة تمثل الترحيب.
# ‎<code>duration</code>‎: عدد اختياري يمثل الزمن (بالمللي ثانية).
# ‎<code>color</code>‎: سلسلة نصية اختيارية تمثل اللون ( مثل ‎<code>#ff00ff</code>‎).

'''الشيفرة:'''
<syntaxhighlight lang="typescript">
greet({
  greeting: "hello world",
  duration: 4000
});
</syntaxhighlight>
'''التصريح:'''

استعمل واجهةً ‎<code>interface</code>‎ لتعريف نوعٍ وخاصياته:
<syntaxhighlight lang="typescript">
interface GreetingSettings {
  greeting: string;
  duration?: number;
  color?: string;
}

declare function greet(setting: GreetingSettings): void;
</syntaxhighlight>
===الأنواع القابلة لإعادة الاستخدام (أسماء الأنواع البديلة)===
'''التوثيق:'''

يمكنك تمرير سلسلةٍ نصيّة، أو دالةٍ تعيد سلسلة نصية، أو تمريرُ نسخةٍ من ‎<code>Greeter</code>‎ في أي مكان يقبل ترحيبًا.

'''الشيفرة:'''
<syntaxhighlight lang="typescript">
function getGreeting() {
    return "howdy";
}
class MyGreeter extends Greeter { }

greet("hello");
greet(getGreeting);
greet(new MyGreeter());
</syntaxhighlight>
'''التصريح:'''

يمكنك استخدام تسميات الأنواع البديلة لإنشاء اختصارٍ لنوعٍ ما:
<syntaxhighlight lang="typescript">
type GreetingLike = string | (() => string) | MyGreeter;

declare function greet(g: GreetingLike): void;
</syntaxhighlight>
===تنظيم الأنواع===
'''التوثيق:'''

يمكن أن يُسجّل (log) الكائن ‎<code>greeter</code>‎ إلى ملفّ أو يعرضَ تنبيهًا (alert). يمكنك توفير إعدادات التسجيل إلى ‎<code>.log(...)‎</code>‎ وإعدادات التنبيه إلى ‎<code>.alert(...)‎</code>‎.

'''الشيفرة:'''
<syntaxhighlight lang="typescript">
const g = new Greeter("Hello");
g.log({ verbose: true });
g.alert({ modal: false, title: "Current Greeting" });
</syntaxhighlight>
'''التصريح:'''

استعمل مجالات الأسماء لتنظيم الأنواع:
<syntaxhighlight lang="typescript">
declare namespace GreetingLib {
    interface LogOptions {
        verbose?: boolean;
    }
    interface AlertOptions {
        modal: boolean;
        title?: string;
        color?: string;
    }
}
</syntaxhighlight>
يمكنك كذلك إنشاء مجالات أسماء متداخلة في تصريح واحد:
<syntaxhighlight lang="typescript">
declare namespace GreetingLib.Options {
    // يُشار إلى الواجهة بالنقاط كما يلي
    // GreetingLib.Options.Log
    interface Log {
        verbose?: boolean;
    }
    interface Alert {
        modal: boolean;
        title?: string;
        color?: string;
    }
}
</syntaxhighlight>

===الأصناف===
'''التوثيق:'''

يمكنك إنشاء مُرحِّبٍ عبر إنشاء نسخة من الكائن ‎<code>Greeter</code>‎، أو يمكنك إنشاء مرحّبٍ مخصّص عبر توسيعه.

'''الشيفرة:'''
<syntaxhighlight lang="typescript">
const myGreeter = new Greeter("hello, world");
myGreeter.greeting = "howdy";
myGreeter.showGreeting();

class SpecialGreeter extends Greeter {
    constructor() {
        super("Very special greetings");
    }
}
</syntaxhighlight>
'''التصريح:'''

استعمل ‎<code>declare class</code>‎ لوصف صنفٍ أو كائن شبيه بالأصناف (class-like object). يمكن للأصناف أن تحتوي على خاصيات وتوابع، إضافةً إلى الدوال البانية:
<syntaxhighlight lang="typescript">
declare class Greeter {
    constructor(greeting: string);

    greeting: string;
    showGreeting(): void;
}
</syntaxhighlight>

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