Typy obiektowe w TypeScript: właściwości opcjonalne i readonly

Typ obiektowy w TypeScript wymienia właściwości obiektu i typ każdej z nich: { name: string; age: number }. Dodaj ?, żeby właściwość była opcjonalna, i readonly, żeby zablokować ponowne przypisanie. Zapisz typ inline albo nazwij go przez type lub interface, żeby używać go wielokrotnie.

// 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

Zapisywanie typów obiektowych

Właściwości oddziela się ; lub , (działają oba, ; to zwyczajowy styl), a sam znak nowej linii też wystarcza. Typ inline sprawdza się przy jednorazowym parametrze; wszystko, czego używasz dwa razy, warto nazwać.

// 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 i interface równie dobrze opisują kształty obiektów. Różnice (łączenie deklaracji, unie) omawia strona interface vs type.

Dostęp do właściwości, której typ nie deklaruje, to błąd kompilacji: point.z daje TS2339, Property 'z' does not exist on type '{ x: number; y: number; }'.

Właściwości opcjonalne

? po nazwie pozwala pominąć właściwość. Odczyt właściwości opcjonalnej daje T | undefined, więc TypeScript każe ci obsłużyć przypadek braku, zanim jej użyjesz.

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

Wywołanie metody na właściwości opcjonalnej bez sprawdzenia to błąd: p.nickname.toUpperCase() kończy się TS18048, 'p.nickname' is possibly 'undefined'. Użyj optional chaining (p.nickname?.toUpperCase()), gdy undefined to akceptowalny wynik.

prop?: T i prop: T | undefined to nie to samo. Pierwsze pozwala, by klucza nie było; drugie wymaga klucza, choć jego wartość może być 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 } {}

Właściwości readonly

readonly blokuje ponowne przypisanie właściwości po utworzeniu obiektu. To tylko sprawdzenie podczas kompilacji i jest płytkie: obiekt lub tablicę zapisaną we właściwości readonly nadal można zmieniać od środka.

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' }

Wynik pokazuje oba ograniczenia: id naprawdę zmieniło się w czasie działania (tylko kompilator wiedział, że jest readonly), a tablica w środku została zmodyfikowana. Dla tablicy tylko do odczytu użyj readonly string[]; żeby wszystkie właściwości naraz były readonly, użyj Readonly<Order>.

Sprawdzanie nadmiarowych właściwości

Gdy przypisujesz literał obiektu bezpośrednio do otypowanej zmiennej albo przekazujesz go wprost do otypowanego parametru, TypeScript odrzuca każdą właściwość, której typ nie deklaruje. Dodatkowe właściwości w świeżym literale to prawie zawsze literówki.

// 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'?

Kod błędu to TS2561, bo kompilator znalazł bliskie dopasowanie; dodatkowa właściwość bez podobnej nazwy daje TS2353, Object literal may only specify known properties, and 'z' does not exist in type 'Point'. Bez tego sprawdzenia literówka by się skompilowała, color byłoby undefined, a program po cichu rysowałby na czarno. Sprawdzenie dotyczy tylko świeżych literałów. Obiekt, który już jest w zmiennej, może mieć dodatkowe właściwości, bo typowanie w TypeScript jest strukturalne: wartość pasuje do typu, gdy ma co najmniej wymagane właściwości.

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

Zagnieżdżone obiekty i metody

Typy obiektowe można zagnieżdżać, a metody opisuje się składnią metody albo właściwością o typie funkcji.

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);

Przy głębokich lub wielokrotnie używanych kształtach nazwij typ wewnętrzny (type Address = { ... }) i odwołuj się do niego albo wyciągnij go z typu zewnętrznego przez indexed access, Company["address"], jak w ostatnich liniach.

object a {} a Object

Trzy typy brzmią podobnie, a znaczą co innego:

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);

{} nie oznacza "pustego obiektu"; oznacza "nie null i nie undefined". Aby przyjąć dowolny obiekt o nieznanych kluczach, użyj Record<string, unknown>; dla mapy kluczy na wartości użyj sygnatury indeksu albo Record, jak na stronie dictionary. W większości przypadków konkretny kształt jest lepszy niż każdy z tych trzech.