Interfejsy w TypeScript: składnia, pola opcjonalne, metody

Interfejs nadaje nazwę kształtowi obiektu: właściwościom, które musi mieć, i typowi każdej z nich. Po zadeklarowaniu używasz tej nazwy jako typu, a kompilator sprawdza względem niej każdy obiekt, który przekazujesz, zwracasz albo przypisujesz.

interface User {
  id: number;
  name: string;
  email?: string; // optional
}

function describe(user: User): string {
  return `#${user.id} ${user.name} <${user.email ?? "no email"}>`;
}

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

console.log(describe(ada));                       // #1 Ada Lovelace <ada@example.com>
console.log(describe({ id: 2, name: "Alan Turing" })); // #2 Alan Turing <no email>

// @ts-expect-error: Property 'name' is missing in type '{ id: number; }' but required in type 'User'.
describe({ id: 3 });

Ostatnie wywołanie to błąd kompilacji TS2741. Interfejsy są usuwane podczas kompilacji kodu: w wynikowym JavaScripcie nie ma śladu User i nic nie sprawdza kształtu w czasie działania.

Deklarowanie interfejsu

Składnia to słowo kluczowe interface, nazwa (zwyczajowo w PascalCase) i ciało z listą składowych. Składowe można oddzielać średnikami, przecinkami albo po prostu nowymi liniami; średniki to najczęstszy styl.

interface Product {
  sku: string;               // required property
  price: number;
  tags: string[];            // array property
  dimensions: {              // nested object type
    width: number;
    height: number;
  };
  discount?: number;         // optional property
  readonly createdAt: Date;  // cannot be reassigned
  label(): string;           // method
}

Interfejs to typ, a nie wartość. Nie da się utworzyć jego instancji przez new, nie ma wartości domyślnych, a obj instanceof Product to błąd TS2693 ('Product' only refers to a type, but is being used as a value here). Żeby sprawdzić kształt w czasie działania, napisz type guard.

Typowanie strukturalne i sprawdzanie nadmiarowych właściwości

TypeScript porównuje kształty, a nie nazwy. Każdy obiekt z wymaganymi właściwościami pasuje do interfejsu, niezależnie od tego, czy został z nim zadeklarowany. Dodatkowe właściwości są dozwolone, z jednym wyjątkiem: literał obiektowy zapisany bezpośrednio tam, gdzie oczekiwany jest interfejs, przechodzi sprawdzenie nadmiarowych właściwości, bo nieznany klucz w takim miejscu to prawie zawsze literówka.

interface Point {
  x: number;
  y: number;
}

function distance(p: Point): number {
  return Math.hypot(p.x, p.y);
}

const saved = { x: 3, y: 4, label: "A" }; // never declared as a Point
console.log(distance(saved));             // 5: the shape matches

// @ts-expect-error: Object literal may only specify known properties, and 'label' does not exist in type 'Point'.
distance({ x: 3, y: 4, label: "A" });

Ten błąd (TS2353) wyłapuje { id: 1, name: "a", emial: "x" } dla typu User: kompilator podpowiada nawet Did you mean to write 'email'? (TS2561).

Właściwości opcjonalne i readonly

? po nazwie czyni właściwość opcjonalną: obiekt może ją pominąć, a jej odczyt daje T | undefined. readonly zabrania ponownego przypisania właściwości po utworzeniu obiektu.

interface Config {
  readonly apiUrl: string;
  readonly hosts: readonly string[];
  timeoutMs?: number;
}

const config: Config = { apiUrl: "https://api.example.com", hosts: ["a", "b"] };

// @ts-expect-error: Cannot assign to 'apiUrl' because it is a read-only property.
config.apiUrl = "http://localhost";
// @ts-expect-error: Property 'push' does not exist on type 'readonly string[]'.
config.hosts.push("c");

console.log(config.timeoutMs ?? 5000); // 5000: optional, so check or default it

const local = { ...config, apiUrl: "http://localhost" }; // a changed copy is fine
console.log(local.apiUrl); // http://localhost

// readonly is a compile-time rule attached to this type only:
const writable: { apiUrl: string } = config; // allowed
writable.apiUrl = "changed";
console.log(config.apiUrl); // changed

Widać tu dwa ograniczenia. Po pierwsze, readonly działa tylko w czasie kompilacji: dwie linie oznaczone @ts-expect-error i tak się wykonują po kliknięciu Run, i to z powodzeniem, a ostatnie linie zmieniają apiUrl przez referencję otypowaną bez readonly. Po drugie, jest płytkie: readonly hosts: string[] zablokowałoby ponowne przypisanie hosts, ale nadal pozwalałoby na hosts.push(...), dlatego sama tablica ma typ readonly string[]. readonly dokumentuje i egzekwuje zamiar w otypowanym kodzie; niczego nie zamraża. Utility type Readonly<T> sprawia, że wszystkie właściwości istniejącego interfejsu stają się naraz readonly.

