共计 5913 个字符,预计需要花费 15 分钟才能阅读完成。
- 阐明 :目前网上没有 TypeScript 最新官网文档的中文翻译,所以有了这么一个翻译打算。因为我也是 TypeScript 的初学者,所以无奈保障翻译百分之百精确,若有谬误,欢送评论区指出;
- 翻译内容 :暂定翻译内容为 TypeScript Handbook,后续有空会补充翻译文档的其它局部;
- 我的项目地址 :TypeScript-Doc-Zh,如果对你有帮忙,能够点一个 star ~
本章节官网文档地址:Modules
模块
解决模块化代码的形式很多,JavaScript 在这方面有着悠久的历史。TypeScript 诞生于 2012 年,对许多模块化计划也实现了反对。但随着工夫的推移,社区和 JavaScript 标准在一种名为 ES 模块(或者称为 ES6 模块)的计划上达成了共识。你可能据说过它的 import/export
语法。
ES 模块于 2015 年被纳入 JavaScript 标准,到了 2020 年,它曾经取得了少数 web 浏览器和 JavaScript 运行时的反对。
本手册会重点解说 ES 模块以及在它之前十分风行的、提供了 module.exports =
语法的 CommonJS。在“参考”章节的模块这一大节中,你能够理解到更多对于其它模块化计划的信息。
JavaScript 的模块是如何定义的
和 ECMAScript 2015 一样,TypeScript 会将任何蕴含顶层 import
或者 export
的文件视为一个模块。
反过来,一个不蕴含顶层 import
或者 export
申明的文件会被视为一个脚本,它的内容能够在全局作用域中拜访到(因而对模块也是可见的)。
模块在本身的作用域而非全局作用域中执行。这意味着在一个模块中申明的变量、函数和类等在模块里面是不可见的,除非应用其中一种导出形式将它们显式导出。反过来,为了应用从某个不同的模块中导出的变量、函数、类等,也须要应用其中一种导入形式将它们导入。
非模块
在咱们开始之前,有个很重要的事件须要搞清楚,那就是 TypeScript 会将什么视为一个模块。JavaScript 标准表明,任何不蕴含 export
或者顶层 await
的 JavaScript 文件都应该被视为一个脚本,而不是一个模块。
在一个脚本文件中申明的变量和类型会位于共享的全局作用域中,而且通常状况下,你会应用 outFile 编译选项将多个输出文件合并为一个输入文件,或者应用 HTML 文件中的多个 <script>
标签去(以正确的程序!)加载文件。
如果你的文件以后没有任何的 import
或者 export
,然而你想将其视为一个模块,那么能够增加上面这行代码:
export {};
这会将文件转化为没有导出任何货色的一个模块。不论你的模块指标是什么,这个语法都能够失效。
TypeScript 中的模块
在 TypeScript 中编写基于模块的代码时,有三件次要的事件须要思考:
- 语法: 我想要应用什么语法去进行导入和导出?
- 模块解析: 模块名(或者门路)和磁盘上的文件有什么关系?
- 模块输入指标: 产生的 JavaScript 模块看起来应该是什么样子的?
ES 模块语法
一个文件能够通过 export default
申明一个次要的导出:
// @filename: hello.ts
export default function helloWorld() {console.log("Hello, world!");
}
接着通过上面的语句导入:
import hello from "./hello.js";
hello();
除了默认导出之外,你还能够省略 default
,间接用 export
导出多个变量和函数:
// @filename: maths.ts
export var pi = 3.14;
export let squareTwo = 1.41;
export const phi = 1.61;
export class RandomNumberGenerator {}
export function absolute(num: number) {if (num < 0) return num * -1;
return num;
}
你能够通过 import
语法在另一个文件中导入:
import {pi, phi, absolute} from "./maths.js";
console.log(pi);
const absPhi = absolute(phi);
^
// const absPhi: number
其它导入语法
能够应用诸如 import {old as new}
这样的模式重新命名一个导入:
import {pi as π} from "./maths.js";
console.log(π);
^
//(alias) var π: number
// import π
你能够将上述语法混合为单个 import
:
// @filename: maths.ts
export const pi = 3.14;
export default class RandomNumberGenerator {}
// @filename: app.ts
import RNGen, {pi as π} from "./maths.js";
RNGen;
^
//(alias) class RNGen
//import RNGen
console.log(π);
^
// (alias) const π: 3.14
// import π
应用 * as name
,你能够承受所有导出对象,并将它们放入单个命名空间中:
// @filename: app.ts
import * as math from "./maths.js";
console.log(math.pi);
const positivePhi = math.absolute(math.phi);
^
// const positivePhi: number
应用 import "./file"
,你能够在以后模块中仅导入文件,而不导入文件中的任何变量:
// @filename: app.ts
import "./maths.js";
console.log("3.14");
在这种状况下,import
不会做任何事。不过,math.ts
中的所有代码都会被执行,这可能会触发副作用并影响其它对象。
TypeScript 专属的 ES 模块语法
你能够应用和 JavaScript 值一样的语法将类型进行导出和导入:
// @filename: animal.ts
export type Cat = {breed: string; yearOfBirth: number};
export interface Dog {breeds: string[];
yearOfBirth: number;
}
// @filename: app.ts
import {Cat, Dog} from "./animal.js";
type Animals = Cat | Dog;
TypeScript 为 import
语法拓展了两个用处,让它能够申明类型导入:
import type
该导入语句只能导入类型:
// @filename: animal.ts
export type Cat = {breed: string; yearOfBirth: number};
// 'createCatName' cannot be used as a value because it was imported using 'import type'.
export type Dog = {breeds: string[]; yearOfBirth: number };
export const createCatName = () => "fluffy";
// @filename: valid.ts
import type {Cat, Dog} from "./animal.js";
export type Animals = Cat | Dog;
// @filename: app.ts
import type {createCatName} from "./animal.js";
const name = createCatName();
内联 type
导入
TypeScript 4.5 也容许单个导入应用 type
前缀表明导入的援用是一个类型:
// @filename: app.ts
import {createCatName, type Cat, type Dog} from "./animal.js";
export type Animals = Cat | Dog;
const name = createCatName();
所有这些都容许诸如 Babel、swc 或者 esbuild 这样的非 TypeScript 转译工具晓得哪些导入是能够被平安地移除的。
具备 CommonJS 行为的 ES 模块语法
TypeScript 的 ES 模块语法能够和 CommonJS 与 AMD 的 require
间接关联。在大多数状况下,应用 ES 模块的导入与雷同环境下应用 require
是一样的,但这个语法能够确保你的 TypeScript 文件和 CommonJS 输入存在一对一的匹配:
import fs = require("fs");
const code = fs.readFileSync("hello.ts", "utf8");
你能够在模块这一参考章节中理解到更多对于该语法的信息。
CommonJS 语法
CommonJS 是大多数 npm 包采纳的模块化计划。即便你编写代码的时候采纳的是 ES 模块语法,简要理解一下 CommonJS 语法的工作形式也有助于简化你的调试过程。
导出
通过给一个名为 module
的全局对象设置 exports
属性,你能够导出标识符:
function absolute(num: number) {if (num < 0) return num * -1;
return num;
}
module.exports = {
pi: 3.14,
squareTwo: 1.41,
phi: 1.61,
absolute,
};
之后能够通过 require
申明导入这些文件:
const maths = require("maths");
maths.pi;
^
// any
或者你也能够应用 JavaScript 的解构语法只导入一部分内容:
const {squareTwo} = require("maths");
squareTwo;
^
// const squareTwo: any
CommonJS 和 ES 模块的互操作
因为默认导入和模块命名空间对象导入的差别,CommonJS 和 ES 模块在性能上存在不匹配的中央。TypeScript 提供了一个编译选项 esModuleInterop,以缩小这两组不同的束缚之间的抵触。
TypeScript 的模块解析选项
模块解析是一个过程,它指的是从 import
或者 require
申明中提取一个字符串,并确定该字符串所批示的文件。
TypeScript 应用两种解析策略:Classic 和 Node。应用 Classic 策略是为了实现向后兼容,当编译选项 module 不是 commonjs
的时候,默认采纳该策略。Node 策略则复刻了 Node.js 在 CommonJS 模式下的工作形式,并提供了额定的 .ts
和 .d.ts
查看。
还有很多 TSConfig 选项会影响到 TypeScript 中的模块策略,包含:moduleResolution、baseUrl、paths、rootDirs。
无关这些策略如何工作的详细信息,请浏览模块解析。
TypeScript 的模块输入选项
有两个选项会影响到最终输入的 JavaScript:
- target 会决定哪些 JS 个性会被降级(进行转化并运行在比拟旧的 JavaScript 运行时),哪些 JS 个性会被保留
- module 会决定模块之间进行交互所应用的代码
应用哪个 target,取决于你心愿执行 TypeScript 代码的 JavaScript 运行时能够应用的个性。这样的运行时能够是:你反对的最旧的浏览器,你心愿能够运行的最低版本的 Node.js,或者从运行时 —— 比方 Electron 的惟一束缚进行考量。
模块之间的所有通信通过一个模块加载器进行,编译选项 module 会决定应该应用哪一个。在运行时,模块加载器负责在执行模块之前定位并执行模块的所有依赖。
举个例子,这是一个应用 ES 模块语法的 TypeScript 文件:
import {valueOfPi} from "./constants.js";
export const twoPi = valueOfPi * 2;
上面是应用不同的 module 选项之后的编译后果:
ES2020
import {valueOfPi} from "./constants.js";
export const twoPi = valueOfPi * 2;
CommonJS
"use strict";
Object.defineProperty(exports, "__esModule", { value: true});
exports.twoPi = void 0;
const constants_js_1 = require("./constants.js");
exports.twoPi = constants_js_1.valueOfPi * 2;
UMD
(function (factory) {if (typeof module === "object" && typeof module.exports === "object") {var v = factory(require, exports);
if (v !== undefined) module.exports = v;
}
else if (typeof define === "function" && define.amd) {define(["require", "exports", "./constants.js"], factory);
}
})(function (require, exports) {
"use strict";
Object.defineProperty(exports, "__esModule", { value: true});
exports.twoPi = void 0;
const constants_js_1 = require("./constants.js");
exports.twoPi = constants_js_1.valueOfPi * 2;
});
留神:ES2020 实际上和原先的 index.ts 是一样的。
你能够在 TSConfig 这一参考章节的“模块”大节中理解到所有可用的选项以及对应输入的 JavaScript 代码是怎么样的。
TypeScript 命名空间
TypeScript 有本人的模块格局,名为“命名空间”,它比 ES 模块规范呈现得要早。这个语法提供了很多有用的个性以创立简单的定义文件,并且依然广泛应用于 DefinitelyTyped 中。尽管该语法还没有被弃用,但鉴于 ES 模块曾经领有了命名空间的大部分个性,咱们举荐你应用 ES 模块来跟 JavaScript 保持一致。在命名空间的参考章节中,你能够理解到更多相干信息。