蛋蛋的博客

一般来讲，*组织*声明文件的方式取决于代码库是如何被使用的。在 JavaScript 中一个代码库有很多使用方式，这就需要你书写声明文件去匹配它们。这篇指南涵盖了如何识别常见代码库的模式，以及怎样书写符合相应模式的声明文件。

这篇指南的目的是教你如何书写高质量的 TypeScript 声明文件。

声明文件一章的目的是教你如何编写高质量的 TypeScript 声明文件。我们假设你对 TypeScript 已经有了基本的了解。

如果一个目录下存在一个`tsconfig.json`文件，那么它意味着这个目录是TypeScript项目的根目录。 `tsconfig.json`文件中指定了用来编译这个项目的根文件和编译选项。 一个项目可以通过以下方式之一来编译：

与其它构建工具整合

编译器支持使用环境变量配置如何监视文件和目录的变化。

编译选项可以在使用MSBuild的项目里通过MSBuild属性指定。

编译选项

让我们使用TypeScript来创建一个简单的Web应用。

`let`和`const`是JavaScript里相对较新的变量声明方式。 [像我们之前提到过的](basic-types.md#a-note-about-let)，`let`在很多方面与`var`是相似的，但是可以帮助大家避免在JavaScript里常见一些问题。 `const`是对`let`的一个增强，它能阻止对一个变量再次赋值。

TypeScript 提供一些工具类型来帮助常见的类型转换。这些类型是全局可见的。

这节介绍TypeScript里的类型推论。即，类型是在哪里如何被推断的。

TypeScript里的类型兼容性是基于结构子类型的。 结构类型是一种只使用其成员来描述类型的方式。 它正好与名义（nominal）类型形成对比。（译者注：在基于名义类型的类型系统中，数据类型的兼容性或等价性是通过明确的声明和/或类型的名称来决定的。这与结构性类型系统不同，它是基于类型的组成结构，且不要求明确地声明。）

三斜线指令是包含单个XML标签的单行注释。 注释的内容会做为编译器指令使用。三斜线指令_仅_可放在包含它的文件的最顶端。 一个三斜线指令的前面只能出现单行或多行注释，这包括其它的三斜线指令。 如果它们出现在一个语句或声明之后，那么它们会被当做普通的单行注释，并且不具有特殊的涵义。

自ECMAScript 2015起，symbol成为了一种新的原生类型，就像number和string一样。

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

这篇文章描述了如何在TypeScript里使用命名空间（之前叫做“内部模块”）来组织你的代码。 就像我们在术语说明里提到的那样，“内部模块”现在叫做“命名空间”。 另外，任何使用module关键字来声明一个内部模块的地方都应该使用namespace关键字来替换。 这就避免了让新的使用者被相似的名称所迷惑。

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

_模块解析_是指编译器在查找导入模块内容时所遵循的流程。 假设有一个导入语句import { a } from "moduleA"; 为了去检查任何对a的使用，编译器需要准确的知道它表示什么，并且需要检查它的定义moduleA。这时候，编译器会有个疑问“moduleA的结构是怎样的？” 这听上去很简单，但moduleA可能在你写的某个.ts/.tsx文件里或者在你的代码所依赖的.d.ts里。

除了传统的面向对象继承方式，还流行一种通过可重用组件创建类的方式，就是联合另一个简单类的代码。 你可能在Scala等语言里对mixins及其特性已经很熟悉了，但它在JavaScript中也是很流行的。

JSX是一种嵌入式的类似XML的语法。 它可以被转换成合法的JavaScript，尽管转换的语义是依据不同的实现而定的。 JSX因React框架而流行，但也存在其它的实现。 TypeScript支持内嵌，类型检查以及将JSX直接编译为JavaScript。

当一个对象实现了Symbol.iterator属性时，我们认为它是可迭代的。 一些内置的类型如Array，Map，Set，String，Int32Array，Uint32Array等都已经实现了各自的Symbol.iterator。 对象上的Symbol.iterator函数负责返回供迭代的值。

随着TypeScript和ES6里引入了类，在一些场景下我们需要额外的特性来支持标注或修改类及其成员。 装饰器（Decorators）为我们在类的声明及成员上通过元编程语法添加标注提供了一种方式。 Javascript里的装饰器目前处在建议征集的第二阶段，但在TypeScript里已做为一项实验性特性予以支持。

TypeScript中有些独特的概念可以在类型层面上描述JavaScript对象的模型。 这其中尤其独特的一个例子是“声明合并”的概念。 理解了这个概念，将有助于操作现有的JavaScript代码。 同时，也会有助于理解更多高级抽象的概念。

交叉类型是将多个类型合并为一个类型。 这让我们可以把现有的多种类型叠加到一起成为一种类型，它包含了所需的所有类型的特性。 例如，`Person & Serializable & Loggable`同时是`Person`_和_`Serializable`_和_`Loggable`。 就是说这个类型的对象同时拥有了这三种类型的成员。

在 JavaScript 中，对象是我们最基本的组织和传递数据的方式。在 TypeScript 中，我们通过*对象类型*来表示它们。

假设我们有一个名为padLeft的函数。如果padding是一个number，它将把它作为我们想要在input前面添加的空格数。如果padding是一个string，它应该只是将padding添加到input前面。让我们尝试为当向padLeft的padding参数传递一个number时实现逻辑。糟糕，我们得到padding相关的错误。TypeScript 警告我们正在将类型为的值传递给repeat函数，而该函数只接受一个number参数，而它是正确的。换句话说，我们没有明确检查padding是否为。

函数是任何应用程序的基本构建块，它们可以是本地函数、从另一个模块导入的函数或者类的方法。它们也是值，并且与其他值一样，TypeScript 有很多方法来描述函数的调用方式。让我们来学习如何编写用于描述函数的类型。

JavaScript 历来具有多种处理代码模块化的方式。TypeScript 自 2012 年问世以来，已经实现了对这其中很多格式的支持。但随着时间的推移，社区和 JavaScript 规范已经趋于使用一种称为 ES 模块（或 ES6 模块）的格式。它使用的是 `import`/`export` 语法。ES 模块在 2015 年被添加到 JavaScript 规范中，并且截至 2020 年已经在大多数 Web 浏览器和 JavaScript 运行时中得到广泛支持。

在本章中，我们将介绍一些在 JavaScript 代码中最常见的值的类型，并说明在 TypeScript 中描述这些类型相应的方法。这不是一个详尽的列表，后续章节将描述命名和使用其他类型的更多方法。

TypeScript-类

TypeScript基础

5分钟了解TypeScript