Metody i właściwości funkcyjne

Metodę można zapisać jako sygnaturę metody, name(params): ReturnType, albo jako właściwość przechowującą funkcję, name: (params) => ReturnType. Wywołuje się je tak samo.

interface Counter {
  count: number;
  increment(by?: number): void; // method signature
  reset: () => void;            // property holding a function
}

function createCounter(): Counter {
  return {
    count: 0,
    increment(by = 1) {
      this.count += by; // this is typed as Counter
    },
    reset() {
      this.count = 0;
    },
  };
}

const c = createCounter();
c.increment();
c.increment(5);
console.log(c.count); // 6
c.reset();
console.log(c.count); // 0

Różnica jest subtelna: przy strictFunctionTypes (część strict) parametry właściwości o typie funkcji są sprawdzane ściśle, a sygnatury metod luźniej (biwariantnie), więc forma właściwości wyłapuje kilka błędów więcej. Składnia metody jest krótsza i częściej spotykana; obie są w porządku.

Interfejs może też opisywać coś, co da się wywołać albo skonstruować, za pomocą sygnatury wywołania albo sygnatury konstrukcji:

interface Formatter {
  (value: number): string; // call signature: the object is a function
  locale: string;          // and it also has a property
}

interface PointConstructor {
  new (x: number, y: number): { x: number; y: number }; // construct signature
}

Sygnatury indeksu

Gdy nazwy właściwości nie są znane z góry, sygnatura indeksu opisuje je wszystkie naraz: [key: string]: T oznacza „dowolny klucz typu string, każdy z wartością T”.

interface Scores {
  [player: string]: number;
}

const scores: Scores = { ada: 90, alan: 85 };
scores.grace = 95; // any string key is allowed
scores["linus"] = 70;

for (const [player, score] of Object.entries(scores)) {
  console.log(player, score);
}

const missing = scores.nobody; // typed number, actually undefined
console.log(missing);          // undefined

Ostatnie linie pokazują haczyk: odczyt nieistniejącego klucza ma typ number, a nie number | undefined. Opcja kompilatora noUncheckedIndexedAccess dodaje | undefined do każdego takiego odczytu.

Nazwane właściwości mogą stać obok sygnatury indeksu, ale muszą do niej pasować. interface Dict { [key: string]: number; name: string } to błąd TS2411, Property 'name' of type 'string' is not assignable to 'string' index type 'number'. Poszerz typ indeksu ([key: string]: number | string) albo przenieś dynamiczną część do osobnej właściwości. Dla prostych map klucz/wartość Record<string, number> mówi to samo w jednej linii.

Rozszerzanie interfejsu

extends buduje nowy interfejs z jednego lub kilku istniejących. Potomek ma wszystkie składowe rodzica i do tego własne:

interface Animal {
  name: string;
}

interface Pet extends Animal {
  owner: string;
}

interface Trained {
  commands: string[];
}

interface ServiceDog extends Pet, Trained {
  certifiedUntil: Date;
}

// ServiceDog requires: name, owner, commands, certifiedUntil

Potomek może ponownie zadeklarować właściwość rodzica tylko ze zgodnym (węższym) typem, na przykład kind: "dog" tam, gdzie rodzic ma kind: string. Reguły i sposób rozszerzania aliasów typów opisuje strona o extends.

Implementowanie interfejsu w klasie

class X implements Shape prosi kompilator o sprawdzenie, czy klasa ma wszystko, czego wymaga interfejs. Brakująca składowa to błąd przy deklaracji klasy:

// This does not compile: Circle is missing area()
interface Shape {
  name: string;
  area(): number;
}

class Circle implements Shape {
  name = "circle";
  constructor(public radius: number) {}
}

console.log(new Circle(2).name);

index.ts(7,7): error TS2420: Class 'Circle' incorrectly implements interface 'Shape'.
  Property 'area' is missing in type 'Circle' but required in type 'Shape'.

Po dodaniu area() kilka klas, a nawet zwykły obiekt, może służyć jako Shape:

interface Shape {
  name: string;
  area(): number;
}

class Circle implements Shape {
  name = "circle";
  constructor(public radius: number) {}
  area() {
    return Math.PI * this.radius ** 2;
  }
}

class Rect implements Shape {
  name = "rect";
  constructor(public w: number, public h: number) {}
  area() {
    return this.w * this.h;
  }
}

// A plain object with the right shape is a Shape too: no class needed.
const unitSquare: Shape = { name: "unit square", area: () => 1 };

