十一、三斜线指令

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

三斜线指令只在其包含文件的顶部有效。三斜线指令的前面只能有单行或多行注释，包括其他三斜线指令。如果它们出现在语句或声明之后，则被视为普通的单行注释，没有任何特殊意义。

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

  • 预处理输入文件

编译器对输入文件进行预处理，以解决所有三斜线参考指令。在这个过程中，额外的文件被添加到编译中。

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

如果使用的是相对路径，那么三斜线引用的路径是相对于包含的文件进行解析的。

  • 错误

引用一个不存在的文件是一个错误。一个文件对自己有三重斜线引用是一个错误。

  • 使用 --noResolve

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

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

与作为依赖关系声明的 /// <reference path="..." /> 指令类似，/// <reference types="..." />指令声明对包的依赖关系。

解析这些包名的过程与解析 import 语句中的模块名的过程类似。一个简单的方法是将三重斜线引用类型指令看作是声明包的 import。

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

只有在你手工编写 d.ts 文件的时候才使用这些指令。

对于在编译过程中生成的声明文件，编译器会自动为你添加 /// <reference types="..." />；在生成的声明文件中，当且仅当生成的文件使用了被引用包的任何声明时，会添加 /// <reference types="..." />。

对于在 .ts 文件中声明对 @types s包的依赖，在命令行或你的 tsconfig.json 中使用 types 来代替。参见 在 tsconfig.json 文件里应用 @types, typeRoots 和 types 以了解更多细节。

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

这个指令允许一个文件明确地包含一个现有的内置 lib 文件。

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

对于依赖内置类型的声明文件作者，例如DOM APIs或内置的JS运行时构造器，如 Symbol或Iterable，建议使用三重斜线引用的lib指令。以前这些 .d.ts 文件不得不添加此类类型的前向/重复声明。

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

/// <reference lib="es2017.string" />
"foo".padStart(4);

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

这个指令将一个文件标记为 _默认库_。你会在 lib.d.ts 和它的不同变体的顶部看到这个注释。

这个指令指示编译器在编译时不包括默认库（即 lib.d.ts）。这里的影响类似于在命令行中传递 noLib 。

还要注意的是，当传递 skipDefaultLibCheck时，编译器将只跳过检查带有 /// <reference no-default-lib="true"/> 的文件。

14.5 /// <amd-module />

默认情况下，AMD模块是以匿名方式生成的。当其他工具被用来处理生成的模块时，这可能会导致问题，例如捆绑器（如 r.js ）。

amd-module指令允许向编译器传递一个可选的模块名称。

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

将导致在调用AMD define的过程中，将NamedModule这个名字分配给模块。

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

14.6 /// <amd-dependency />

注意：这个指令已被废弃。使用import "moduleName";语句代替。

/// <amd-dependency path="x" /> 通知编译器一个需要在生成的模块的 require 调用中注入的非 TS 模块的依赖关系。

amd-dependency指令也可以有一个可选的name属性；这允许为amd-dependency传递一个可选的名字。

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

特别声明: 本文转自 古艺散人老师 ，如有需要可前往原文预览查看。