Справочник по объявлениям

Цель данного руководства — научить вас создавать качественные файлы определений. Руководство структурировано, демонстрируя документацию для некоторых API, примеры использования этого API и объяснения того, как написать соответствующее объявление.

Эти примеры упорядочены приблизительно по возрастанию сложности.

Объекты со свойствами

Документация

Глобальная переменная myLib имеет функцию makeGreeting для создания приветствий и свойство numberOfGreetings, указывающее на количество сделанных приветствий.

Код

let result = myLib.makeGreeting("hello, world");
console.log("The computed greeting is:" + result);

let count = myLib.numberOfGreetings;

Объявление

Используйте declare namespace для описания типов или значений, доступных через обозначение с точкой.

declare namespace myLib {
  function makeGreeting(s: string): string;
  let numberOfGreetings: number;
}

Перегруженные функции

Документация

Функция getWidget принимает число и возвращает Widget или принимает строку и возвращает массив Widget.

Код

let x: Widget = getWidget(43);

let arr: Widget[] = getWidget("all of them");

Объявление

declare function getWidget(n: number): Widget;
declare function getWidget(s: string): Widget[];

Многократно используемые типы (интерфейсы)

Документация

При указании приветствия необходимо передать объект GreetingSettings. Этот объект имеет следующие свойства:

1 - greeting: Обязательная строка

2 - duration: Необязательная длительность (в миллисекундах)

3 - color: Необязательная строка, например, ‘#ff00ff’

Код

greet({
  greeting: "hello world",
  duration: 4000
});

Объявление

Используйте interface для определения типа со свойствами.

interface GreetingSettings {
  greeting: string;
  duration?: number;
  color?: string;
}

declare function greet(setting: GreetingSettings): void;

Многократно используемые типы (псевдонимы типов)

Документация

В любом месте, где ожидается приветствие, можно предоставить string, функцию, возвращающую string, или экземпляр Greeter.

Код

function getGreeting() {
  return "howdy";
}
class MyGreeter extends Greeter {}

greet("hello");
greet(getGreeting);
greet(new MyGreeter());

Объявление

Можно использовать псевдоним типа для создания сокращения для типа:

type GreetingLike = string | (() => string) | MyGreeter;

declare function greet(g: GreetingLike): void;

Организация типов

Документация

Объект greeter может регистрировать данные в файле или отображать сообщение об ошибке. Можно передать LogOptions в .log(...) и параметры предупреждения в .alert(...)

Код

const g = new Greeter("Hello");
g.log({ verbose: true });
g.alert({ modal: false, title: "Current Greeting" });

Объявление

Используйте пространства имён для организации типов.

declare namespace GreetingLib {
  interface LogOptions {
    verbose?: boolean;
  }
  interface AlertOptions {
    modal: boolean;
    title?: string;
    color?: string;
  }
}

Также можно создать вложенные пространства имён в одном объявлении:

declare namespace GreetingLib.Options {
  // Refer to via GreetingLib.Options.Log
  interface Log {
    verbose?: boolean;
  }
  interface Alert {
    modal: boolean;
    title?: string;
    color?: string;
  }
}

Классы

Документация

Можно создать приветствие, создав экземпляр объекта Greeter, или создать настроенное приветствие, расширив его.

Код

const myGreeter = new Greeter("hello, world");
myGreeter.greeting = "howdy";
myGreeter.showGreeting();

class SpecialGreeter extends Greeter {
  constructor() {
    super("Very special greetings");
  }
}

Объявление

Используйте declare class для описания класса или объекта, подобного классу. Классы могут иметь свойства и методы, а также конструктор.

declare class Greeter {
  constructor(greeting: string);

  greeting: string;
  showGreeting(): void;
}

Глобальные переменные

Документация

Глобальная переменная foo содержит количество имеющихся виджетов.

Код

console.log("Half the number of widgets is " + foo / 2);

Объявление

Используйте declare var для объявления переменных. Если переменная является только для чтения, можно использовать declare const. Также можно использовать declare let, если переменная имеет область действия блока.

/** The number of widgets present */
declare var foo: number;

Глобальные функции

Документация

Можно вызвать функцию greet со строкой, чтобы показать пользователю приветствие.

Код

greet("hello, world");

Объявление

Используйте declare function для объявления функций.

declare function greet(greeting: string): void;