三斜杠指令

三斜杠指令是包含单个 XML 标签的单行注释。注释的内容用作编译器指令。

三斜杠指令 **仅** 在其包含文件的顶部有效。三斜杠指令只能在单行或多行注释之前，包括其他三斜杠指令。如果它们在语句或声明之后遇到，则被视为常规单行注释，没有任何特殊含义。

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

/// <reference path="..." /> 指令是这组指令中最常见的。它用作文件之间依赖关系的声明。

三斜杠引用指示编译器在编译过程中包含其他文件。

它们还用作在使用 out 或 outFile 时对输出进行排序的方法。文件以与预处理传递后输入相同的顺序发出到输出文件位置。

预处理输入文件

编译器对输入文件执行预处理传递以解析所有三斜杠引用指令。在此过程中，其他文件将被添加到编译中。

该过程从一组根文件开始；这些是命令行或tsconfig.json 文件中files 列表中指定的文件名。这些根文件按指定的顺序进行预处理。在将文件添加到列表之前，将处理其中的所有三斜杠引用，并将其目标包含在内。三斜杠引用以深度优先的方式解析，按照它们在文件中出现的顺序进行解析。

如果使用相对路径，则三斜杠引用路径相对于包含文件解析。

错误

引用不存在的文件是错误的。文件对自身进行三斜杠引用是错误的。

使用 --noResolve

如果指定了编译器标志 noResolve，则会忽略三斜线引用；它们不会导致添加新文件，也不会改变提供的文件的顺序。

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

类似于/// <reference path="..." /> 指令，它用作依赖项的声明，/// <reference types="..." /> 指令声明对包的依赖项。

解析这些包名称的过程类似于解析import 语句中模块名称的过程。一个简单的理解三斜线引用类型指令的方法是将它们视为声明包的import。

例如，在声明文件中包含/// <reference types="node" /> 声明该文件使用@types/node/index.d.ts 中声明的名称；因此，该包需要与声明文件一起包含在编译中。

仅在手动编写d.ts 文件时使用这些指令。

对于在编译期间生成的声明文件，编译器会自动为您添加/// <reference types="..." />；仅当生成的声明文件使用来自引用包的任何声明时，才会添加生成的声明文件中的/// <reference types="..." />。

要声明对.ts 文件中的@types 包的依赖项，请在命令行或tsconfig.json 中使用 types。有关更多详细信息，请参阅 在tsconfig.json 文件中使用@types、typeRoots 和types。

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

此指令允许文件显式包含现有的内置lib 文件。

内置的 lib 文件的引用方式与 tsconfig.json 中的 lib 编译器选项相同（例如，使用 lib="es2015" 而不是 lib="lib.es2015.d.ts" 等）。

对于依赖内置类型的声明文件作者，例如 DOM API 或内置 JS 运行时构造函数（如 Symbol 或 Iterable），建议使用三斜杠引用 lib 指令。以前，这些 .d.ts 文件必须添加此类类型的转发/重复声明。

例如，在编译中的某个文件中添加 /// <reference lib="es2017.string" /> 等效于使用 --lib es2017.string 进行编译。

ts
/// <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

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

将导致在调用 AMD define 时将名称 NamedModule 分配给模块。

amdModule.js

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" /> 通知编译器关于需要注入到生成的模块的 require 调用中的非 TS 模块依赖项。

amd-dependency 指令还可以有一个可选的 name 属性；这允许为 amd 依赖项传递可选名称。

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

生成的 JS 代码

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