Интерфейсы в TypeScript: синтаксис, методы и примеры

Интерфейс даёт имя структуре объекта: свойствам, которые у него должны быть, и типу каждого из них. После объявления имя используется как тип, и компилятор проверяет по нему каждый объект, который вы передаёте, возвращаете или присваиваете.

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

Последний вызов это ошибка компиляции TS2741. Интерфейсы стираются при компиляции кода: в выводе JavaScript от User не остаётся следа, и во время выполнения структуру никто не проверяет.

Объявление интерфейса

Синтаксис такой: ключевое слово interface, имя (по соглашению в PascalCase) и тело со списком членов. Члены можно разделять точками с запятой, запятыми или просто переводами строк; точки с запятой это распространённый стиль.

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
}

Интерфейс это тип, а не значение. Его нельзя создать через new, у него нет значений по умолчанию, а obj instanceof Product это ошибка TS2693 ('Product' only refers to a type, but is being used as a value here). Чтобы проверить структуру во время выполнения, напишите защитник типа.

Структурная типизация и проверка лишних свойств

TypeScript сравнивает структуры, а не имена. Любой объект с нужными свойствами подходит под интерфейс, независимо от того, объявлялся ли он с ним. Лишние свойства допустимы, с одним исключением: объектный литерал, написанный прямо там, где ожидается интерфейс, проходит проверку лишних свойств, потому что неизвестный ключ в этом месте почти всегда опечатка.

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

Именно эта ошибка (TS2353) ловит { id: 1, name: "a", emial: "x" } для User: компилятор даже подсказывает Did you mean to write 'email'? (TS2561).

Необязательные и readonly свойства

? после имени делает свойство необязательным: объект может его опустить, а чтение даёт T | undefined. readonly запрещает переприсваивать свойство после создания объекта.

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

Здесь видны два ограничения. Во-первых, readonly действует только при компиляции: две строки с пометкой @ts-expect-error при нажатии Run всё равно выполняются и успешно, а последние строки меняют apiUrl через ссылку с типом без readonly. Во-вторых, он поверхностный: readonly hosts: string[] запретил бы переприсваивать hosts, но разрешил бы hosts.push(...), поэтому сам массив типизирован как readonly string[]. Он документирует и обеспечивает намерение в типизированном коде, но ничего не замораживает. Служебный тип Readonly<T> делает readonly сразу все свойства существующего интерфейса.

Методы и свойства-функции

Метод можно записать как сигнатуру метода, name(params): ReturnType, или как свойство, хранящее функцию, name: (params) => ReturnType. Вызывающий код использует оба одинаково.

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

Разница тонкая: при strictFunctionTypes (входит в strict) параметры свойств с типом функции проверяются строго, а сигнатуры методов мягче (бивариантно), поэтому форма свойства ловит чуть больше ошибок. Синтаксис метода короче и встречается чаще; годятся оба.

Интерфейс может также описывать то, что можно вызвать или сконструировать, через сигнатуру вызова или сигнатуру конструктора:

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
}

Сигнатуры индекса

Когда имена свойств заранее неизвестны, сигнатура индекса описывает их все сразу: [key: string]: T означает «любой строковый ключ, каждый хранит 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

Последние строки показывают подвох: чтение несуществующего ключа типизировано как number, а не number | undefined. Параметр компилятора noUncheckedIndexedAccess добавляет | undefined к каждому такому чтению.

Именованные свойства могут соседствовать с сигнатурой индекса, но должны ей соответствовать. interface Dict { [key: string]: number; name: string } это ошибка TS2411, Property 'name' of type 'string' is not assignable to 'string' index type 'number'. Расширьте тип индекса ([key: string]: number | string) или вынесите динамическую часть в отдельное свойство. Для простых отображений ключ/значение Record<string, number> говорит то же самое в одну строку.

Расширение интерфейса

extends строит новый интерфейс из одного или нескольких существующих. Потомок содержит все члены родителя плюс свои:

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

Потомок может переобъявить свойство родителя только с совместимым (более узким) типом, например kind: "dog", где у родителя kind: string. Правила и способы расширять псевдонимы типов описаны на странице extends.

Реализация интерфейса в классе

class X implements Shape просит компилятор проверить, что в классе есть всё, чего требует интерфейс. Отсутствующий член это ошибка в объявлении класса:

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

Когда area() добавлен, несколько классов и даже обычный объект можно использовать как 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 это только проверка. Он не добавляет в класс членов и не типизирует за вас параметры методов класса: greet(name) {} внутри класса, реализующего greet(name: string): string, всё равно ошибка TS7006, Parameter 'name' implicitly has an 'any' type. Класс может реализовать несколько интерфейсов: class A implements B, C.

Слияние объявлений

Если объявить интерфейс с одним и тем же именем дважды в одной области видимости, два объявления сливаются в одно. Псевдонимы типов так не умеют (второй type с тем же именем даёт ошибку повторяющегося идентификатора).

interface Settings {
  theme: string;
}

interface Settings {
  fontSize: number;
}

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

В прикладном коде это редко нужно, а случайное слияние может сбить с толку. Настоящее применение это добавление членов в типы, которые вам не принадлежат: параметры библиотеки или глобальный объект вроде Window. Внутри модуля оберните объявление в declare global:

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

export {};

После этого window.analytics.track("signup") проходит проверку типов во всём проекте. На том же механизме основаны пакеты определений типов; см. файлы объявлений.

Значения по умолчанию для свойств интерфейса

Интерфейс не может хранить значения по умолчанию, потому что описывает типы и стирается во время выполнения. size?: "sm" | "md" = "md" это ошибка TS1246, An interface property cannot have an initializer. Сделайте свойство необязательным и подставляйте значение по умолчанию там, где используется объект:

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

Значения по умолчанию при деструктуризации надёжнее: они применяются всякий раз, когда значение undefined, включая явное size: undefined. Вариант с распространением копирует это явное undefined поверх значения по умолчанию, а его результат всё равно типизирован так, будто size задан всегда. Если нужна такая гарантия от типов, включите exactOptionalPropertyTypes, и тогда size: undefined станет ошибкой компиляции для необязательного size?: .... Другой вариант это класс с инициализированными полями, если объекту нужно ещё и поведение.

Обобщённые интерфейсы

Интерфейс может принимать параметры типа, и тогда одно объявление работает для многих типов данных:

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>> читается как «ответ, данные которого это страница пользователей». Стандартная библиотека полна таких интерфейсов: Array<T>, Promise<T>, Map<K, V> это обобщённые интерфейсы.

Интерфейс или псевдоним типа

Псевдоним type может описать ту же структуру объекта, и для простых объектных типов они взаимозаменяемы. Только интерфейс умеет сливаться; только псевдоним типа может назвать объединение, кортеж, сопоставленный или условный тип. Практическое правило из справочника TypeScript: используйте interface, пока не понадобится возможность, которая есть только у type. Полное сравнение, включая неожиданную для многих разницу с Record<string, ...>, есть на странице interface или type.