Директивы с тройными слешами

Директивы с тройными слешами — это однострочные комментарии, содержащие один XML-тег. Содержимое комментария используется как директивы компилятора.

Директивы с тройными слешами только допустимы в начале содержащего их файла. Директива с тройными слешами может предшествовать только однострочным или многострочным комментариям, включая другие директивы с тройными слешами. Если они встречаются после оператора или объявления, они обрабатываются как обычные однострочные комментарии и не имеют специального значения.

/// <reference path="..." />

Директива /// <reference path="..." /> — наиболее распространённая в этой группе. Она служит объявлением зависимости между файлами.

Ссылки с тройными слешами инструктируют компилятор включить дополнительные файлы в процесс компиляции.

Они также служат способом упорядочения вывода при использовании out или outFile. Файлы выводятся в выходной файл в том же порядке, что и входные, после прохождения предобработки.

Предобработка входных файлов

Компилятор выполняет предобработку входных файлов для разрешения всех директив с тройными слешами. В ходе этого процесса к компиляции добавляются дополнительные файлы.

Процесс начинается с набора корневых файлов; это имена файлов, указанные в командной строке или в списке files в файле tsconfig.json. Эти корневые файлы предобрабатываются в том же порядке, в котором они указаны. Перед добавлением файла в список обрабатываются все ссылки с тройными слешами в нём, а их целевые файлы включаются. Ссылки с тройными слешами разрешаются по принципу глубины, в порядке их обнаружения в файле.

Путь ссылки с тройными слешами разрешается относительно содержащего файла, если используется относительный путь.

Ошибки

Ошибка — ссылаться на файл, которого не существует. Ошибка — у файла есть ссылка с тройными слешами на себя.

Использование --noResolve

Если указан флаг компилятора noResolve, ссылки с тройными слешами игнорируются; они не приводят к добавлению новых файлов и не меняют порядок предоставленных файлов.

/// <reference types="..." />

Аналогично директиве /// <reference path="..." />, которая служит объявлением зависимости, директива /// <reference types="..." /> объявляет зависимость от пакета.

Процесс разрешения этих имён пакетов аналогичен процессу разрешения имён модулей в операторе import. Легче всего представить директивы triple-slash-reference-types как import для объявления пакетов.

Например, включение /// <reference types="node" /> в файл объявления означает, что этот файл использует имена, объявленные в @types/node/index.d.ts; следовательно, этот пакет необходимо включить в компиляцию вместе с файлом объявления.

Используйте эти директивы только при ручном создании файла d.ts.

Для файлов объявления, сгенерированных во время компиляции, компилятор автоматически добавит /// <reference types="..." /> для вас; директива /// <reference types="..." /> в сгенерированном файле объявления добавляется только в том случае, если результирующий файл использует какие-либо объявления из ссылаемого пакета.

Для объявления зависимости от пакета @types в файле .ts используйте types в командной строке или в вашем файле tsconfig.json. Подробности см. в использовании @types, typeRoots и types в файлах tsconfig.json.

/// <reference lib="..." />

Эта директива позволяет файлу явно включить существующий встроенный файл lib.

Встроенные файлы lib ссылаются так же, как и опция компилятора lib в tsconfig.json (например, используйте lib="es2015" и не lib="lib.es2015.d.ts", и т. д.).

Для авторов файлов объявления, которые полагаются на встроенные типы, например, DOM-API или встроенные конструкторы JS-среды выполнения, такие как Symbol или Iterable, рекомендуются директивы triple-slash-reference lib. Раньше эти файлы .d.ts должны были добавлять объявления-перенаправления/дубликаты таких типов.

Например, добавление /// <reference lib="es2017.string" /> в один из файлов в компиляции эквивалентно компиляции с --lib es2017.string.

/// <reference lib="es2017.string" />

"foo".padStart(4);

/// <reference no-default-lib="true"/>

Эта директива помечает файл как стандартную библиотеку. Вы увидите этот комментарий в начале файла lib.d.ts и его различных вариантов.

Эта директива инструктирует компилятор не включать стандартную библиотеку (т. е. lib.d.ts) в компиляцию. Влияние здесь аналогично передаче noLib в командной строке.

Также обратите внимание, что при передаче skipDefaultLibCheck компилятор будет пропускать проверку файлов с /// <reference no-default-lib="true"/>.

/// <amd-module />

По умолчанию модули AMD генерируются анонимно. Это может привести к проблемам при использовании других инструментов для обработки полученных модулей, таких как сборщики (например, r.js).

Директива amd-module позволяет передать необязательное имя модуля компилятору:

amdModule.ts

///<amd-module name="NamedModule"/>
export class C {}

Приведёт к присвоению имени NamedModule модулю в качестве части вызова AMD define:

amdModule.js

define("NamedModule", ["require", "exports"], function (require, exports) {
  var C = (function () {
    function C() {}
    return C;
  })();
  exports.C = C;
});

/// <amd-dependency />

Примечание: эта директива устарела. Используйте операторы import "moduleName"; вместо неё.

/// <amd-dependency path="x" /> сообщает компилятору о зависимости от модуля, не являющегося TS, которая должна быть внедрена в вызов require результирующего модуля.

Директива amd-dependency также может иметь необязательную свойство name; это позволяет передать необязательное имя для amd-зависимости:

/// <amd-dependency path="legacy/moduleA" name="moduleA"/>
declare var moduleA: MyType;
moduleA.callStuff();

Сгенерированный код JS:

define(["require", "exports", "legacy/moduleA"], function (
  require,
  exports,
  moduleA
) {
  moduleA.callStuff();
});