const shapes: Shape[] = [new Circle(1), new Rect(2, 3), unitSquare];
for (const s of shapes) {
  console.log(s.name, s.area().toFixed(2));
}

implements to tylko sprawdzenie. Nie dodaje składowych do klasy i nie typuje za ciebie parametrów jej metod: greet(name) {} w klasie implementującej greet(name: string): string to nadal błąd TS7006, Parameter 'name' implicitly has an 'any' type. Klasa może implementować kilka interfejsów: class A implements B, C.

Łączenie deklaracji

Dwukrotne zadeklarowanie interfejsu o tej samej nazwie w tym samym zasięgu łączy obie deklaracje w jedną. Aliasy typów tego nie potrafią (drugi type o tej samej nazwie to błąd zduplikowanego identyfikatora).

interface Settings {
  theme: string;
}

interface Settings {
  fontSize: number;
}

// Settings now requires both properties
const s: Settings = { theme: "dark", fontSize: 14 };

W kodzie aplikacji rzadko o to chodzi, a przypadkowe połączenie potrafi zmylić. Prawdziwe zastosowanie to dodawanie składowych do typów, które nie są twoje: opcji biblioteki albo globalnego obiektu, takiego jak Window. Wewnątrz modułu owiń deklarację w declare global:

declare global {
  interface Window {
    analytics: { track(event: string): void };
  }
}

export {};

Od tej chwili window.analytics.track("signup") przechodzi sprawdzanie typów w całym projekcie. Na tym samym mechanizmie opierają się pakiety z definicjami typów; zobacz pliki deklaracji.

Wartości domyślne właściwości interfejsu

Interfejs nie może przechowywać wartości domyślnych, bo opisuje typy i jest usuwany w czasie działania. size?: "sm" | "md" = "md" to błąd TS1246, An interface property cannot have an initializer. Uczyń właściwość opcjonalną i uzupełnij wartość domyślną tam, gdzie używasz obiektu:

interface ButtonOptions {
  label: string;
  size?: "sm" | "md" | "lg";
  disabled?: boolean;
}

// 1. Destructuring defaults: applied when the value is undefined
function render({ label, size = "md", disabled = false }: ButtonOptions): string {
  return `[${label}] size=${size} disabled=${disabled}`;
}

// 2. Spread a defaults object under the options
const DEFAULTS = { size: "md", disabled: false } as const;

function withDefaults(options: ButtonOptions) {
  return { ...DEFAULTS, ...options };
}

console.log(render({ label: "Save" }));                   // [Save] size=md disabled=false
console.log(render({ label: "Save", size: undefined }));  // [Save] size=md disabled=false
console.log(withDefaults({ label: "Save", size: "lg" }));  // { size: 'lg', disabled: false, label: 'Save' }
console.log(withDefaults({ label: "Save", size: undefined }));
// { size: undefined, disabled: false, label: 'Save' }

Wartości domyślne przy destrukturyzacji są bezpieczniejsze: działają zawsze, gdy wartość to undefined, także przy jawnym size: undefined. Wersja ze spreadem kopiuje to jawne undefined na wartość domyślną, a jej wynik nadal ma typ, jakby size było zawsze ustawione. Jeśli potrzebujesz takiej gwarancji od typów, włącz exactOptionalPropertyTypes, które czyni size: undefined błędem kompilacji dla opcjonalnego size?: .... Klasa z zainicjalizowanymi polami to druga opcja, gdy obiekt potrzebuje też zachowania.

Interfejsy generyczne

Interfejs może przyjmować parametry typu, dzięki czemu jedna deklaracja działa dla wielu typów zawartości:

interface ApiResponse<T> {
  ok: boolean;
  data: T;
  error?: string;
}

interface Page<T> {
  items: T[];
  nextCursor?: string;
}

interface User {
  id: number;
  name: string;
}

const res: ApiResponse<Page<User>> = {
  ok: true,
  data: { items: [{ id: 1, name: "Ada" }], nextCursor: "abc" },
};

ApiResponse<Page<User>> czyta się jako „odpowiedź, której dane są stroną użytkowników”. Biblioteka standardowa jest ich pełna: Array<T>, Promise<T> i Map<K, V> to interfejsy generyczne.

Interfejs kontra alias typu

Alias type może opisywać ten sam kształt obiektu, a dla zwykłych typów obiektowych oba są wymienne. Tylko interfejs można łączyć; tylko alias typu może nazwać unię, krotkę albo mapped type czy conditional type. Praktyczna reguła z handbooka TypeScript: używaj interface, dopóki nie potrzebujesz czegoś, co ma tylko type. Pełne porównanie jest na stronie o interface vs type, łącznie z różnicą przy Record<string, ...>, która zaskakuje większość osób.