دالة البناء (Constructor) في TypeScript: خصائص المعاملات والتحميل

دالة البناء في TypeScript هي التابع constructor في الصنف مع معاملات بأنواع محددة. ليس لها توصيف لنوع القيمة المُعادة: فهي تنتج دائمًا نسخة من الصنف.

class Product {
    name: string;
    price: number;

    constructor(name: string, price: number) {
        this.name = name;
        this.price = price;
    }
}

const p = new Product("Lamp", 39);
console.log(p); // Product { name: 'Lamp', price: 39 }

// @ts-expect-error: Expected 2 arguments, but got 1.
new Product("Chair");

كتابة constructor(): Product هي الخطأ TS1093 (Type annotation cannot appear on a constructor declaration). وكل ما عدا ذلك في طريقة عمل new هو JavaScript عادية.

خصائص المعاملات

النمط السابق (تعريف حقل، واستقبال معامل، ونسخه إلى الحقل) شائع جدًا حتى إن لـ TypeScript اختصارًا له. ضع public أو private أو protected أو readonly قبل معامل دالة البناء فيصبح حقلًا:

class Product {
    constructor(
        public name: string,
        private price: number,
        readonly sku: string,
    ) {}

    label(): string {
        return `${this.name} (${this.sku}): $${this.price}`;
    }
}

const lamp = new Product("Lamp", 39, "LMP-1");
console.log(lamp.label()); // Lamp (LMP-1): $39
console.log(lamp.name, lamp.sku); // Lamp LMP-1
// lamp.price is private: accessing it outside the class is a compile error

هذه من الميزات القليلة في TypeScript التي تولّد كودًا. يكتب المترجم عمليات الإسناد نيابة عنك:

class Product {
    name;
    price;
    sku;
    constructor(name, price, sku) {
        this.name = name;
        this.price = price;
        this.sku = sku;
    }
    // ...
}

ولأنها ليست مجرد أنواع تُحذف، لا تعمل خصائص المعاملات مع إزالة الأنواع المدمجة في Node (يفشل node file.ts بالخطأ ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX)، ويبلّغ عنها خيار المترجم erasableSyntaxOnly بالخطأ TS1294. المشاريع التي تشغّل ملفات .ts مباشرة تكتب الحقول يدويًا.

المعاملات الاختيارية والافتراضية

تتبع معاملات دالة البناء قواعد معاملات الدوال نفسها: ? تجعل المعامل اختياريًا، والقيمة الافتراضية تجعله اختياريًا وتملؤه، والمعاملات المطلوبة تأتي أولًا.

class Logger {
    constructor(
        readonly prefix: string,
        readonly level: "info" | "debug" = "info",
        readonly color?: string,
    ) {}
}

console.log(new Logger("app"));
// Logger { prefix: 'app', level: 'info', color: undefined }
console.log(new Logger("db", "debug", "blue"));
// Logger { prefix: 'db', level: 'debug', color: 'blue' }

يمكن أن يكون لخصائص المعاملات قيم افتراضية أيضًا. نوع color داخل الصنف هو string | undefined، فيجب على الكود الذي يستخدمه أن يفحص undefined أولًا.

لدوال البناء ذات الخيارات الكثيرة، كائن خيارات واحد أسهل قراءة من قائمة موضعية طويلة: constructor(opts: { prefix: string; level?: "info" | "debug" }).

ترتيب تهيئة الحقول

تعمل القيم الابتدائية للحقول قبل جسم دالة البناء، وتُسند خصائص المعاملات في بداية جسم دالة البناء. لذلك لا تستطيع القيمة الابتدائية لحقل أن تقرأ خاصية معامل. وتكتشف TypeScript ذلك:

// This does not compile: the initializer reads `size` too early.
class Grid {
    cells = this.size * this.size;

    constructor(public size: number) {}
}

console.log(new Grid(3).cells);

index.ts(3,18): error TS2729: Property 'size' is used before its initialization.
index.ts(3,30): error TS2729: Property 'size' is used before its initialization.

وقت التشغيل كانت القيمة الابتدائية سترى undefined وتنتج NaN. احسب القيمة في جسم دالة البناء بدلًا من ذلك:

class Grid {
    cells: number;

    constructor(public size: number) {
        this.cells = size * size;
    }
}

console.log(new Grid(3).cells); // 9

