模块

全局模块

默认情况下，当你开始在一个新的 TypeScript 文件中写下代码时，它处于全局命名空间中。如在 foo.ts 里的以下代码：

  1. const foo = 123;

如果你在相同的项目里创建了一个新的文件 bar.ts，TypeScript 类型系统将会允许你使用变量 foo，就好像它在全局可用一样：

  1. const bar = foo; // allowed

毋庸置疑，使用全局变量空间是危险的，因为它会与文件内的代码命名冲突。我们推荐使用下文中将要提到的文件模块。

文件模块

它也被称为外部模块。如果在你的 TypeScript 文件的根级别位置含有 import 或者 export，它会在这个文件中创建一个本地的作用域。因此，我们需要把上文 foo.ts 改成如下方式（注意 export 用法）：

  1. export const foo = 123;

在全局命名空间里，我们不再有 foo，这可以通过创建一个新文件 bar.ts 来证明：

  1. const bar = foo; // ERROR: "cannot find name 'foo'"

如果你想在 bar.ts 里使用来自 foo.ts 的内容，你必须显式导入它，更新 bar.ts 如下所示：

  1. import { foo } from './foo';
  2. const bar = foo; // allow

在 bar.ts 文件里使用 import，不但允许你使用从其他文件导入的内容，而且它会将此文件 bar.ts 标记为一个模块，文件内定义的声明也不会污染全局命名空间。

文件模块详情

文件模块拥有强大的能力和可用性。在这里，我们来讨论它的能力以及一些用法。

澄清：commonjs, amd, es modules, others

首先，我们需要澄清这些模块系统的不一致性。我将会提供给你我当前的建议，以及消除一些顾虑。

你可以根据不同的 module 选项来把 TypeScript 编译成不同的 JavaScript 模块类型，这有一些你可以忽略的：

  • AMD：不要使用它，它仅能在浏览器工作；
  • SystemJS：这是一个好的实验，已经被 ES 模块替代；
  • ES 模块：它并没有准备好。
    使用 module: commonjs 选项来替代这些模式，这会是一个好的主意。

怎么书写 TypeScript 模块，这也是一件让人困惑的事。在今天我们应该这么做：

  • import foo = require('foo') 例如： import/require 使用 ES 模块语法。
    这很酷，接下来，让我们看看 ES 模块语法。

TIP

使用 module: commonjs 选项以及使用 ES 模块语法导入导出其他模块。

ES 模块语法

  • 使用 export 关键字导出一个变量（或者类型）：
  1. // foo.ts
  2. export const someVar = 123;
  3. export type someType = {
  4.   foo: string;
  5. };
  • export 的写法除了上面这样，还有另外一种：
  1. // foo.ts
  2. const someVar = 123;
  3. type someType = {
  4.   type: string;
  5. };
  7. export { someVar, someType };
  • 你也可以重命名变量导出：
  1. // foo.ts
  2. const someVar = 123;
  3. export { someVar as aDifferentName };
  • 使用 import 关键字导入一个变量或者是一个类型：
  1. // bar.ts
  2. import { someVar, someType } from './foo';
  • 重命名导入变量或者类型：
  1. // bar.ts
  2. import { someVar as aDifferentName } from './foo';
  • 除了指定加载某个输出值，还可以使用整体加载，即用星号（*）指定一个对象，所有输出值都加载在这个对象上面：
  1. // bar.ts
  2. import * as foo from './foo';
  3. // 你可以使用 `foo.someVar` 和 `foo.someType` 以及其他任何从 `foo` 导出的变量或者类型
  • 仅导入模块：
  1. import 'core-js'; // 一个普通的 polyfill 库
  • 从其他模块导入后整体导出：
  1. export * from './foo';
  • 从其他模块导入后，部分导出：
  1. export { someVar } from './foo';
  • 通过重命名，部分导出从另一个模块导入的项目：
  1. export { someVar as aDifferentName } from './foo';

默认导入／导出

