TypeScript/declaration files/by example

مقدمة

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

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

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

الأمثلة

المتغيرات العامة

التوثيق:

يحتوي المتغير العام ‎foo‎ على عدد الإضافات الموجودة.

الشيفرة:

console.log("Half the number of widgets is " + (foo / 2));

التصريح:

استعمل ‎declare var‎ للتصريح عن المتغيرات. إذا كان المتغير قابلًا للقراءة فقط (read-only) فيُمكنك استعمال ‎declare const‎. يمكنك كذلك استعمال ‎declare let‎ إذا كان المتغير محصورًا داخل كتلة (block-scoped).

/** عدد الإضافات الموجودة */
declare var foo: number;

الدوال العامة

التوثيق:

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

الشيفرة:

greet("hello, world");

التصريح:

استعمل ‎declare function‎ للتصريح عن الدوال:

declare function greet(greeting: string): void;

الكائنات ذات الخاصيات

التوثيق:

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

الشيفرة:

let result = myLib.makeGreeting("hello, world");
console.log("The computed greeting is:" + result);

let count = myLib.numberOfGreetings;

التصريح:

استعمل ‎declare namespace‎ لوصف الأنواع أو القيم التي يمكن الوصول إليها عبر النقطة (‎.‎).

declare namespace myLib {
    function makeGreeting(s: string): string;
    let numberOfGreetings: number;
}

الدوال ذات الأحمال الزائدة

التوثيق:

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

الشيفرة:

let x: Widget = getWidget(43);

let arr: Widget[] = getWidget("all of them");

التصريح:

declare function getWidget(n: number): Widget;
declare function getWidget(s: string): Widget[];

الأنواع القابلة لإعادة الاستخدام (الواجهات)

التوثيق:

عند تحديد ترحيب معيّن، يجب عليك تمرير كائن من النوع ‎GreetingSettings‎، يمتلك هذا الكائن الخاصيات التاليّة:

1. ‎greeting‎: سلسلة نصية مطلوبة تمثل الترحيب.
2. ‎duration‎: عدد اختياري يمثل الزمن (بالمللي ثانية).
3. ‎color‎: سلسلة نصية اختيارية تمثل اللون ( مثل ‎#ff00ff‎).

الشيفرة:

greet({
  greeting: "hello world",
  duration: 4000
});

التصريح:

استعمل واجهةً ‎interface‎ لتعريف نوعٍ وخاصياته:

interface GreetingSettings {
  greeting: string;
  duration?: number;
  color?: string;
}

declare function greet(setting: GreetingSettings): void;

الأنواع القابلة لإعادة الاستخدام (أسماء الأنواع البديلة)

التوثيق:

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

الشيفرة:

function getGreeting() {
    return "howdy";
}
class MyGreeter extends Greeter { }

greet("hello");
greet(getGreeting);
greet(new MyGreeter());

التصريح:

يمكنك استخدام تسميات الأنواع البديلة لإنشاء اختصارٍ لنوعٍ ما:

type GreetingLike = string | (() => string) | MyGreeter;

declare function greet(g: GreetingLike): void;

تنظيم الأنواع

التوثيق:

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

الشيفرة:

const g = new Greeter("Hello");
g.log({ verbose: true });
g.alert({ modal: false, title: "Current Greeting" });

التصريح:

استعمل مجالات الأسماء لتنظيم الأنواع:

declare namespace GreetingLib {
    interface LogOptions {
        verbose?: boolean;
    }
    interface AlertOptions {
        modal: boolean;
        title?: string;
        color?: string;
    }
}

يمكنك كذلك إنشاء مجالات أسماء متداخلة في تصريح واحد:

declare namespace GreetingLib.Options {
    // يُشار إلى الواجهة بالنقاط كما يلي
    // GreetingLib.Options.Log
    interface Log {
        verbose?: boolean;
    }
    interface Alert {
        modal: boolean;
        title?: string;
        color?: string;
    }
}

الأصناف

التوثيق:

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

الشيفرة:

const myGreeter = new Greeter("hello, world");
myGreeter.greeting = "howdy";
myGreeter.showGreeting();

class SpecialGreeter extends Greeter {
    constructor() {
        super("Very special greetings");
    }
}

التصريح:

استعمل ‎declare class‎ لوصف صنفٍ أو كائن شبيه بالأصناف (class-like object). يمكن للأصناف أن تحتوي على خاصيات وتوابع، إضافةً إلى الدوال البانية:

declare class Greeter {
    constructor(greeting: string);

    greeting: string;
    showGreeting(): void;
}

مصادر

• صفحة By Example في توثيق TypeScript الرسمي.