أنواع الكائنات في TypeScript: الخصائص الاختيارية وreadonly

يسرد نوع الكائن في TypeScript الخصائص التي يملكها الكائن ونوع كل منها: { name: string; age: number }. أضف ? لجعل خاصية اختيارية وreadonly لمنع إعادة إسنادها. اكتب النوع مضمّنًا، أو سمّه بـ type أو interface لإعادة استخدامه.

// Inline object type
let point: { x: number; y: number } = { x: 3, y: 4 };

// Named object type with optional and readonly properties
type User = {
    readonly id: number;
    name: string;
    email?: string; // optional: may be missing
};

const ada: User = { id: 1, name: "Ada" };
const grace: User = { id: 2, name: "Grace", email: "grace@example.com" };

console.log(point.x + point.y);           // 7
console.log(ada.email ?? "no email");      // no email
console.log(grace.email?.toUpperCase());   // GRACE@EXAMPLE.COM

كتابة أنواع الكائنات

تُفصل الخصائص بـ ; أو , (كلاهما يعمل، و; الأسلوب المعتاد)، وفاصل السطر وحده يكفي. النوع المضمّن مناسب لمعامل يُستخدم مرة واحدة؛ ولكل ما يُستخدم مرتين، أعطه اسمًا.

// Inline, in a parameter
function area(rect: { width: number; height: number }): number {
    return rect.width * rect.height;
}

// Named with a type alias
type Rect = { width: number; height: number };

// Named with an interface (the same shape)
interface RectShape {
    width: number;
    height: number;
}

يصف type وinterface أشكال الكائنات بالكفاءة نفسها. الفروق بينهما (دمج التصريحات وunion) مشروحة في صفحة interface مقابل type.

الوصول إلى خاصية لا يعلنها النوع خطأ ترجمة: point.z يعطي TS2339، Property 'z' does not exist on type '{ x: number; y: number; }'.

الخصائص الاختيارية

علامة ? بعد الاسم تسمح بترك الخاصية. قراءة خاصية اختيارية تعطي T | undefined، لذلك تجبرك TypeScript على معالجة حالة الغياب قبل استخدامها.

type Profile = {
    name: string;
    nickname?: string;
    age?: number;
};

function greet(p: Profile): string {
    // p.nickname is string | undefined
    const shown = p.nickname ?? p.name;         // default with ??
    const ageText = p.age !== undefined ? ` (${p.age})` : ""; // or check
    return `Hi, ${shown}${ageText}`;
}

console.log(greet({ name: "Ada" }));                        // Hi, Ada
console.log(greet({ name: "Grace", nickname: "Amazing Grace", age: 85 }));
console.log("age" in { name: "Ada" });                      // false

استدعاء دالة على خاصية اختيارية دون فحص خطأ: p.nickname.toUpperCase() يفشل بالخطأ TS18048، 'p.nickname' is possibly 'undefined'. استخدم optional chaining (p.nickname?.toUpperCase()) عندما تكون undefined نتيجة مقبولة.

prop?: T وprop: T | undefined ليسا الشيء نفسه. الأول يسمح بغياب المفتاح؛ والثاني يشترط وجود المفتاح، وإن كانت قيمته قد تكون undefined:

type A = { note?: string };
type B = { note: string | undefined };

const a1: A = {};                    // fine: key left out
const b1: B = { note: undefined };   // fine: key present
// @ts-expect-error: Property 'note' is missing in type '{}' but required in type 'B'.
const b2: B = {};

console.log(a1, b1, b2); // {} { note: undefined } {}

خصائص readonly

يمنع readonly إعادة إسناد الخاصية بعد إنشاء الكائن. إنه فحص وقت الترجمة فقط، وهو سطحي: الكائن أو المصفوفة المخزنة في خاصية readonly يمكن تغيير محتواها.

type Order = {
    readonly id: string;
    readonly items: string[];
    status: "open" | "paid";
};

const order: Order = { id: "A-17", items: ["tea"], status: "open" };

order.status = "paid"; // fine
// @ts-expect-error: Cannot assign to 'id' because it is a read-only property.
order.id = "B-2";
order.items.push("cake"); // allowed: readonly is shallow