تحميل دالة البناء

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

class Color {
    r: number;
    g: number;
    b: number;

    constructor(hex: string);
    constructor(r: number, g: number, b: number);
    constructor(a: string | number, g = 0, b = 0) {
        if (typeof a === "string") {
            const n = parseInt(a.replace("#", ""), 16);
            this.r = (n >> 16) & 255;
            this.g = (n >> 8) & 255;
            this.b = n & 255;
        } else {
            this.r = a;
            this.g = g;
            this.b = b;
        }
    }
}

console.log(new Color("#ff8800")); // Color { r: 255, g: 136, b: 0 }
console.log(new Color(10, 20, 30)); // Color { r: 10, g: 20, b: 30 }
// new Color(10, 20) is an error: no overload takes 2 arguments

يصعب قراءة التحميل بعد شكلين أو ثلاثة. توابع المصنع الثابتة ذات الأسماء الواضحة (Color.fromHex("#ff8800")، Color.fromRgb(10, 20, 30)) كثيرًا ما تكون أوضح ولا تحتاج إلى تضييق الأنواع داخل جسم واحد.

استدعاء super في صنف فرعي

الصنف المشتق الذي يعرّف دالة بناء خاصة به يجب أن يستدعي super(...) بوسائط الصنف الأب، وأن يفعل ذلك قبل استخدام this. نسيان الاستدعاء هو الخطأ TS2377 (Constructors for derived classes must contain a 'super' call)، واستخدام this أولًا هو TS17009 ('super' must be called before accessing 'this' in the constructor of a derived class). وكلاهما يعكس قواعد JavaScript وقت التشغيل.

class Animal {
    constructor(public name: string) {}
}

class Dog extends Animal {
    tricks: string[];

    constructor(name: string, ...tricks: string[]) {
        super(name); // must come first
        this.tricks = tricks;
    }
}

const rex = new Dog("Rex", "sit", "roll");
console.log(rex); // Dog { name: 'Rex', tricks: [ 'sit', 'roll' ] }

الصنف الفرعي الذي لا يضيف دالة بناء يرث دالة الأب بأنواع المعاملات نفسها. المزيد عن الأصناف الفرعية في الوراثة.

دوال البناء الخاصة والتهيئة غير المتزامنة

لا يمكن استدعاء دالة بناء private إلا من داخل الصنف. أما من خارجه فـ new هو الخطأ TS2673. هكذا تُجبر المستدعين على المرور عبر مصنع، لنمط singleton أو لتهيئة يجب أن تكون غير متزامنة (دوال البناء لا يمكن أن تكون async).

class Connection {
    private constructor(readonly url: string, readonly version: number) {}

    static async open(url: string): Promise<Connection> {
        const version = await Promise.resolve(3); // stands in for a real handshake
        return new Connection(url, version);
    }
}

async function main() {
    const conn = await Connection.open("db://local");
    console.log(conn.url, conn.version); // db://local 3
}
main();

private هنا قاعدة وقت الترجمة فقط. يحتوي JavaScript الناتج على دالة بناء عادية، فيستطيع كود JavaScript عادي أن يستدعي new Connection(...).

أنواع دوال البناء

لقبول صنف كقيمة، حدد نوع المعامل بتوقيع إنشاء: new (...args) => Instance. يعمل typeof MyClass أيضًا، لكنه يربط المعامل بتوقيع دالة البناء والأعضاء الثابتة لذلك الصنف وحده.

class Circle {
    constructor(public r: number) {}
}
class Square {
    constructor(public r: number) {}
}

type ShapeCtor<T> = new (size: number) => T;

function makeAll<T>(ctor: ShapeCtor<T>, sizes: number[]): T[] {
    return sizes.map((s) => new ctor(s));
}

console.log(makeAll(Circle, [1, 2])); // [ Circle { r: 1 }, Circle { r: 2 } ]
console.log(makeAll(Square, [5]));    // [ Square { r: 5 } ]

type CircleArgs = ConstructorParameters<typeof Circle>; // [r: number]
const args: CircleArgs = [7];
console.log(new Circle(...args)); // Circle { r: 7 }

يستخرج ConstructorParameters وInstanceType الـ tuple الخاص بالمعاملات ونوع النسخة من نوع دالة بناء؛ وهما مشروحان مع بقية أدوات الدوال في ReturnType وParameters.