typescript模块与命名空间

最新推荐文章于 2024-08-08 19:36:20 发布

大金牙卡菜

最新推荐文章于 2024-08-08 19:36:20 发布

阅读量622

点赞数 25

文章标签：网络 udp 网络协议

本文链接：https://blog.csdn.net/wubeidangziqiang/article/details/138348459

版权

一、模块

关于术语的一点说明: 请务必注意一点，TypeScript 1.5里术语名已经发生了变化。 “内部模块”现在称做“命名空间”。 “外部模块”现在则简称为“模块”，这是为了与 ECMAScript 2015里的术语保持一致，(也就是说 module X { 相当于现在推荐的写法 namespace X {)。

1. 介绍

从ECMAScript 2015开始，JavaScript引入了模块的概念。TypeScript 也沿用这个概念。

模块在其自身的作用域里执行，而不是在全局作用域里；这意味着定义在一个模块里的变量，函数，类等等在模块外部是不可见的，除非你明确地使用 export 形式之一导出它们。相反，如果想使用其它模块导出的变量，函数，类，接口等的时候，你必须要导入它们，可以使用 import 形式之一。

模块是自声明的；两个模块之间的关系是通过在文件级别上使用 imports 和 exports 建立的。

模块使用模块加载器去导入其它的模块。 在运行时，模块加载器的作用是在执行此模块代码前去查找并执行这个模块的所有依赖。大家最熟知的 JavaScript 模块加载器是服务于 Node.js 的 CommonJS 和服务于 Web 应用的Require.js。

TypeScript 与 ECMAScript 2015 一样，任何包含顶级 import 或者 export 的文件都被当成一个模块。相反地，如果一个文件不带有顶级的 import 或者 export 声明，那么它的内容被视为全局可见的（因此对模块也是可见的）。

2. 导出

1> 导出声明

任何声明（比如变量，函数，类，类型别名或接口）都能够通过添加 export 关键字来导出。

// Validation.ts

export interface StringValidator {
    isAcceptable(s: string): boolean;
}

// ZipCodeValidator.ts
export const numberRegexp = /^[0-9]+$/;

export class ZipCodeValidator implements StringValidator {
    isAcceptable(s: string) {
        return s.length === 5 && numberRegexp.test(s);
    }
}

2> 导出语句

导出语句很便利，因为我们可能需要对导出的部分重命名，所以上面的例子可以这样改写：

class ZipCodeValidator implements StringValidator {
    isAcceptable(s: string) {
        return s.length === 5 && numberRegexp.test(s);
    }
}
export { ZipCodeValidator };
export { ZipCodeValidator as mainValidator };

3> 重新导出

我们经常会去扩展其它模块，并且只导出那个模块的部分内容。 重新导出功能并不会在当前模块导入那个模块或定义一个新的局部变量。

// ParseIntBasedZipCodeValidator.ts
export class ParseIntBasedZipCodeValidator {
    isAcceptable(s: string) {
        return s.length === 5 && parseInt(s).toString() === s;
    }
}

// 导出原先的验证器但做了重命名
export {ZipCodeValidator as RegExpBasedZipCodeValidator} from "./ZipCodeValidator";

或者一个模块可以包裹多个模块，并把他们导出的内容联合在一起通过语法：export * from "module"。

// AllValidators.ts

export * from "./StringValidator"; // exports interface StringValidator
export * from "./LettersOnlyValidator"; // exports class LettersOnlyValidator
export * from "./ZipCodeValidator";  // exports class ZipCodeValidator

3. 导入

模块的导入操作与导出一样简单。可以使用以下 import 形式之一来导入其它模块中的导出内容。

1> 导入一个模块中的某个导出内容

import { ZipCodeValidator } from "./ZipCodeValidator";

let myValidator = new ZipCodeValidator();

2> 可以对导入内容重命名

import { ZipCodeValidator as ZCV } from "./ZipCodeValidator";
let myValidator = new ZCV();

3> 将整个模块导入到一个变量，并通过它来访问模块的导出部分

import * as validator from "./ZipCodeValidator";
let myValidator = new validator.ZipCodeValidator();

4> 具有副作用的导入模块

尽管不推荐这么做，一些模块会设置一些全局状态供其它模块使用。这些模块可能没有任何的导出或用户根本就不关注它的导出。使用下面的方法来导入这类模块：

import "./my-module.js";

4. 默认导出

每个模块都可以有一个 default 导出。默认导出使用 default 关键字标记；并且一个模块只能够有一个 default 导出。需要使用一种特殊的导入形式来导入 default 导出。

default 导出十分便利。比如，像JQuery这样的类库可能有一个默认导出 jQuery或$，并且我们基本上也会使用同样的名字jQuery或$导出JQuery。

// JQuery.d.ts

declare let $: JQuery;
export default $;

// App.ts
import $ from "JQuery";

$("button.continue").html( "Next Step..." );

类和函数声明可以直接被标记为默认导出。标记为默认导出的类和函数的名字是可以省略的。

// ZipCodeValidator.ts
export default class ZipCodeValidator {
    static numberRegexp = /^[0-9]+$/;
    isAcceptable(s: string) {
        return s.length === 5 && ZipCodeValidator.numberRegexp.test(s);
    }
}

// Test.ts
import validator from "./ZipCodeValidator";

let myValidator = new validator();

或者

// StaticZipCodeValidator.ts
const numberRegexp = /^[0-9]+$/;

export default function (s: string) {
    return s.length === 5 && numberRegexp.test(s);
}

// Test.ts
import validate from "./StaticZipCodeValidator";

let strings = ["Hello", "98052", "101"];

// Use function validate
strings.forEach(s => {
  console.log(`"${s}" ${validate(s) ? " matches" : " does not match"}`);
});

default 导出也可以是一个值

// OneTwoThree.ts
export default "123";

// Log.ts
import num from "./OneTwoThree";

console.log(num); // "123"

5. export = 和 import = require()

CommonJS 和 AMD 的环境里都有一个 exports 变量，这个变量包含了一个模块的所有导出内容。

CommonJS 和 AMD 的 exports 都可以被赋值为一个对象, 这种情况下其作用就类似于 es6 语法里的默认导出，即 export default 语法了。虽然作用相似，但是 export default 语法并不能兼容 CommonJS 和 AMD 的 exports。

为了支持 CommonJS 和 AMD 的 exports, TypeScript 提供了 export = 语法。

export = 语法定义一个模块的导出对象。这里的对象一词指的是类，接口，命名空间，函数或枚举。

若使用 export = 导出一个模块，则必须使用 TypeScript 的特定语法 import module = require("module") 来导入此模块。

// ZipCodeValidator.ts
let numberRegexp = /^[0-9]+$/;
class ZipCodeValidator {
    isAcceptable(s: string) {
        return s.length === 5 && numberRegexp.test(s);
    }
}
export = ZipCodeValidator;

// Test.ts
import zip = require("./ZipCodeValidator");

// Some samples to try
let strings = ["Hello", "98052", "101"];

// Validators to use
let validator = new zip();

// Show whether each string passed each validator
strings.forEach(s => {
  console.log(`"${ s }" - ${ validator.isAcceptable(s) ? "matches" : "does not match" }`);
});

二、生成模块代码

根据编译时指定的模块目标参数，编译器会生成相应的供 Node.js (CommonJS)，Require.js (AMD)，UMD，SystemJS 或 ECMAScript 2015 native modules (ES6)模块加载系统使用的代码。想要了解生成代码中 define，require 和 register 的意义，请参考相应模块加载器的文档。

下面的例子说明了导入导出语句里使用的名字是怎么转换为相应的模块加载器代码的。

// SimpleModule.ts
import m = require("mod");
export let t = m.something + 1;

// Native ECMAScript 2015 modules SimpleModule.js
import { something } from "./mod";
export let t = something + 1;

// CommonJS / Node SimpleModule.js
let mod_1 = require("./mod");
exports.t = mod_1.something + 1;

1. 简单示例

下面我们来整理一下前面的验证器实现，每个模块只有一个命名的导出。

为了编译，我们必需要在命令行上指定一个模块目标。对于Node.js 来说，使用 --module commonjs；对于Require.js 来说，使用 --module amd。比如：

tsc --module commonjs Test.ts

编译完成后，每个模块会生成一个单独的.js文件。好比使用了reference标签，编译器会根据 import语句编译相应的文件。

// Validation.ts
export interface StringValidator {
    isAcceptable(s: string): boolean;
}

// LettersOnlyValidator.ts
import { StringValidator } from "./Validation";

const lettersRegexp = /^[A-Za-z]+$/;

export class LettersOnlyValidator implements StringValidator {
    isAcceptable(s: string) {
        return lettersRegexp.test(s);
    }
}

// ZipCodeValidator.ts
import { StringValidator } from "./Validation";

const numberRegexp = /^[0-9]+$/;

export class ZipCodeValidator implements StringValidator {
    isAcceptable(s: string) {
        return s.length === 5 && numberRegexp.test(s);
    }
}

// Test.ts
import { StringValidator } from "./Validation";
import { ZipCodeValidator } from "./ZipCodeValidator";
import { LettersOnlyValidator } from "./LettersOnlyValidator";

// Some samples to try
let strings = ["Hello", "98052", "101"];

// Validators to use
let validators: { [s: string]: StringValidator; } = {};
validators["ZIP code"] = new ZipCodeValidator();
validators["Letters only"] = new LettersOnlyValidator();

// Show whether each string passed each validator
strings.forEach(s => {
    for (let name in validators) {
        console.log(`"${ s }" - ${ validators[name].isAcceptable(s) ? "matches" : "does not match" } ${ name }`);
    }
});

三、使用其它的JavaScript库

要想描述非 TypeScript 编写的类库的类型，我们需要声明类库所暴露出的 API。

我们叫它声明因为它不是“外部程序”的具体实现。它们通常是在 .d.ts 文件里定义的。如果你熟悉 C/C++，你可以把它们当做 .h 文件。让我们看一些例子。

1. 外部模块

在 Node.js 里大部分工作是通过加载一个或多个模块实现的。我们可以使用顶级的 export 声明来为每个模块都定义一个 .d.ts 文件，但最好还是写在一个大的 .d.ts 文件里。我们使用与构造一个外部命名空间相似的方法，但是这里使用 module 关键字并且把名字用引号括起来，方便之后 import。例如：

// node.d.ts (simplified excerpt)
declare module "url" {
    export interface Url {
        protocol?: string;
        hostname?: string;
        pathname?: string;
    }

    export function parse(urlStr: string, parseQueryString?, slashesDenoteHost?): Url;
}

declare module "path" {
    export function normalize(p: string): string;
    export function join(...paths: any[]): string;
    export let sep: string;
}

现在我们可以 /// <reference> node.d.ts 并且使用import url = require("url"); 或 import * as URL from "url" 加载模块。

// 三斜线指令 "///" 用来引入类型定义文件（.d.ts 文件），告诉编译器当前文件需要使用某个类型声明包，这对于使用外部库的类型信息非常有用。
// 这些三斜线指令通常位于文件的顶部
/// <reference path="node.d.ts"/>
import * as URL from "url";
let myUrl = URL.parse("http://www.typescriptlang.org");

1> 外部模块简写

假如你不想在使用一个新模块之前花时间去编写声明，你可以采用声明的简写形式以便能够快速使用它。

// declarations.d.ts
declare module "hot-new-module";

简写模块里所有导出的类型将是 any。

import x, {y} from "hot-new-module";
x(y);

四、创建模块结构指导

1. 尽可能地在顶层导出

用户应该更容易地使用你模块导出的内容。嵌套层次过多会变得难以处理，因此仔细考虑一下如何组织你的代码。

从你的模块中导出一个命名空间就是一个增加嵌套的例子。虽然命名空间有时候有它们的用处，在使用模块的时候它们额外地增加了一层。这对用户来说是很不便的并且通常是多余的。

导出类的静态方法也有同样的问题 - 这个类本身就增加了一层嵌套。除非它能方便表述或便于清晰使用，否则请考虑直接导出一个辅助方法。

2. 如果仅导出单个 class 或 function，使用 export default

就像“在顶层上导出”帮助减少用户使用的难度，一个默认的导出也能起到这个效果。如果一个模块就是为了导出特定的内容，那么你应该考虑使用一个默认导出。这会令模块的导入和使用变得些许简单。比如：

// MyClass.ts
export default class SomeType {
  constructor() { ... }
}

// MyFunc.ts
export default function getThing() { return 'thing'; }

// Consumer.ts
import t from "./MyClass";
import f from "./MyFunc";
let x = new t();
console.log(f());

对用户来说这是最理想的。他们可以随意命名导入模块的类型（本例为 t）并且不需要多余的（.）来找到相关对象。

3. 如果要导出多个对象，把它们放在顶层里导出

// MyThings.ts
export class SomeType { /* ... */ }
export function someFunc() { /* ... */ }

4. 当导入的时候：明确地列出导入的名字

// Consumer.ts
import { SomeType, someFunc } from "./MyThings";
let x = new SomeType();
let y = someFunc();

5. 使用命名空间导入模式当你要导出大量内容的时候

// MyLargeModule.ts
export class Dog { ... }
export class Cat { ... }
export class Tree { ... }
export class Flower { ... }

// Consumer.ts
import * as myLargeModule from "./MyLargeModule.ts";
let x = new myLargeModule.Dog();

6. 使用重新导出进行扩展

你可能经常需要去扩展一个模块的功能。 JS 里常用的一个模式是 JQuery 那样去扩展原对象。如我们之前提到的，模块不会像全局命名空间对象那样去合并。推荐的方案是不要去改变原来的对象，而是导出一个新的实体来提供新的功能。

假设 Calculator.ts 模块里定义了一个简单的计算器实现。这个模块同样提供了一个辅助函数来测试计算器的功能，通过传入一系列输入的字符串并在最后给出结果。

// Calculator.ts
export class Calculator {
    private current = 0;
    private memory = 0;
    private operator: string;

    protected processDigit(digit: string, currentValue: number) {
        if (digit >= "0" && digit <= "9") {
            return currentValue * 10 + (digit.charCodeAt(0) - "0".charCodeAt(0));
        }
    }

    protected processOperator(operator: string) {
        if (["+", "-", "*", "/"].indexOf(operator) >= 0) {
            return operator;
        }
    }

    protected evaluateOperator(operator: string, left: number, right: number): number {
        switch (this.operator) {
            case "+": return left + right;
            case "-": return left - right;
            case "*": return left * right;
            case "/": return left / right;
        }
    }

    private evaluate() {
        if (this.operator) {
            this.memory = this.evaluateOperator(this.operator, this.memory, this.current);
        }
        else {
            this.memory = this.current;
        }
        this.current = 0;
    }

    public handleChar(char: string) {
        if (char === "=") {
            this.evaluate();
            return;
        }
        else {
            let value = this.processDigit(char, this.current);
            if (value !== undefined) {
                this.current = value;
                return;
            } else {
                let value = this.processOperator(char);
                if (value !== undefined) {
                    this.evaluate();
                    this.operator = value;
                    return;
                }
            }
        }
        throw new Error(`Unsupported input: '${char}'`);
    }

    public getResult() {
        return this.memory;
    }
}

export function test(c: Calculator, input: string) {
    for (let i = 0; i < input.length; i++) {
        c.handleChar(input[i]);
    }

    console.log(`result of '${input}' is '${c.getResult()}'`);
}

下面使用导出的 test 函数来测试计算器。

// TestCalculator.ts
import { Calculator, test } from "./Calculator";

let c = new Calculator();
test(c, "1+2*33/11="); // prints 9

现在扩展它，添加支持输入其它进制（十进制以外），让我们来创建 ProgrammerCalculator.ts。

// ProgrammerCalculator.ts
import { Calculator } from "./Calculator";

class ProgrammerCalculator extends Calculator {
    static digits = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "A", "B", "C", "D", "E", "F"];

    constructor(public base: number) {
        super();
        const maxBase = ProgrammerCalculator.digits.length;
        if (base <= 0 || base > maxBase) {
            throw new Error(`base has to be within 0 to ${maxBase} inclusive.`);
        }
    }

    protected processDigit(digit: string, currentValue: number) {
        if (ProgrammerCalculator.digits.indexOf(digit) >= 0) {
            return currentValue * this.base + ProgrammerCalculator.digits.indexOf(digit);
        }
    }
}

// Export the new extended calculator as Calculator
export { ProgrammerCalculator as Calculator };

// Also, export the helper function
export { test } from "./Calculator";

新的 ProgrammerCalculator 模块导出的API与原先的Calculator模块很相似，但却没有改变原模块里的对象。下面是测试ProgrammerCalculator类的代码：

// TestProgrammerCalculator.ts
import { Calculator, test } from "./ProgrammerCalculator";

let c = new Calculator(2);
test(c, "001+010="); // prints 3

7. 模块里不要使用命名空间

当初次进入基于模块的开发模式时，可能总会控制不住要将导出包裹在一个命名空间里。模块具有其自己的作用域，并且只有导出的声明才会在模块外部可见。记住这点，命名空间在使用模块时几乎没什么价值。

在组织方面，命名空间对于在全局作用域内对逻辑上相关的对象和类型进行分组是很便利的。例如，在C#里，你会从 System.Collections里找到所有集合的类型。通过将类型有层次地组织在命名空间里，可以方便用户找到与使用那些类型。然而，模块本身已经存在于文件系统之中，这是必须的。我们必须通过路径和文件名找到它们，这已经提供了一种逻辑上的组织形式。我们可以创建 /collections/generic/ 文件夹，把相应模块放在这里面。

命名空间对解决全局作用域里命名冲突来说是很重要的。比如，你可以有一个 My.Application.Customer.AddForm和My.Application.Order.AddForm -- 两个类型的名字相同，但命名空间不同。然而，这对于模块来说却不是一个问题。在一个模块里，没有理由两个对象拥有同一个名字。从模块的使用角度来说，使用者会挑出他们用来引用模块的名字，所以也没有理由发生重名的情况。

五、命名空间

1. 介绍

“内部模块”现在叫做“命名空间”。另外，任何使用 module 关键字来声明一个内部模块的地方都应该使用 namespace 关键字来替换。这就避免了让新的使用者被相似的名称所迷惑。

2. 第一步

我们先来写一段程序并将在整篇文章中都使用这个例子。我们定义几个简单的字符串验证器，假设你会使用它们来验证表单里的用户输入或验证外部数据。所有的验证器都放在一个文件里

interface StringValidator {
    isAcceptable(s: string): boolean;
}

let lettersRegexp = /^[A-Za-z]+$/;
let numberRegexp = /^[0-9]+$/;

class LettersOnlyValidator implements StringValidator {
    isAcceptable(s: string) {
        return lettersRegexp.test(s);
    }
}

class ZipCodeValidator implements StringValidator {
    isAcceptable(s: string) {
        return s.length === 5 && numberRegexp.test(s);
    }
}

// Some samples to try
let strings = ["Hello", "98052", "101"];

// Validators to use
let validators: { [s: string]: StringValidator; } = {};
validators["ZIP code"] = new ZipCodeValidator();
validators["Letters only"] = new LettersOnlyValidator();

// Show whether each string passed each validator
for (let s of strings) {
    for (let name in validators) {
        let isMatch = validators[name].isAcceptable(s);
        console.log(`'${ s }' ${ isMatch ? "matches" : "does not match" } '${ name }'.`);
    }
}

3. 命名空间

随着更多验证器的加入，我们需要一种手段来组织代码，以便于在记录它们类型的同时还不用担心与其它对象产生命名冲突。因此，我们 把验证器包裹到一个命名空间内，而不是把它们放在全局命名空间下。

下面的例子里，把所有与验证器相关的类型都放到一个叫做 Validation 的命名空间里。因为我们想让这些接口和类在命名空间之外也是可访问的，所以需要使用 export。相反的，变量 lettersRegexp 和 numberRegexp 是实现的细节，不需要导出，因此它们在命名空间外是不能访问的。在文件末尾的测试代码里，由于是在命名空间之外访问，因此需要限定类型的名称，比如 Validation.LettersOnlyValidator。

使用命名空间的验证器

namespace Validation {
    export interface StringValidator {
        isAcceptable(s: string): boolean;
    }

    const lettersRegexp = /^[A-Za-z]+$/;
    const numberRegexp = /^[0-9]+$/;

    export class LettersOnlyValidator implements StringValidator {
        isAcceptable(s: string) {
            return lettersRegexp.test(s);
        }
    }

    export class ZipCodeValidator implements StringValidator {
        isAcceptable(s: string) {
            return s.length === 5 && numberRegexp.test(s);
        }
    }
}

// Some samples to try
let strings = ["Hello", "98052", "101"];

// Validators to use
let validators: { [s: string]: Validation.StringValidator; } = {};
validators["ZIP code"] = new Validation.ZipCodeValidator();
validators["Letters only"] = new Validation.LettersOnlyValidator();

// Show whether each string passed each validator
for (let s of strings) {
    for (let name in validators) {
        console.log(`"${ s }" - ${ validators[name].isAcceptable(s) ? "matches" : "does not match" } ${ name }`);
    }
}

4. 分离到多文件

当应用变得越来越大时，我们需要将代码分离到不同的文件中以便于维护。

多文件中的命名空间 现在，我们把 Validation 命名空间分割成多个文件。 尽管是不同的文件，它们仍是同一个命名空间，并且在使用的时候就如同它们在一个文件中定义的一样。因为不同文件之间存在依赖关系，所以我们加入了引用标签来告诉编译器文件之间的关联。我们的测试代码保持不变。

// Validation.ts
namespace Validation {
    export interface StringValidator {
        isAcceptable(s: string): boolean;
    }
}

// LettersOnlyValidator.ts
/// <reference path="Validation.ts" />
namespace Validation {
    const lettersRegexp = /^[A-Za-z]+$/;
    export class LettersOnlyValidator implements StringValidator {
        isAcceptable(s: string) {
            return lettersRegexp.test(s);
        }
    }
}

// ZipCodeValidator.ts
/// <reference path="Validation.ts" />
namespace Validation {
    const numberRegexp = /^[0-9]+$/;
    export class ZipCodeValidator implements StringValidator {
        isAcceptable(s: string) {
            return s.length === 5 && numberRegexp.test(s);
        }
    }
}

// Test.ts
/// <reference path="Validation.ts" />
/// <reference path="LettersOnlyValidator.ts" />
/// <reference path="ZipCodeValidator.ts" />

// Some samples to try
let strings = ["Hello", "98052", "101"];

// Validators to use
let validators: { [s: string]: Validation.StringValidator; } = {};
validators["ZIP code"] = new Validation.ZipCodeValidator();
validators["Letters only"] = new Validation.LettersOnlyValidator();

// Show whether each string passed each validator
for (let s of strings) {
    for (let name in validators) {
        console.log(`"${ s }" - ${ validators[name].isAcceptable(s) ? "matches" : "does not match" } ${ name }`);
    }
}

当涉及到多文件时，我们必须确保所有编译后的代码都被加载了。我们有两种方式。

第一种方式，把所有的输入文件编译为一个输出文件，需要使用 --outFile 标记：
```
tsc --outFile sample.js Test.ts
```
编译器会根据源码里的引用标签自动地对输出进行排序。你也可以单独地指定每个文件。
```
tsc --outFile sample.js Validation.ts LettersOnlyValidator.ts ZipCodeValidator.ts Test.ts
```
第二种方式，我们可以编译每一个文件（默认方式），那么每个源文件都会对应生成一个 JavaScript 文件。然后，在页面上通过 <script> 标签把所有生成的 JavaScript 文件按正确的顺序引进来，比如：

<!-- MyTestPage.html (excerpt) -->
<script src="Validation.js" type="text/javascript" />
<script src="LettersOnlyValidator.js" type="text/javascript" />
<script src="ZipCodeValidator.js" type="text/javascript" />
<script src="Test.js" type="text/javascript" />

5. 别名

另一种简化命名空间操作的方法是使用 import q = x.y.z 给常用的对象起一个短的名字。不要与用来加载模块的 import x = require('name') 语法弄混了，这里的语法是为指定的符号创建一个别名。你可以用这种方法为任意标识符创建别名，也包括导入的模块中的对象。

namespace Shapes {
    export namespace Polygons {
        export class Triangle { }
        export class Square { }
    }
}

import polygons = Shapes.Polygons;
let sq = new polygons.Square(); // Same as "new Shapes.Polygons.Square()"

注意，我们并没有使用 require 关键字，而是直接使用导入符号的限定名赋值。这与使用 var 相似，但它还适用于类型和导入的具有命名空间含义的符号。重要的是，对于值来讲， import 会生成与原始符号不同的引用，所以改变别名的 var 值并不会影响原始变量的值。

6. 使用其它的 `JavaScript` 库

为了描述不是用 TypeScript 编写的类库的类型，我们需要声明类库导出的 API。由于大部分程序库只提供少数的顶级对象，命名空间是用来表示它们的一个好办法。

我们称其为声明是因为它不是外部程序的具体实现。我们通常在 .d.ts 里写这些声明。如果你熟悉 C/C++，你可以把它们当做 .h 文件。让我们看一些例子。

外部命名空间 流行的程序库 D3 在全局对象 d3 里定义它的功能。因为这个库通过一个 <script> 标签加载（不是通过模块加载器），它的声明文件使用内部模块来定义它的类型。为了让 TypeScript 编译器识别它的类型，我们使用外部命名空间声明。比如，我们可以像下面这样写：

// D3.d.ts (部分摘录)
declare namespace D3 {
    export interface Selectors {
        select: {
            (selector: string): Selection;
            (element: EventTarget): Selection;
        };
    }

    export interface Event {
        x: number;
        y: number;
    }

    export interface Base extends Selectors {
        event: Event;
    }
}

declare var d3: D3.Base;

六、命名空间和模块的应用

这里将概括介绍在 TypeScript 里使用模块与命名空间来组织代码的方法。我们也会谈及命名空间和模块的高级使用场景，和在使用它们的过程中常见的陷阱。

1. 使用命名空间

命名空间是位于全局命名空间下的一个普通的带有名字的JavaScript对象。这令命名空间十分容易使用。它们可以在多文件中同时使用，并通过 --outFile 结合在一起。命名空间是帮你组织Web应用不错的方式，你可以把所有依赖都放在HTML页面的 <script> 标签里。

但就像其它的全局命名空间污染一样，它很难去识别组件之间的依赖关系，尤其是在大型的应用中。

2. 使用模块

像命名空间一样，模块可以包含代码和声明。不同的是模块可以声明它的依赖。

模块会把依赖添加到模块加载器上（例如 CommonJs / Require.js）。对于小型的JS应用来说可能没必要，但是对于大型应用，这一点点的花费会带来长久的模块化和可维护性上的便利。模块也提供了更好的代码重用，更强的封闭性以及更好的使用工具进行优化。

对于 Node.js 应用来说，模块是默认并推荐的组织代码的方式。

从 ECMAScript 2015 开始，模块成为了语言内置的部分，应该会被所有正常的解释引擎所支持。因此，对于新项目来说推荐使用模块做为组织代码的方式。

3. 命名空间和模块的陷阱

这部分我们会描述常见的命名空间和模块的使用陷阱和如何去避免它们。

3.1 对模块使用 `/// <reference>`

一个常见的错误是使用 /// <reference> 引用模块文件，应该使用 import。要理解这之间的区别，我们首先应该弄清编译器是如何根据 import 路径（例如，import x from "..."; 或 import x = require("...") 里面的...，等等）来定位模块的类型信息的。

编译器首先尝试去查找相应路径下的 .ts，.tsx 再或者 .d.ts。如果这些文件都找不到，编译器会查找外部模块声明。回想一下，它们是在 .d.ts 文件里声明的。

// myModules.d.ts

// In a .d.ts file or .ts file that is not a module:
declare module "SomeModule" {
    export function fn(): string;
}

// myOtherModule.ts

/// <reference path="myModules.d.ts" />
import * as m from "SomeModule";

这里的引用标签指定了外来模块的位置。这就是一些 TypeScript 例子中引用 node.d.ts 的方法。

3.2 不必要的命名空间

如果你想把命名空间转换为模块，它可能会像下面这个文件一件：

// shapes.ts
export namespace Shapes {
    export class Triangle { /* ... */ }
    export class Square { /* ... */ }
}

顶层的模块 Shapes 包裹了 Triangle 和 Square。对于使用它的人来说这是令人迷惑和讨厌的：

// shapeConsumer.ts
import * as shapes from "./shapes";
let t = new shapes.Shapes.Triangle(); // shapes.Shapes?

TypeScript 里模块的一个特点是不同的模块永远也不会在相同的作用域内使用相同的名字。因为使用模块的人会为它们命名，所以完全没有必要把导出的符号包裹在一个命名空间里。

再次重申，不应该对模块使用命名空间，使用命名空间是为了提供逻辑分组和避免命名冲突。模块文件本身已经是一个逻辑分组，并且它的名字是由导入这个模块的代码指定，所以没有必要为导出的对象增加额外的模块层。

下面是改进的例子：

// shapes.ts
export class Triangle { /* ... */ }
export class Square { /* ... */ }

// shapeConsumer.ts
import * as shapes from "./shapes";
let t = new shapes.Triangle();

3.3 模块的取舍

就像每个 JS 文件对应一个模块一样，TypeScript 里模块文件与生成的 JS 文件也是一一对应的。这会产生一种影响，根据你指定的目标模块系统的不同，你可能无法连接多个模块源文件。例如当目标模块系统为 commonjs 或 umd 时，无法使用 outFile 选项，但是在 TypeScript 1.8 以上的版本能够使用 outFile 当目标为 amd 或 system。