我并不喜欢用默认导出，虽然有默认导出的语法：

  • 使用 export default
    • 在一个变量之前（不需要使用 let/const/var）；
    • 在一个函数之前；
    • 在一个类之前。
  1. // some var
  2. export default (someVar = 123);
  4. // some function
  5. export default function someFunction() {}
  7. // some class
  8. export default class someClass {}
  • 导入使用 import someName from 'someModule' 语法（你可以根据需要为导入命名）：
  1. import someLocalNameForThisFile from './foo';

模块路径

TIP

假设你使用 moduleResolution: node 选项。这个选项应该在你 TypeScript 配置文件里。如果你使用了 module: commonjs 选项， moduleResolution: node 将会默认开启。

这里存在两种不同截然不同的模块，它们是由导入语句中的不同的路径写法所引起的（例如：import foo from 'THIS IS THE PATH SECTION'）。

  • 相对模块路径（路径以 . 开头，例如：./someFile 或者 ../../someFolder/someFile 等）；
  • 其他动态查找模块（如：core-js，typestyle，react 或者甚至是 react/core 等）。
    它们的主要区别来自于系统如何解析模块。

TIP

我将会使用一个概念性术语，place — 将在提及查找模式后解释它。

相对模块路径

这很简单，仅仅是按照相对路径：

  • 如果文件 bar.ts 中含有 import * as foo from './foo'，foo 文件所存在的地方必须是相同文件夹下；
  • 如果文件 bar.ts 中含有 import * as foo from '../foo'，foo 文件所存在的地方必须是上一级目录；
  • 如果文件 bar.ts 中含有 import * as foo from '../someFolder/foo'，foo 文件所在的文件夹 someFolder 必须与 bar.ts 所在文件夹在相同的目录下。
    或者，你还可以想想其他相对路径导入的情景。?

动态查找

当导入路径不是相对路径时，模块解析将会模仿 Node 模块解析策略，以下我将给出一个简单例子：

  • 当你使用 import * as foo from 'foo'，将会按如下顺序查找模块：
    • ./node_modules/foo
    • ../node_modules/foo
    • ../../node_modules/foo
    • 直到系统的根目录
  • 当你使用 import * as foo from 'something/foo'，将会按照如下顺序查找内容
    • ./node_modules/something/foo
    • ../node_modules/something/foo
    • ../../node_modules/something/foo
    • 直到系统的根目录

什么是 place

当我提及被检查的 place 时，我想表达的是在这个 place，TypeScript 将会检查以下内容（例如一个 foo 的位置）：

  • 如果这个 place 表示一个文件，如：foo.ts，欢呼！
  • 否则，如果这个 place 是一个文件夹，并且存在一个文件 foo/index.ts，欢呼！
  • 否则，如果这个 place 是一个文件夹，并且存在一个 foo/package.json 文件，在该文件中指定 types 的文件存在，那么就欢呼！
  • 否则，如果这个 place 是一个文件夹，并且存在一个 package.json 文件，在该文件中指定 main 的文件存在，那么就欢呼！
    从文件类型上来说，我实际上是指 .ts， .d.ts 或者 .js

就是这样，现在你已经是一个模块查找专家（这并不是一个小小的成功）。

重写类型的动态查找

在你的项目里，你可以通过 declare module 'somePath' 来声明一个全局模块的方式，用来解决查找模块路径的问题：

  1. // globals.d.ts
  2. declare module 'foo' {
  3.   // some variable declarations
  4.   export var bar: number;
  5. }

接着：

  1. // anyOtherTsFileInYourProject.ts
  2. import * as foo from 'foo';
  3. // TypeScript 将假设（在没有做其他查找的情况下）
  4. // foo 是 { bar: number }

import/require 仅仅是导入类型

以下导入语法：

  1. import foo = require('foo');

它实际上只做了两件事：

  • 导入 foo 模块的所有类型信息；
  • 确定 foo 模块运行时的依赖关系。
    你可以选择仅加载类型信息，而没有运行时的依赖关系。在继续之前，你可能需要重新阅读本书的 声明空间部分 部分。

