معدّلات الوصول في TypeScript: public وprivate وprotected

في TypeScript ثلاثة معدّلات وصول لأعضاء الصنف: public (الافتراضي)، وprotected، وprivate. تتحكم في المواضع التي يمكن فيها استخدام العضو، ويبلّغ المترجم عن أي وصول من الموضع الخاطئ.

class Employee {
    public name: string;          // anywhere (public is the default)
    protected salary: number;     // this class and subclasses
    private ssn: string;          // this class only

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

    maskedSsn(): string {
        return "***-**-" + this.ssn.slice(-4); // fine: inside the class
    }
}

const e = new Employee("Ada", 5000, "123-45-6789");
console.log(e.name, e.maskedSsn()); // Ada ***-**-6789

// @ts-expect-error: Property 'ssn' is private and only accessible within class 'Employee'.
console.log(e.ssn);

السطر الأخير خطأ ترجمة، لكن انظر إلى ما طبعه حين شُغّل رغم ذلك: 123-45-6789. هذه أهم حقيقة في هذه الصفحة، ويشرحها قسم private.

ما يسمح به كل معدّل

تعمل المعدّلات على الحقول والتوابع والـ getters والـ setters ودوال البناء وخصائص المعاملات (constructor(private id: string)). كتابة public اختيارية، وكثير من المشاريع تحذفها.

private فحص وقت الترجمة

تحذف TypeScript المعدّل private مع بقية الأنواع. الصنف المترجم يحتوي على خاصية عادية، فيراها كل ما لا يمر عبر فاحص الأنواع: مستدعو JavaScript العاديون، وJSON.stringify، وObject.keys، بل وصيغة الأقواس المربعة في TypeScript نفسها، المسموحة كمخرج مقصود.

class Session {
    private token = "abc123";
    userId = 7;
}

const s = new Session();
console.log(s["token"]);           // abc123: bracket access skips the check
console.log(Object.keys(s));       // [ 'token', 'userId' ]
console.log(JSON.stringify(s));    // {"token":"abc123","userId":7}

هذا مناسب للغرض الذي وُجد له private: إخبار المطورين الآخرين (ومحررك) بأن العضو تفصيل تنفيذي. إنه ليس حدًا أمنيًا، وسينتهي الحقل private في السجلات واستجابات JSON ما لم تحذفه بنفسك.

حقول #private: تُفرض وقت التشغيل

لـ JavaScript حقولها الخاصة، وتُكتب بـ #. يفرضها المحرك: خارج الصنف لا تكون obj.#field صيغة صالحة أصلًا، ولا يظهر الحقل في Object.keys ولا JSON.stringify ولا console.log.

class Session {
    #token = "abc123";
    userId = 7;

    constructor(token: string) {
        this.#token = token;
    }

    matches(t: string): boolean {
        return this.#token === t;
    }

    static isSession(x: object): boolean {
        return #token in x; // brand check: was x made by this class?
    }
}

const s = new Session("xyz");
console.log(s.matches("xyz"));     // true
console.log(Object.keys(s));       // [ 'userId' ]
console.log(JSON.stringify(s));    // {"userId":7}
console.log(s);                    // Session { userId: 7 }
console.log(Session.isSession(s), Session.isSession({ userId: 7 })); // true false

كتابة s.#token خارج الصنف هي الخطأ TS18013 (Property '#token' is not accessible outside class 'Session' because it has a private identifier)، وعلى خلاف حالة private لا توجد طريقة للالتفاف عليها وقت التشغيل أيضًا. راجع الحقول الخاصة في JavaScript لقواعد وقت التشغيل.

private مقابل #private: أيهما تستخدم

استخدم #private حين يجب أن تبقى البيانات خاصة وقت التشغيل (الرموز المميزة، والحالة الداخلية التي لا يجوز لمستخدمي مكتبة لمسها)، أو حين تريد أن يتجاهلها JSON.stringify. واستخدم private حين يكون الهدف مجرد واجهة عامة نظيفة، أو حين يحتاج إطار عمل إلى قراءة الحقل بالانعكاس (reflection)، أو لمطابقة الأسلوب القائم في المشروع. لا تجمع بينهما: private #x هو الخطأ TS18010 (An accessibility modifier cannot be used with a private identifier).

