Декларация окружения

Как мы сказали в разделе почему TypeScript:

Основная цель разработки TypeScript состоит в том, чтобы позволить вам безопасно и легко использовать существующие Javascript библиотеки в TypeScript. TypeScript делает это посредством объявлений.

Декларация окружения позволяют вам безопасно использовать существующие популярные библиотеки JavaScript и постепенно переносить ваш проект с JavaScript / CoffeeScript / Other-Compile-To-Js-Language на TypeScript.

Научиться писать декларацию окружения для сторонних библиотек JavaScript - хорошая практика для написания аннотаций для TypeScript.

Файл декларации

Вы можете использовать ключевое слово declare, чтобы сообщить TypeScript, что вы пытаетесь описать код, который уже существует в другом месте (например: код, написанный на JavaScript, CoffeeScript, среда такая как браузер или Node.js):

foo = 123; // Error: 'foo' is not defined

против.

declare var foo: any;
foo = 123; // allow

Вы можете поместить эти объявления в .ts или .d.ts. В вашем реальном проекте мы настоятельно рекомендуем поместить объявление в .d.ts (вы можете начать с файлов global.d.ts или vendor.d.ts ).

Если файл имеет расширение .d.ts, это означает, что каждое объявление верхнего уровня должно начинаться с ключевого слова declare. Это гарантирует, что TypeScript не влияет на код. Автор должен проверить, что заявленный элемент существует во время выполнения.

• Декларация окружения похожа на соглашение между вами и компилятором. Если вы попытаетесь использовать элемент без него во время выполнения, программа вылетит без предупреждения.

• Декларация окружения похожа на документацию. При изменении источника документация должна быть обновлена. Поэтому, если вы не декларацию окружения, когда во время выполнения возникает новое поведение, вы получите ошибку компиляции.

Переменные

Например, чтобы рассказать TypeScript о переменной process, вы можете написать:

declare let process: any;

Вам не нужно делать это для process , потому что он уже существует в файле node.d.ts, поддерживаемом сообществом.

Это позволяет использовать process и успешно компилировать с помощью TypeScript:

process.exit();

Мы рекомендуем использовать интерфейсы всякий раз, когда это возможно, например:

interface Process {
  exit(code?: number): void;
}

declare let process: Process;

Это позволяет расширять глобальные переменные, но также позволяет TypeScript знать об изменениях в глобальных переменных. Например, в следующем примере добавляется функция exitWithLogging для обработки по мере необходимости:

interface Process {
  exitWithLogging(code?: number): void;
}

process.exitWithLogging = function() {
  console.log('exiting');
  process.exit.apply(process, arguments);
};

Далее давайте разберемся с интерфейсами более подробно.