三斜線指令是包含單個XML標簽的單行注釋。 注釋的內容會做為編譯器指令使用。
三斜線指令僅可放在包含它的文件的最頂端。 一個三斜線指令的前面只能出現單行或多行注釋,這包括其它的三斜線指令。 如果它們出現在一個語句或聲明之后,那么它們會被當做普通的單行注釋,並且不具有特殊的涵義。
/// <reference path="..." />
/// <reference path="..." />
指令是三斜線指令中最常見的一種。 它用於聲明文件間的依賴。
三斜線引用告訴編譯器在編譯過程中要引入的額外的文件。
當使用--out
或--outFile
時,它也可以做為調整輸出內容順序的一種方法。 文件在輸出文件內容中的位置與經過預處理后的輸入順序一致。
預處理輸入文件
編譯器會對輸入文件進行預處理來解析所有三斜線引用指令。 在這個過程中,額外的文件會加到編譯過程中。
這個過程會以一些根文件開始; 它們是在命令行中指定的文件或是在tsconfig.json
中的"files"
列表里的文件。 這些根文件按指定的順序進行預處理。 在一個文件被加入列表前,它包含的所有三斜線引用都要被處理,還有它們包含的目標。 三斜線引用以它們在文件里出現的順序,使用深度優先的方式解析。
一個三斜線引用路徑是相對於包含它的文件的,如果不是根文件。
錯誤
引用不存在的文件會報錯。 一個文件用三斜線指令引用自己會報錯。
使用 --noResolve
如果指定了--noResolve
編譯選項,三斜線引用會被忽略;它們不會增加新文件,也不會改變給定文件的順序。
/// <reference types="..." />
與/// <reference path="..." />
指令相似,這個指令是用來聲明依賴的; 一個/// <reference path="..." />
指令聲明了對@types
包的一個依賴。
在聲明文件里包含/// <reference types="node" />
,表明這個文件使用了@types/node/index.d.ts
里面聲明的名字; 並且,這個包要在編譯階段與聲明文件一起被包含進來。
解析@types
包的名字的過程與解析import
語句里模塊名的過程類似。 所以可以簡單的把三斜線類型引用指令想像成針對包的import
聲明。
僅當在你需要寫一個d.ts
文件時才使用這個指令。
對於那些在編譯階段生成的聲明文件,編譯器會自動地添加/// <reference types="..." />
; 當且僅當結果文件中使用了引用的@types
包里的聲明時才會在生成的聲明文件里添加/// <reference types="..." />
語句。
若要在.ts
文件里聲明一個對@types
包的依賴,使用--types
命令行選項或在tsconfig.json
里指定。
/// <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" />
告訴編譯器有一個非TypeScript模塊依賴需要被注入,做為目標模塊require
調用的一部分。
amd-dependency
指令也可以帶一個可選的name
屬性;它允許我們為amd-dependency傳入一個可選名字:
/// <amd-dependency path="legacy/moduleA" name="moduleA"/> declare var moduleA:MyType moduleA.callStuff()
生成的JavaScript代碼:
define(["require", "exports", "legacy/moduleA"], function (require, exports, moduleA) { moduleA.callStuff() });