protected والأصناف الفرعية

العضو protected متاح داخل الصنف وفي أي صنف يرث منه، لكن ليس على النسخ من الخارج.

class Shape {
    protected sides: number;

    constructor(sides: number) {
        this.sides = sides;
    }
}

class Polygon extends Shape {
    describe(): string {
        return `${this.sides} sides`; // fine: subclass
    }
}

const hex = new Polygon(6);
console.log(hex.describe()); // 6 sides

// @ts-expect-error: Property 'sides' is protected and only accessible within class 'Shape' and its subclasses.
console.log(hex.sides); // 6: like private, protected is not enforced at runtime

قاعدة واحدة تفاجئ الناس. داخل Polygon يمكنك قراءة sides على this أو على Polygon آخر، لكن ليس على Shape عادي يُمرَّر كمعامل: other.sides حيث other: Shape هو الخطأ TS2446 (Property 'sides' is protected and only accessible through an instance of class 'Polygon'. This is an instance of class 'Shape'.). لا يصل الصنف الفرعي إلى الأعضاء المحمية إلا في الكائنات التي تنتمي إلى فرعه من الهرمية.

يمكن للصنف الفرعي أن يجعل عضوًا محميًا عامًا بإعادة تعريفه، لكنه لا يستطيع أن يجعل عضوًا عامًا محميًا أو خاصًا. أعد تعريفه بقيمة ابتدائية (public override sides = 6) أو كنوع فقط (declare public sides: number). أما public sides: number; المجرد فيُرفض بالخطأين TS2564 وTS2612، لأنه مع حقول الأصناف الحديثة سيعيد ضبط القيمة الموروثة إلى undefined بعد عودة super().

readonly

يمنع readonly إعادة الإسناد بعد الإنشاء. يمكن ضبط الحقل في تعريفه أو في دالة البناء؛ وأي إسناد لاحق هو الخطأ TS2540.

class Order {
    readonly id: string;
    readonly items: string[] = [];

    constructor(id: string) {
        this.id = id; // allowed: inside the constructor
    }
}

const order = new Order("A-17");
order.items.push("book"); // allowed: readonly is shallow
console.log(order);       // Order { id: 'A-17', items: [ 'book' ] }

// @ts-expect-error: Cannot assign to 'id' because it is a read-only property.
order.id = "B-1";
console.log(order.id);    // B-1: nothing stops it at runtime

يظهر هنا حدّان. readonly سطحي: لا يمكن استبدال المصفوفة، لكن محتواها يمكن أن يتغير (اجعل نوعها readonly string[] لمنع push). ومثل private يختفي وقت التشغيل، فالإسناد الذي رفضه المترجم نُفّذ رغم ذلك. للقيمة التي يجب ألا تتغير وقت التشغيل استخدم Object.freeze أو getter بلا setter. تشرح صفحة readonly النوع Readonly<T> والمصفوفات للقراءة فقط.

يجتمع readonly مع معدّلات الوصول: private readonly cache = new Map<string, number>() نمط شائع لحقل داخلي لا يُعاد إسناده أبدًا.

أخطاء شائعة

• معاملة private كأداة أمان. يختفي وقت التشغيل. استخدم #field للبيانات التي يجب أن تبقى مخفية، ولا ترسل أبدًا كائنًا يحمل أسرارًا مباشرة إلى JSON.stringify.
• كتابة public في كل مكان. إنه الافتراضي؛ وإضافته لا تغيّر شيئًا.
• استخدام protected لكل ما هو «داخلي». إن لم يحتجه أي صنف فرعي، فإن private يُبقي الواجهة أصغر.
• توقّع أن يجمّد readonly البيانات المتداخلة. إنه يمنع فقط إعادة إسناد الخاصية نفسها.