TypeScript 官方手册翻译计划【十三】：模块
- 说明：目前网上没有 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: anyCommonJS 和 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，取决于你希望执行 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 保持一致。在命名空间的参考章节中，你可以了解到更多相关信息。
腾讯云开发者
