文档教程【免费下载链接】TypeScriptTypeScript 使用手册中文版翻译。http://www.typescriptlang.org项目地址https://gitcode.com/gh_mirrors/typ/TypeScript点击查看免费下载三斜线指令是 TypeScript 编译器提供的特殊单行注释语法用于在编译期声明文件间的依赖、引入类型包、控制默认库与 AMD 模块命名。本文基于 TypeScript 使用手册中文版进阶手册中的《三斜线指令》一节结合仓库内 编译选项、tsconfig.json 配置 与 声明文件写作 等关联文档系统讲解五种三斜线指令的语法、行为与适用场景。读完本文你将能准确写出可被编译器识别的/// reference path /、/// reference types /、/// reference no-default-lib /、/// amd-module /与/// amd-dependency /并理解它们在预处理、--outFile输出排序和声明文件发布中的实际作用。什么是三斜线指令三斜线指令是包含单个 XML 标签的单行注释注释内容会被编译器当作指令处理/// reference path./other.ts /它的命名来源于行首的///三个斜杠与普通注释//和/* */区分开来。需要注意的关键约束是三斜线指令仅可放在包含它的文件的最顶端在一个三斜线指令的前面只能出现单行或多行注释这包括其它的三斜线指令如果三斜线指令出现在一个语句或声明之后那么它会被当做普通的单行注释处理不再具有特殊涵义。也就是说三斜线指令必须位于文件头部可被其它注释覆盖一旦代码开始之后的///就只是普通注释了。从源码结构看这也是编译器在解析源文件时先扫描头部注释区、再进入语句解析的原因所在。/// reference path... /声明文件间依赖/// reference path... /是三斜线指令中最常见的一种用于声明文件间的依赖。它告诉编译器在编译过程中要引入path所指向的额外文件。/// reference path./globals.d.ts /预处理输入文件编译器会对输入文件进行预处理来解析所有三斜线引用指令在这个过程中额外的文件会被加入到编译过程中。整个处理流程遵循以下规则预处理从一些根文件开始——它们是在命令行中指定的文件或是在tsconfig.json的files列表里的文件根文件按指定的顺序进行预处理在一个文件被加入列表前它包含的所有三斜线引用都要被处理包括它们所指向的目标文件三斜线引用以它们在文件里出现的顺序使用深度优先的方式解析。关于路径解析有一条重要规则一个三斜线引用路径是相对于包含它的文件的如果该文件不是根文件。错误情形引用不存在的文件会报错一个文件用三斜线指令引用自己会报错。与--noResolve的配合如果指定了--noResolve编译选项三斜线引用会被忽略它们不会增加新文件也不会改变给定文件的顺序。根据仓库内 编译选项表 的描述--noResolve的完整语义是不把/// reference或模块导入的文件加到编译文件列表默认值为false。它同时影响三斜线引用与模块导入两类文件引入机制。用--outFile控制输出顺序当使用--out已废弃见 编译选项或--outFile时三斜线引用还可以作为调整输出内容顺序的一种方法文件在输出文件内容中的位置与经过预处理后的输入顺序一致。在 编译选项表 中对此的说明是合并的顺序取决于传入编译器的文件顺序以及/// reference和import的文件顺序且只有AMD和System两种模块系统能与--outFile一起使用。/// reference types... /声明对类型包的依赖与/// reference path... /相似用于声明文件依赖/// reference types... /指令声明的是对某个包的依赖。这些包的名字的解析方式与import语句里模块名的解析类似——可以简单地把三斜线类型引用指令当做import声明的包。/// reference typesnode /例如把/// reference typesnode /引入到声明文件表明这个文件使用了types/node/index.d.ts里面声明的名字并且这个包需要在编译阶段与声明文件一起被包含进来。使用时的核心注意事项仅当需要写一个.d.ts文件时才使用这个指令对于那些在编译阶段生成的声明文件编译器会自动地添加/// reference types... /且当且仅当结果文件中使用了引用的包里的声明时才会在生成的声明文件里添加该语句若要在.ts文件里声明对types包的依赖应该使用--types命令行选项或在tsconfig.json里指定详见 tsconfig.json 中的types、typeRoots和types。在声明文件的写作实践中这一指令有明确的使用指引。仓库内 声明文件·库结构 一节指出如果全局代码库依赖于某个全局库或 UMD 模块应使用/// reference types... /声明依赖/// reference typessomeLib / function getThing(): someLib.thing;而 声明文件·发布 一节则给出了发布声明文件时的危险信号不要在声明文件里使用/// reference path... /因为它会把内部文件路径暴露给使用者且依赖关系不随 npm 包正确解析应该改用/// reference types... /// 不要这样写 /// reference path../typescript/lib/typescriptServices.d.ts / .... // 应该这样写 /// reference typestypescript / ....现代手册v2中也保留了该语法的应用场景例如在 手册 v2·模块 中使用/// reference typesnode /声明import fs require(fs)所需的 Node 全局类型。相关配置types、typeRoots与types因为三斜线类型引用解析的是types包理解 tsconfig.json 中的相关配置很有必要默认行为所有可见的types包都会在编译过程中被包含进来即node_modules/types文件夹下以及其子文件夹下的所有包./node_modules/types/、../node_modules/types/、../../node_modules/types/等等typeRoots如果指定了typeRoots只有typeRoots下面的包才会被包含进来。例如配置typeRoots: [./typings]后编译器只包含./typings下的包而不再包含./node_modules/types里的包types如果指定了types只有被列出来的包才会被包含进来。例如types: [node, lodash, express]将仅包含./node_modules/types/node、./node_modules/types/lodash和./node_modules/types/express指定types: []可以禁用自动引入types包注意自动引入只在使用全局声明相对于模块时是重要的如果使用import foo语句TypeScript 仍会查找node_modules和node_modules/types文件夹来获取foo包。/// reference no-default-libtrue/标记默认库这个指令把一个文件标记成默认库。你会在lib.d.ts文件和它不同变体的顶端看到这个注释/// reference no-default-libtrue/该指令告诉编译器在编译过程中不要包含这个默认库比如lib.d.ts这与在命令行上使用--noLib相似。根据 编译选项表 的说明--noLib的语义就是不包含默认的库文件lib.d.ts。还要注意当传递了--skipDefaultLibCheck时编译器只会忽略检查带有/// reference no-default-libtrue/的文件。在 编译选项表 中--skipDefaultLibCheck被描述为忽略库的默认声明文件的类型检查默认值为false。这两个选项都与默认库文件lib.d.ts及其变体的包含与检查行为相关是理解 TypeScript 如何注入内置lib类型的关键补充。/// amd-module /为 AMD 模块命名默认情况下生成的 AMD 模块都是匿名的。但是当一些工具需要处理生成的模块时会产生问题比如r.jsRequireJS 的优化打包工具。amd-module指令允许给编译器传入一个可选的模块名amdModule.ts///amd-module nameNamedModule/ export class C {}这会将NamedModule传入到 AMDdefine函数里amdModule.jsdefine(NamedModule, [require, exports], function (require, exports) { var C (function () { function C() {} return C; })(); exports.C C; });可以看到define的第一个参数由匿名的空位变成了字符串NamedModule这使 r.js 等工具能够按模块名进行依赖分析和合并。该指令与--module amd编译选项配合使用是面向 AMD 模块化打包工作流的专门手段。/// amd-dependency /注入非 TypeScript 模块依赖注意这个指令已被废弃应使用import moduleName;语句代替。/// amd-dependency pathx /告诉编译器有一个非 TypeScript 模块依赖需要被注入作为目标模块require调用的一部分。amd-dependency指令也可以带一个可选的name属性允许为注入的依赖传入一个可选名字/// amd-dependency pathlegacy/moduleA namemoduleA/ declare var moduleA: MyType; moduleA.callStuff();生成的 JavaScript 代码define([require, exports, legacy/moduleA], function ( require, exports, moduleA ) { moduleA.callStuff(); });注意legacy/moduleA被自动加入到了define的依赖数组[require, exports, legacy/moduleA]中且通过可选的name属性回调参数直接以moduleA的名字注入从而可以在 TypeScript 源码中通过declare var moduleA: MyType;声明其类型后直接调用。该指令适合处理无法用 TypeScript 类型系统描述、但必须在 AMD 运行时前置加载的遗留 JS 模块官方已明确建议新代码改用import moduleName;这种标准写法。总结与实践建议三斜线指令是 TypeScript 编译器在预处理阶段的指令性注释五种指令各司其职指令作用典型场景/// reference path... /声明文件间依赖控制编译输入与--outFile输出顺序手工组织的多文件项目、旧式全局脚本/// reference types... /声明对types包的依赖编写.d.ts声明文件、发布 npm 类型包/// reference no-default-libtrue/把文件标记为默认库配合--noLib/--skipDefaultLibChecklib.d.ts及其变体/// amd-module /为生成的 AMD 模块指定模块名r.js 等 AMD 打包工具/// amd-dependency /已废弃注入非 TypeScript 模块依赖遗留 AMD 项目新代码改用import moduleName;在实际项目中建议遵循以下原则三斜线指令必须置于文件顶端且仅出现在注释之后、代码之前在.ts源码中声明对types包的依赖优先使用 tsconfig.json 中的types/typeRoots配置而不是/// reference types编写和发布.d.ts声明文件时使用/// reference types... /声明包级依赖避免使用/// reference path... /参见 声明文件·发布需要控制合并输出文件顺序时可以利用--outFile仅配合AMD或System模块系统见 编译选项通过--noResolve、--noLib、--skipDefaultLibCheck等 编译选项 可以精确控制三斜线指令与默认库的行为边界。理解三斜线指令的解析规则根文件起步、深度优先、相对路径、--noResolve忽略能帮助你准确预判编译输入集合与输出文件顺序在维护全局脚本风格项目或发布类型声明包时避免踩坑。赞分享文档教程【免费下载链接】TypeScriptTypeScript 使用手册中文版翻译。http://www.typescriptlang.org项目地址https://gitcode.com/gh_mirrors/typ/TypeScript点击查看免费下载相关推荐TypeScript 三斜线指令Triple-Slash Directives实战指南从声明文件引用到编译器行为控制TypeScript 三斜线指令Triple Slash Directives实战指南从声明文件引用到编译器行为控制 本文基于《The Concise T文档教程TypeScript 三斜线指令Triple-Slash Directives详解从 /// reference 到编译器选项TypeScript 三斜线指令Triple Slash Directives详解从 /// reference 到编译器选项 三斜线指令是 TypeS文档教程The Concise TypeScript Book 精讲TypeScript 三斜线指令Triple-Slash Directives完整指南The Concise TypeScript Book 精讲TypeScript 三斜线指令Triple Slash Directives完整指南 三斜线文档教程上一篇BiliRoamingX终极指南5个必知技巧让你的B站体验全面升级下一篇B站Android客户端终极优化指南哔哩漫游X让你的观看体验全面升级创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考