console.log(order); // { id: 'B-2', items: [ 'tea', 'cake' ], status: 'paid' }

يُظهر الناتج الحدين معًا: تغيّر id فعلًا وقت التشغيل (لم يكن يعرف أنه readonly إلا المترجم)، وعُدّلت المصفوفة الداخلية. للمصفوفة للقراءة فقط استخدم readonly string[]؛ ولجعل كل الخصائص readonly دفعة واحدة، استخدم Readonly<Order>.

فحص الخصائص الزائدة

عندما تُسند كائنًا حرفيًا مباشرة إلى متغير له نوع أو تمرره مباشرة إلى معامل له نوع، ترفض TypeScript أي خاصية لا يعلنها النوع. الخصائص الإضافية في كائن حرفي جديد أخطاء إملائية في أغلب الأحيان.

// This does not compile: 'colour' is not a property of Options.
type Options = { color?: string; size?: number };

function draw(opts: Options) {
    console.log(opts.color ?? "black", opts.size ?? 1);
}

draw({ colour: "red", size: 2 });

index.ts(8,8): error TS2561: Object literal may only specify known properties, but 'colour' does not exist in type 'Options'. Did you mean to write 'color'?

رمز الخطأ TS2561 لأن المترجم وجد اسمًا قريبًا؛ أما الخاصية الإضافية التي ليس لها اسم مشابه فتعطي TS2353، Object literal may only specify known properties, and 'z' does not exist in type 'Point'. دون هذا الفحص كان الخطأ الإملائي سيُترجم، وستكون color هي undefined، وسيرسم البرنامج بالأسود بصمت. ينطبق الفحص على الكائنات الحرفية الجديدة فقط. الكائن الموجود أصلًا في متغير يمكن أن يحمل خصائص إضافية، لأن الأنواع في TypeScript بنيوية: القيمة تناسب النوع عندما تملك الخصائص المطلوبة على الأقل.

type Point = { x: number; y: number };

const point3d = { x: 1, y: 2, z: 3 };
const p: Point = point3d; // fine: point3d has x and y

function show(pt: Point) {
    console.log(pt.x, pt.y);
}
show(point3d); // 1 2

الكائنات المتداخلة والدوال

تتداخل أنواع الكائنات، ويمكنها وصف الدوال إما بصياغة method أو بخاصية نوعها دالة.

type Company = {
    name: string;
    address: {
        city: string;
        zip?: string;
    };
    tags: string[];
    describe(): string;                  // method syntax
    rename: (newName: string) => void;   // function property
};

const acme: Company = {
    name: "Acme",
    address: { city: "Berlin" },
    tags: ["b2b"],
    describe() {
        return `${this.name} in ${this.address.city}`;
    },
    rename(newName) {
        this.name = newName;
    },
};

acme.rename("Acme GmbH");
console.log(acme.describe());               // Acme GmbH in Berlin
console.log(acme.address.zip ?? "no zip");  // no zip

type Address = Company["address"]; // reuse a nested type by indexing
const home: Address = { city: "Paris", zip: "75001" };
console.log(home);

للأشكال العميقة أو المعاد استخدامها، سمِّ النوع الداخلي (type Address = { ... }) وأشر إليه، أو استخرجه من النوع الخارجي بـ indexed access، Company["address"]، كما تفعل الأسطر الأخيرة.

object مقابل {} مقابل Object

ثلاثة أنواع متشابهة في الاسم وتعني أشياء مختلفة:

const a: object = { id: 1 };
const b: object = [1, 2];
const c: {} = 42;          // allowed: {} does not mean "empty object"
const d: {} = "text";      // allowed too

// @ts-expect-error: Type 'number' is not assignable to type 'object'.
const e: object = 42;

console.log(a, b, c, d, e);

لا يعني {} «كائنًا فارغًا»؛ بل يعني «ليس null ولا undefined». لقبول أي كائن بمفاتيح غير معروفة، استخدم Record<string, unknown>؛ ولخريطة من المفاتيح إلى القيم، استخدم index signature أو Record كما في صفحة القاموس. وفي أغلب الأحيان يكون الشكل المحدد أفضل من الثلاثة كلها.