如果你没有把导入的名称当做变量声明空间来用，在编译成 JavaScript 时，导入的模块将会被完全移除。这有一些较好的例子，当你了解了它们之后，我们将会给出一些使用例子。

例子 1

  1. import foo = require('foo');

将会编译成 JavaScript：

这是正确的，一个没有被使用的空文件。

例子 2

  1. import foo = require('foo');
  2. var bar: foo;

将会被编译成：

  1. let bar;

这是因为 foo （或者其他任何属性如：foo.bas）没有被当做一个变量使用。

例子 3

  1. import foo = require('foo');
  2. const bar = foo;

将会被编译成（假设是 commonjs）：

  1. const foo = require('foo');
  2. const bar = foo;

这是因为 foo 被当做变量使用了。

使用例子：懒加载

类型推断需要提前完成，这意味着，如果你想在 bar 文件里，使用从其他文件 foo 导出的类型，你将不得不这么做：

  1. import foo = require('foo');
  2. let bar: foo.SomeType;

然而，在某些情景下，你只想在需要时加载模块 foo，此时你需要仅在类型注解中使用导入的模块名称，而不是在变量中使用。在编译成 JavaScript 式，这些将会被移除。接着，你可以手动导入你需要的模块。

做为一个例子，考虑以下基于 commonjs 的代码，我们仅在一个函数内导入 foo 模块：

  1. import foo = require('foo');
  3. export function loadFoo() {
  4.   // 这是懒加载 foo，原始的加载仅仅用来做类型注解
  5.   const _foo: typeof foo = require('foo');
  6.   // 现在，你可以使用 `_foo` 替代 `foo` 来做为一个变量使用
  7. }

一个同样简单的 amd 模块（使用 requirejs）：

  1. import foo = require('foo');
  3. export function loadFoo() {
  4.   // 这是懒加载 foo，原始的加载仅仅用来做类型注解
  5.   require(['foo'], (_foo: typeof foo) => {
  6.     // 现在，你可以使用 `_foo` 替代 `foo` 来做为一个变量使用
  7.   });
  8. }

这些通常在以下情景使用：

  • 在 web app 里， 当你在特定路由上加载 JavaScript 时；
  • 在 node 应用里，当你只想加载特定模块，用来加快启动速度时。

使用例子：打破循环依赖

类似于懒加载的使用用例，某些模块加载器（commonjs/node 和 amd/requirejs）不能很好的处理循环依赖。在这种情况下，一方面我们使用延迟加载代码，并在另一方面预先加载模块时很实用的。

使用例子：确保导入

当你加载一个模块，只是想引入其附加的作用（如：模块可能会注册一些像 CodeMirror addons）时，然而，如果你仅仅是 import/require （导入）一些并没有与你的模块或者模块加载器有任何依赖的 JavaScript 代码，（如：webpack），经过 TypeScript 编译后，这些将会被完全忽视。在这种情况下，你可以使用一个 ensureImport 变量，来确保编译的 JavaScript 依赖与模块。如：

  1. import foo = require('./foo');
  2. import bar = require('./bar');
  3. import bas = require('./bas');
  5. const ensureImport: any = foo || bar || bas;

globals.d.ts

在上文中，当我们讨论文件模块时，比较了全局变量与文件模块，并且我们推荐使用基于文件的模块，而不是选择污染全局命名空间。

然而，如果你的团队里有 TypeScript 初学者，你可以提供他们一个 globals.d.ts 文件，用来将一些接口或者类型放入全局命名空间里，这些定义的接口和类型能在你的所有 TypeScript 代码里使用。

TIP

对于任何需要编译成 JavaScript 代码，我们强烈建议你放入文件模块里。

  • globals.d.ts 是一种扩充 lib.d.ts 很好的方式，如果你需要。
  • 当你从 TS 迁移到 JS 时，定义 declare module "some-library-you-dont-care-to-get-defs-for" 能让你快速开始。

原文: https://jkchao.github.io/typescript-book-chinese/project/modules.html