Repository: xcatliu/typescript-tutorial
Branch: master
Commit: 1b71bebef402
Files: 161
Total size: 147.8 KB
Directory structure:
gitextract_f_xb4944/
├── .editorconfig
├── .eslintignore
├── .eslintrc.js
├── .github/
│ ├── FUNDING.yml
│ └── workflows/
│ └── gh-pages.yml
├── .gitignore
├── .lintmdrc
├── .npmrc
├── .prettierignore
├── .prettierrc.js
├── .vscode/
│ └── settings.json
├── README.md
├── TypeScript 入门教程 2020.epub
├── TypeScript 入门教程.epub
├── advanced/
│ ├── README.md
│ ├── class-and-interfaces.md
│ ├── class.md
│ ├── declaration-merging.md
│ ├── decorator.md
│ ├── enum.md
│ ├── further-reading.md
│ ├── generics.md
│ ├── string-literal-types.md
│ ├── tuple.md
│ └── type-aliases.md
├── basics/
│ ├── README.md
│ ├── any.md
│ ├── built-in-objects.md
│ ├── declaration-files.md
│ ├── primitive-data-types.md
│ ├── type-assertion.md
│ ├── type-inference.md
│ ├── type-of-array.md
│ ├── type-of-function.md
│ ├── type-of-object-interfaces.md
│ └── union-types.md
├── engineering/
│ ├── README.md
│ ├── compiler-options.md
│ └── lint.md
├── examples/
│ ├── compiler-options/
│ │ ├── 01-allowJs/
│ │ │ ├── false/
│ │ │ │ ├── lib/
│ │ │ │ │ └── index.js
│ │ │ │ ├── package.json
│ │ │ │ ├── src/
│ │ │ │ │ ├── foo.js
│ │ │ │ │ └── index.ts
│ │ │ │ └── tsconfig.json
│ │ │ └── true/
│ │ │ ├── lib/
│ │ │ │ ├── foo.js
│ │ │ │ └── index.js
│ │ │ ├── package.json
│ │ │ ├── src/
│ │ │ │ ├── foo.js
│ │ │ │ └── index.ts
│ │ │ └── tsconfig.json
│ │ └── 02-allowSyntheticDefaultImports/
│ │ ├── false/
│ │ │ ├── package.json
│ │ │ ├── src/
│ │ │ │ └── index.ts
│ │ │ └── tsconfig.json
│ │ └── true/
│ │ ├── package.json
│ │ ├── src/
│ │ │ └── index.ts
│ │ └── tsconfig.json
│ └── declaration-files/
│ ├── 01-jquery/
│ │ ├── src/
│ │ │ └── index.ts
│ │ └── tsconfig.json
│ ├── 02-declare-var/
│ │ ├── src/
│ │ │ └── index.ts
│ │ └── tsconfig.json
│ ├── 03-jquery-d-ts/
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 04-declare-const-jquery/
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 05-declare-jquery-value/
│ │ ├── src/
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 06-declare-function/
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 07-declare-class/
│ │ ├── src/
│ │ │ ├── Animal.d.ts
│ │ │ └── index.ts
│ │ └── tsconfig.json
│ ├── 08-declare-enum/
│ │ ├── src/
│ │ │ ├── Directions.d.ts
│ │ │ └── index.ts
│ │ └── tsconfig.json
│ ├── 09-declare-namespace/
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 10-declare-namespace-nesting/
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 11-declare-namespace-dot/
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 12-interface/
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 13-avoid-name-conflict/
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 14-declaration-merging/
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 15-export/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo/
│ │ └── index.d.ts
│ ├── 16-declare-and-export/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo/
│ │ └── index.d.ts
│ ├── 17-export-namespace/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo/
│ │ └── index.d.ts
│ ├── 18-export-default/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo/
│ │ └── index.d.ts
│ ├── 19-export-default-enum-error/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo/
│ │ └── index.d.ts
│ ├── 20-export-default-enum/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo/
│ │ └── index.d.ts
│ ├── 21-export-equal/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo/
│ │ └── index.d.ts
│ ├── 22-export-as-namespace/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo/
│ │ └── index.d.ts
│ ├── 23-merge-global-interface/
│ │ ├── src/
│ │ │ └── index.ts
│ │ └── tsconfig.json
│ ├── 24-merge-global-namespace/
│ │ ├── package.json
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── jquery-plugin/
│ │ └── index.d.ts
│ ├── 25-declare-global/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo/
│ │ └── index.d.ts
│ ├── 26-declare-module/
│ │ ├── package.json
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── moment-plugin/
│ │ └── index.d.ts
│ ├── 27-multiple-declare-module/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo-bar.d.ts
│ ├── 28-triple-slash-directives/
│ │ ├── package.json
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── jquery-plugin/
│ │ └── index.d.ts
│ ├── 29-triple-slash-directives-global/
│ │ ├── package.json
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── node-plugin/
│ │ └── index.d.ts
│ └── 30-auto-d-ts/
│ ├── lib/
│ │ ├── bar/
│ │ │ ├── index.d.ts
│ │ │ └── index.js
│ │ ├── index.d.ts
│ │ └── index.js
│ ├── package.json
│ ├── src/
│ │ ├── bar/
│ │ │ └── index.ts
│ │ └── index.ts
│ └── tsconfig.json
├── introduction/
│ ├── README.md
│ ├── get-typescript.md
│ ├── hello-typescript.md
│ ├── what-is-typescript.md
│ └── why-typescript.md
├── package.json
├── pagic.config.tsx
├── pandoc-list.txt
├── pandoc-metadata.txt
└── thanks/
└── README.md
================================================
FILE CONTENTS
================================================
================================================
FILE: .editorconfig
================================================
# EditorConfig is awesome: https://EditorConfig.org
# top-most EditorConfig file
root = true
# Unix-style newlines with a newline ending every file
[*]
end_of_line = lf
insert_final_newline = true
# Matches multiple files with brace expansion notation
# Set default charset
[*]
charset = utf-8
# 4 space indentation
# [*]
# indent_style = space
# indent_size = 4
================================================
FILE: .eslintignore
================================================
*.d.ts
================================================
FILE: .eslintrc.js
================================================
module.exports = {
extends: ['alloy', 'alloy/react', 'alloy/typescript'],
env: {
// Your environments (which contains several predefined global variables)
//
// browser: true,
// mocha: true,
// jquery: true
},
globals: {
// Your global variables (setting to false means it's not allowed to be reassigned)
//
// myGlobal: false
},
rules: {
// Customize your rules
'no-undef': 'off',
'prefer-arrow-callback': 'off',
'@typescript-eslint/no-invalid-this': 'off',
'@typescript-eslint/no-require-imports': 'off',
'@typescript-eslint/method-signature-style': 'off',
},
};
================================================
FILE: .github/FUNDING.yml
================================================
# These are supported funding model platforms
github: xcatliu
patreon: # Replace with a single Patreon username
open_collective: # Replace with a single Open Collective username
ko_fi: # Replace with a single Ko-fi username
tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
liberapay: # Replace with a single Liberapay username
issuehunt: # Replace with a single IssueHunt username
otechie: # Replace with a single Otechie username
custom: https://github.com/xcatliu/buy-me-a-coffee
================================================
FILE: .github/workflows/gh-pages.yml
================================================
name: gh-pages
on:
push:
branches:
- master
jobs:
build-and-deploy:
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 0
- name: Setup deno
uses: denolib/setup-deno@v2
with:
deno-version: v1.34.1
- name: Build gh-pages
run: |
curl -fsSL https://deno.land/x/install/install.sh | sh
export DENO_INSTALL="/home/runner/.deno"
export PATH="$DENO_INSTALL/bin:$PATH"
deno --version
deno install --unstable --allow-read --allow-write --allow-net --allow-run -n pagic https://deno.land/x/pagic@v1.6.3/mod.ts
pagic build
- name: Deploy gh-pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./dist
cname: ts.xcatliu.com
================================================
FILE: .gitignore
================================================
.DS_Store
node_modules
dist
================================================
FILE: .lintmdrc
================================================
{
"excludeFiles": [],
"rules": {
"no-trailing-punctuation": 0,
"no-long-code": 0
}
}
================================================
FILE: .npmrc
================================================
registry=https://registry.npmjs.org/
================================================
FILE: .prettierignore
================================================
*.md
*.png
*.epub
node_modules
assets
.DS_Store
.editorconfig
.eslintignore
.gitignore
.lintmdrc
.prettierignore
.npmrc
pnpm-lock.yaml
examples
dist
================================================
FILE: .prettierrc.js
================================================
// .prettierrc.js
module.exports = {
// 一行最多 120 字符
printWidth: 120,
// 使用 2 个空格缩进
tabWidth: 2,
// 不使用缩进符，而使用空格
useTabs: false,
// 行尾需要有分号
semi: true,
// 使用单引号
singleQuote: true,
// 对象的 key 仅在必要时用引号
quoteProps: 'as-needed',
// jsx 不使用单引号，而使用双引号
jsxSingleQuote: false,
// 末尾需要有逗号
trailingComma: 'all',
// 大括号内的首尾需要空格
bracketSpacing: true,
// jsx 标签的反尖括号需要换行
bracketSameLine: false,
// 箭头函数，只有一个参数的时候，也需要括号
arrowParens: 'always',
// 每个文件格式化的范围是文件的全部内容
rangeStart: 0,
rangeEnd: Infinity,
// 不需要写文件开头的 @prettier
requirePragma: false,
// 不需要自动在文件开头插入 @prettier
insertPragma: false,
// 使用默认的折行标准
proseWrap: 'preserve',
// 根据显示样式决定 html 要不要折行
htmlWhitespaceSensitivity: 'css',
// vue 文件中的 script 和 style 内不用缩进
vueIndentScriptAndStyle: false,
// 换行符使用 lf
endOfLine: 'lf',
// 格式化嵌入的内容
embeddedLanguageFormatting: 'auto',
// html, vue, jsx 中每个属性占一行
singleAttributePerLine: false,
};
================================================
FILE: .vscode/settings.json
================================================
{
"files.eol": "\n",
"editor.tabSize": 2,
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact"],
"editor.codeActionsOnSave": {
// 保存时自动修复 ESLint 错误
"source.fixAll.eslint": true
},
"typescript.tsdk": "node_modules/typescript/lib",
"[json]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[jsonc]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
}
}
================================================
FILE: README.md
================================================
---
next: introduction/README.md
---
# TypeScript 入门教程
[](https://github.com/xcatliu/typescript-tutorial/actions)
从 JavaScript 程序员的角度总结思考，循序渐进的理解 TypeScript。
## 关于本书
- [在线阅读](https://ts.xcatliu.com/)
- [GitHub 地址][GitHub]
- 作者：[xcatliu](https://github.com/xcatliu/)
- 本网站使用 [Pagic](https://github.com/xcatliu/pagic) 构建
本书是作者在学习 [TypeScript] 后整理的学习笔记。
随着对 TypeScript 理解的加深和 TypeScript 社区的发展，本书也会做出相应的更新，欢迎大家 [Star 收藏][GitHub]。
- 发现文章内容有问题，可以直接在页面下方评论
- 对项目的建议，可以[提交 issue](https://github.com/xcatliu/typescript-tutorial/issues/new) 向作者反馈
- 欢迎直接提交 pull-request 参与贡献
## 为什么要写本书
TypeScript 虽然有[官方手册][Handbook]及其[非官方中文版][中文手册]，但是它每一章都希望能详尽的描述一个概念，导致前面的章节就会包含很多后面才会学习到的内容，而有些本该一开始就了解的基础知识却在后面才会涉及。如果是初学者，可能需要阅读多次才能理解。所以它更适合用来查阅，而不是学习。
与官方手册不同，本书着重于从 JavaScript 程序员的角度总结思考，循序渐进的理解 TypeScript，希望能给大家一些帮助和启示。
由于一些知识点与官方手册重合度很高，本书会在相应章节推荐直接阅读中文手册。
## 关于 TypeScript
[TypeScript] 是 JavaScript 的一个超集，主要提供了**类型系统**和**对 ES6 的支持**，它由 Microsoft 开发，代码[开源于 GitHub](https://github.com/Microsoft/TypeScript) 上。
它的第一个版本发布于 2012 年 10 月，经历了多次更新后，现在已成为前端社区中不可忽视的力量，不仅在 Microsoft 内部得到广泛运用，而且 Google 开发的 [Angular](https://angular.io/) 从 2.0 开始就使用了 TypeScript 作为开发语言，[Vue](https://vuejs.org/) 3.0 也使用 TypeScript 进行了重构。
## 适合人群
本书适合以下人群
- 熟悉 JavaScript，至少阅读过一遍[《JavaScript 高级程序设计》](https://book.douban.com/subject/10546125/)
- 了解 ES6，推荐阅读 [ECMAScript 6 入门]
- 了解 Node.js，会用 npm 安装及使用一些工具
- 想了解 TypeScript 或者想对 TypeScript 有更深的理解
本书**不适合**以下人群
- 没有系统学习过 JavaScript
- 已经能够很熟练的运用 TypeScript
## 评价
> 《TypeScript 入门教程》全面介绍了 TypeScript 强大的类型系统，完整而简洁，示例丰富，比官方文档更易读，非常适合作为初学者学习 TypeScript 的第一本书。
>
> —— [阮一峰](https://github.com/ruanyf)
## 版权许可
本书采用「保持署名—非商用」创意共享 4.0 许可证。
只要保持原作者署名和非商用，您可以自由地阅读、分享、修改本书。
详细的法律条文请参见[创意共享](http://creativecommons.org/licenses/by-nc/4.0/)网站。
## 相关资料
- [TypeScript 官网][TypeScript]
- [Handbook]（[中文版][中文手册]）
- [ECMAScript 6 入门]
[GitHub]: https://github.com/xcatliu/typescript-tutorial
[TypeScript]: http://www.typescriptlang.org/
[Handbook]: http://www.typescriptlang.org/docs/handbook/basic-types.html
[中文手册]: https://zhongsp.gitbook.io/typescript-handbook/
[ECMAScript 6 入门]: http://es6.ruanyifeng.com/
================================================
FILE: advanced/README.md
================================================
# 进阶
本部分介绍一些高级的类型与技术，具体内容包括：
- [类型别名](type-aliases.md)
- [字符串字面量类型](string-literal-types.md)
- [元组](tuple.md)
- [枚举](enum.md)
- [类](class.md)
- [类与接口](class-and-interfaces.md)
- [泛型](generics.md)
- [声明合并](declaration-merging.md)
- [扩展阅读](further-reading.md)
================================================
FILE: advanced/class-and-interfaces.md
================================================
# 类与接口
[之前学习过](../basics/type-of-object-interfaces.md)，接口（Interfaces）可以用于对「对象的形状（Shape）」进行描述。
这一章主要介绍接口的另一个用途，对类的一部分行为进行抽象。
## 类实现接口
实现（implements）是面向对象中的一个重要概念。一般来讲，一个类只能继承自另一个类，有时候不同类之间可以有一些共有的特性，这时候就可以把特性提取成接口（interfaces），用 `implements` 关键字来实现。这个特性大大提高了面向对象的灵活性。
举例来说，门是一个类，防盗门是门的子类。如果防盗门有一个报警器的功能，我们可以简单的给防盗门添加一个报警方法。这时候如果有另一个类，车，也有报警器的功能，就可以考虑把报警器提取出来，作为一个接口，防盗门和车都去实现它：
```ts
interface Alarm {
alert(): void;
}
class Door {
}
class SecurityDoor extends Door implements Alarm {
alert() {
console.log('SecurityDoor alert');
}
}
class Car implements Alarm {
alert() {
console.log('Car alert');
}
}
```
一个类可以实现多个接口：
```ts
interface Alarm {
alert(): void;
}
interface Light {
lightOn(): void;
lightOff(): void;
}
class Car implements Alarm, Light {
alert() {
console.log('Car alert');
}
lightOn() {
console.log('Car light on');
}
lightOff() {
console.log('Car light off');
}
}
```
上例中，`Car` 实现了 `Alarm` 和 `Light` 接口，既能报警，也能开关车灯。
## 接口继承接口
接口与接口之间可以是继承关系：
```ts
interface Alarm {
alert(): void;
}
interface LightableAlarm extends Alarm {
lightOn(): void;
lightOff(): void;
}
```
这很好理解，`LightableAlarm` 继承了 `Alarm`，除了拥有 `alert` 方法之外，还拥有两个新方法 `lightOn` 和 `lightOff`。
## 接口继承类
常见的面向对象语言中，接口是不能继承类的，但是在 TypeScript 中却是可以的：
```ts
class Point {
x: number;
y: number;
constructor(x: number, y: number) {
this.x = x;
this.y = y;
}
}
interface Point3d extends Point {
z: number;
}
let point3d: Point3d = {x: 1, y: 2, z: 3};
```
为什么 TypeScript 会支持接口继承类呢？
实际上，当我们在声明 `class Point` 时，除了会创建一个名为 `Point` 的类之外，同时也创建了一个名为 `Point` 的类型（实例的类型）。
所以我们既可以将 `Point` 当做一个类来用（使用 `new Point` 创建它的实例）：
```ts
class Point {
x: number;
y: number;
constructor(x: number, y: number) {
this.x = x;
this.y = y;
}
}
const p = new Point(1, 2);
```
也可以将 `Point` 当做一个类型来用（使用 `: Point` 表示参数的类型）：
```ts
class Point {
x: number;
y: number;
constructor(x: number, y: number) {
this.x = x;
this.y = y;
}
}
function printPoint(p: Point) {
console.log(p.x, p.y);
}
printPoint(new Point(1, 2));
```
这个例子实际上可以等价于：
```ts
class Point {
x: number;
y: number;
constructor(x: number, y: number) {
this.x = x;
this.y = y;
}
}
interface PointInstanceType {
x: number;
y: number;
}
function printPoint(p: PointInstanceType) {
console.log(p.x, p.y);
}
printPoint(new Point(1, 2));
```
上例中我们新声明的 `PointInstanceType` 类型，与声明 `class Point` 时创建的 `Point` 类型是等价的。
所以回到 `Point3d` 的例子中，我们就能很容易的理解为什么 TypeScript 会支持接口继承类了：
```ts
class Point {
x: number;
y: number;
constructor(x: number, y: number) {
this.x = x;
this.y = y;
}
}
interface PointInstanceType {
x: number;
y: number;
}
// 等价于 interface Point3d extends PointInstanceType
interface Point3d extends Point {
z: number;
}
let point3d: Point3d = {x: 1, y: 2, z: 3};
```
当我们声明 `interface Point3d extends Point` 时，`Point3d` 继承的实际上是类 `Point` 的实例的类型。
换句话说，可以理解为定义了一个接口 `Point3d` 继承另一个接口 `PointInstanceType`。
所以「接口继承类」和「接口继承接口」没有什么本质的区别。
值得注意的是，`PointInstanceType` 相比于 `Point`，缺少了 `constructor` 方法，这是因为声明 `Point` 类时创建的 `Point` 类型是不包含构造函数的。另外，除了构造函数是不包含的，静态属性或静态方法也是不包含的（实例的类型当然不应该包括构造函数、静态属性或静态方法）。
换句话说，声明 `Point` 类时创建的 `Point` 类型只包含其中的实例属性和实例方法：
```ts
class Point {
/** 静态属性，坐标系原点 */
static origin = new Point(0, 0);
/** 静态方法，计算与原点距离 */
static distanceToOrigin(p: Point) {
return Math.sqrt(p.x * p.x + p.y * p.y);
}
/** 实例属性，x 轴的值 */
x: number;
/** 实例属性，y 轴的值 */
y: number;
/** 构造函数 */
constructor(x: number, y: number) {
this.x = x;
this.y = y;
}
/** 实例方法，打印此点 */
printPoint() {
console.log(this.x, this.y);
}
}
interface PointInstanceType {
x: number;
y: number;
printPoint(): void;
}
let p1: Point;
let p2: PointInstanceType;
```
上例中最后的类型 `Point` 和类型 `PointInstanceType` 是等价的。
同样的，在接口继承类的时候，也只会继承它的实例属性和实例方法。
## 参考
- [Interfaces](http://www.typescriptlang.org/docs/handbook/interfaces.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Interfaces.html)）
================================================
FILE: advanced/class.md
================================================
# 类
传统方法中，JavaScript 通过构造函数实现类的概念，通过原型链实现继承。而在 ES6 中，我们终于迎来了 `class`。
TypeScript 除了实现了所有 ES6 中的类的功能以外，还添加了一些新的用法。
这一节主要介绍类的用法，下一节再介绍如何定义类的类型。
## 类的概念
虽然 JavaScript 中有类的概念，但是可能大多数 JavaScript 程序员并不是非常熟悉类，这里对类相关的概念做一个简单的介绍。
- 类（Class）：定义了一件事物的抽象特点，包含它的属性和方法
- 对象（Object）：类的实例，通过 `new` 生成
- 面向对象（OOP）的三大特性：封装、继承、多态
- 封装（Encapsulation）：将对数据的操作细节隐藏起来，只暴露对外的接口。外界调用端不需要（也不可能）知道细节，就能通过对外提供的接口来访问该对象，同时也保证了外界无法任意更改对象内部的数据
- 继承（Inheritance）：子类继承父类，子类除了拥有父类的所有特性外，还有一些更具体的特性
- 多态（Polymorphism）：由继承而产生了相关的不同的类，对同一个方法可以有不同的响应。比如 `Cat` 和 `Dog` 都继承自 `Animal`，但是分别实现了自己的 `eat` 方法。此时针对某一个实例，我们无需了解它是 `Cat` 还是 `Dog`，就可以直接调用 `eat` 方法，程序会自动判断出来应该如何执行 `eat`
- 存取器（getter & setter）：用以改变属性的读取和赋值行为
- 修饰符（Modifiers）：修饰符是一些关键字，用于限定成员或类型的性质。比如 `public` 表示公有属性或方法
- 抽象类（Abstract Class）：抽象类是供其他类继承的基类，抽象类不允许被实例化。抽象类中的抽象方法必须在子类中被实现
- 接口（Interfaces）：不同类之间公有的属性或方法，可以抽象成一个接口。接口可以被类实现（implements）。一个类只能继承自另一个类，但是可以实现多个接口
## ES6 中类的用法
下面我们先回顾一下 ES6 中类的用法，更详细的介绍可以参考 [ECMAScript 6 入门 - Class]。
### 属性和方法
使用 `class` 定义类，使用 `constructor` 定义构造函数。
通过 `new` 生成新实例的时候，会自动调用构造函数。
```js
class Animal {
name;
constructor(name) {
this.name = name;
}
sayHi() {
return `My name is ${this.name}`;
}
}
let a = new Animal('Jack');
console.log(a.sayHi()); // My name is Jack
```
### 类的继承
使用 `extends` 关键字实现继承，子类中使用 `super` 关键字来调用父类的构造函数和方法。
```js
class Cat extends Animal {
constructor(name) {
super(name); // 调用父类的 constructor(name)
console.log(this.name);
}
sayHi() {
return 'Meow, ' + super.sayHi(); // 调用父类的 sayHi()
}
}
let c = new Cat('Tom'); // Tom
console.log(c.sayHi()); // Meow, My name is Tom
```
### 存取器
使用 getter 和 setter 可以改变属性的赋值和读取行为：
```js
class Animal {
constructor(name) {
this.name = name;
}
get name() {
return 'Jack';
}
set name(value) {
console.log('setter: ' + value);
}
}
let a = new Animal('Kitty'); // setter: Kitty
a.name = 'Tom'; // setter: Tom
console.log(a.name); // Jack
```
### 静态方法
使用 `static` 修饰符修饰的方法称为静态方法，它们不需要实例化，而是直接通过类来调用：
```js
class Animal {
static isAnimal(a) {
return a instanceof Animal;
}
}
let a = new Animal('Jack');
Animal.isAnimal(a); // true
a.isAnimal(a); // TypeError: a.isAnimal is not a function
```
## ES7 中类的用法
ES7 中有一些关于类的提案，TypeScript 也实现了它们，这里做一个简单的介绍。
### 实例属性
ES6 中实例的属性只能通过构造函数中的 `this.xxx` 来定义，ES7 提案中可以直接在类里面定义：
```js
class Animal {
name = 'Jack';
constructor() {
// ...
}
}
let a = new Animal();
console.log(a.name); // Jack
```
### 静态属性
ES7 提案中，可以使用 `static` 定义一个静态属性：
```js
class Animal {
static num = 42;
constructor() {
// ...
}
}
console.log(Animal.num); // 42
```
## TypeScript 中类的用法
### public private 和 protected
TypeScript 可以使用三种访问修饰符（Access Modifiers），分别是 `public`、`private` 和 `protected`。
- `public` 修饰的属性或方法是公有的，可以在任何地方被访问到，默认所有的属性和方法都是 `public` 的
- `private` 修饰的属性或方法是私有的，不能在声明它的类的外部访问
- `protected` 修饰的属性或方法是受保护的，它和 `private` 类似，区别是它在子类中也是允许被访问的
下面举一些例子：
```ts
class Animal {
public name;
public constructor(name) {
this.name = name;
}
}
let a = new Animal('Jack');
console.log(a.name); // Jack
a.name = 'Tom';
console.log(a.name); // Tom
```
上面的例子中，`name` 被设置为了 `public`，所以直接访问实例的 `name` 属性是允许的。
很多时候，我们希望有的属性是无法直接存取的，这时候就可以用 `private` 了：
```ts
class Animal {
private name;
public constructor(name) {
this.name = name;
}
}
let a = new Animal('Jack');
console.log(a.name);
a.name = 'Tom';
// index.ts(9,13): error TS2341: Property 'name' is private and only accessible within class 'Animal'.
// index.ts(10,1): error TS2341: Property 'name' is private and only accessible within class 'Animal'.
```
需要注意的是，TypeScript 编译之后的代码中，并没有限制 `private` 属性在外部的可访问性。
上面的例子编译后的代码是：
```js
var Animal = (function () {
function Animal(name) {
this.name = name;
}
return Animal;
})();
var a = new Animal('Jack');
console.log(a.name);
a.name = 'Tom';
```
使用 `private` 修饰的属性或方法，在子类中也是不允许访问的：
```ts
class Animal {
private name;
public constructor(name) {
this.name = name;
}
}
class Cat extends Animal {
constructor(name) {
super(name);
console.log(this.name);
}
}
// index.ts(11,17): error TS2341: Property 'name' is private and only accessible within class 'Animal'.
```
而如果是用 `protected` 修饰，则允许在子类中访问：
```ts
class Animal {
protected name;
public constructor(name) {
this.name = name;
}
}
class Cat extends Animal {
constructor(name) {
super(name);
console.log(this.name);
}
}
```
当构造函数修饰为 `private` 时，该类不允许被继承或者实例化：
```ts
class Animal {
public name;
private constructor(name) {
this.name = name;
}
}
class Cat extends Animal {
constructor(name) {
super(name);
}
}
let a = new Animal('Jack');
// index.ts(7,19): TS2675: Cannot extend a class 'Animal'. Class constructor is marked as private.
// index.ts(13,9): TS2673: Constructor of class 'Animal' is private and only accessible within the class declaration.
```
当构造函数修饰为 `protected` 时，该类只允许被继承：
```ts
class Animal {
public name;
protected constructor(name) {
this.name = name;
}
}
class Cat extends Animal {
constructor(name) {
super(name);
}
}
let a = new Animal('Jack');
// index.ts(13,9): TS2674: Constructor of class 'Animal' is protected and only accessible within the class declaration.
```
### 参数属性
修饰符和`readonly`还可以使用在构造函数参数中，等同于类中定义该属性同时给该属性赋值，使代码更简洁。
```ts
class Animal {
// public name: string;
public constructor(public name) {
// this.name = name;
}
}
```
### readonly
只读属性关键字，只允许出现在属性声明或索引签名或构造函数中。
```ts
class Animal {
readonly name;
public constructor(name) {
this.name = name;
}
}
let a = new Animal('Jack');
console.log(a.name); // Jack
a.name = 'Tom';
// index.ts(10,3): TS2540: Cannot assign to 'name' because it is a read-only property.
```
注意如果 `readonly` 和其他访问修饰符同时存在的话，需要写在其后面。
```ts
class Animal {
// public readonly name;
public constructor(public readonly name) {
// this.name = name;
}
}
```
### 抽象类
`abstract` 用于定义抽象类和其中的抽象方法。
什么是抽象类？
首先，抽象类是不允许被实例化的：
```ts
abstract class Animal {
public name;
public constructor(name) {
this.name = name;
}
public abstract sayHi();
}
let a = new Animal('Jack');
// index.ts(9,11): error TS2511: Cannot create an instance of the abstract class 'Animal'.
```
上面的例子中，我们定义了一个抽象类 `Animal`，并且定义了一个抽象方法 `sayHi`。在实例化抽象类的时候报错了。
其次，抽象类中的抽象方法必须被子类实现：
```ts
abstract class Animal {
public name;
public constructor(name) {
this.name = name;
}
public abstract sayHi();
}
class Cat extends Animal {
public eat() {
console.log(`${this.name} is eating.`);
}
}
let cat = new Cat('Tom');
// index.ts(9,7): error TS2515: Non-abstract class 'Cat' does not implement inherited abstract member 'sayHi' from class 'Animal'.
```
上面的例子中，我们定义了一个类 `Cat` 继承了抽象类 `Animal`，但是没有实现抽象方法 `sayHi`，所以编译报错了。
下面是一个正确使用抽象类的例子：
```ts
abstract class Animal {
public name;
public constructor(name) {
this.name = name;
}
public abstract sayHi();
}
class Cat extends Animal {
public sayHi() {
console.log(`Meow, My name is ${this.name}`);
}
}
let cat = new Cat('Tom');
```
上面的例子中，我们实现了抽象方法 `sayHi`，编译通过了。
需要注意的是，即使是抽象方法，TypeScript 的编译结果中，仍然会存在这个类，上面的代码的编译结果是：
```js
var __extends =
(this && this.__extends) ||
function (d, b) {
for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p];
function __() {
this.constructor = d;
}
d.prototype = b === null ? Object.create(b) : ((__.prototype = b.prototype), new __());
};
var Animal = (function () {
function Animal(name) {
this.name = name;
}
return Animal;
})();
var Cat = (function (_super) {
__extends(Cat, _super);
function Cat() {
_super.apply(this, arguments);
}
Cat.prototype.sayHi = function () {
console.log('Meow, My name is ' + this.name);
};
return Cat;
})(Animal);
var cat = new Cat('Tom');
```
## 类的类型
给类加上 TypeScript 的类型很简单，与接口类似：
```ts
class Animal {
name: string;
constructor(name: string) {
this.name = name;
}
sayHi(): string {
return `My name is ${this.name}`;
}
}
let a: Animal = new Animal('Jack');
console.log(a.sayHi()); // My name is Jack
```
## 参考
- [Classes](http://www.typescriptlang.org/docs/handbook/classes.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Classes.html)）
- [ECMAScript 6 入门 - Class]
[ecmascript 6 入门 - class]: http://es6.ruanyifeng.com/#docs/class
================================================
FILE: advanced/declaration-merging.md
================================================
# 声明合并
如果定义了两个相同名字的函数、接口或类，那么它们会合并成一个类型：
## 函数的合并
[之前学习过](../basics/type-of-function.md#重载)，我们可以使用重载定义多个函数类型：
```ts
function reverse(x: number): number;
function reverse(x: string): string;
function reverse(x: number | string): number | string {
if (typeof x === 'number') {
return Number(x.toString().split('').reverse().join(''));
} else if (typeof x === 'string') {
return x.split('').reverse().join('');
}
}
```
## 接口的合并
接口中的属性在合并时会简单的合并到一个接口中：
```ts
interface Alarm {
price: number;
}
interface Alarm {
weight: number;
}
```
相当于：
```ts
interface Alarm {
price: number;
weight: number;
}
```
注意，**合并的属性的类型必须是唯一的**：
```ts
interface Alarm {
price: number;
}
interface Alarm {
price: number; // 虽然重复了，但是类型都是 `number`，所以不会报错
weight: number;
}
```
```ts
interface Alarm {
price: number;
}
interface Alarm {
price: string; // 类型不一致，会报错
weight: number;
}
// index.ts(5,3): error TS2403: Subsequent variable declarations must have the same type. Variable 'price' must be of type 'number', but here has type 'string'.
```
接口中方法的合并，与函数的合并一样：
```ts
interface Alarm {
price: number;
alert(s: string): string;
}
interface Alarm {
weight: number;
alert(s: string, n: number): string;
}
```
相当于：
```ts
interface Alarm {
price: number;
weight: number;
alert(s: string): string;
alert(s: string, n: number): string;
}
```
## 类的合并
类的合并与接口的合并规则一致。
## 参考
- [Declaration Merging](http://www.typescriptlang.org/docs/handbook/declaration-merging.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Declaration%20Merging.html)）
================================================
FILE: advanced/decorator.md
================================================
# 装饰器
写在前面：本章只介绍 TypeScript 5.0+ 的装饰器用法，对于 5.0 以下的版本，请参考 [TypeScript 官方文档](https://www.typescriptlang.org/docs/handbook/decorators.html)
## 什么是装饰器
首先，什么是装饰器呢？[维基百科](https://en.wikipedia.org/wiki/Decorator_pattern)是这么说的：
> In [object-oriented programming](https://en.wikipedia.org/wiki/Object-oriented_programming), the **decorator pattern** is a [design pattern](https://en.wikipedia.org/wiki/Design_pattern_(computer_science)) that allows behavior to be added to an individual [object](https://en.wikipedia.org/wiki/Object_(computer_science)), dynamically, without affecting the behavior of other instances of the same [class](https://en.wikipedia.org/wiki/Class_(computer_science)).
本人的蹩足翻译：在 OOP (面向对象编程)中，装饰器模式是一种允许动态地往一个对象上添加自定义行为，而又不影响该对象所属的类的其他实例的一种设计模式。
> 什么是 OOP 和类？[前面的章节](https://ts.xcatliu.com/advanced/class.html)做过介绍。
这句话未免过于拗口了，我们不妨换个角度去切入。
## 装饰器的使用场景
要知道，一切设计模式的诞生，都是为了解决某个问题。在 JavaScript 的世界中，装饰器通常出现于以下场景：
1. 提供一种易读且容易实现的方式，修改类或者类的方法，避免出现大量重复的代码。
下面以修改类的方法为例。
首先，假设我们有一个 `Animal` 类：
```ts
class Animal {
type: string
constructor(type: string) {
this.type = type
}
greet() {
console.log(`Hello, I'm a(n) ${this.type}!`)
}
}
const xcat = new Animal('cat')
xcat.greet() // Hello, I'm a(n) cat!
```
该类有一个 greet 方法，和调用方打招呼。
假如说，我还希望根据不同的 `type`，往 console 打印不同动物的叫声呢？
聪明的你或许想到了，这不就是**类的继承**吗！在子类的 `greet()` 方法中，实现不同的逻辑，再调用 `super.greet()` 即可。
```ts
class Xcat extends Animal {
constructor() {
super('cat')
}
greet() {
console.log('meow~ meow~')
super.greet()
}
}
const xcat = new Xcat()
xcat.greet() // meow~ meow~
// Hello, I'm a(n) cat!
```
用装饰器实现，也不妨为一种思路，比如在 `Animal` 类中，为 `greet()` 方法添加「打印不同动物叫声的」行为:
```ts
class Animal {
type: string
constructor(type: string) {
this.type = type
}
@yelling
greet() {
console.log(`Hello, I'm a(n) ${this.type}!`)
}
}
const typeToYellingMap = {
cat: 'meow~ meow~'
}
function yelling(originalMethod: any, context: ClassMethodDecoratorContext) {
return function(...args: any[]) {
console.log(typeToYellingMap[this.type])
originalMethod.call(this, ...args)
}
}
const xcat = new Animal('cat')
xcat.greet() // meow~ meow~
// Hello, I'm a(n) cat!
```
在 `Animal.greet()` 方法上出现的 `@yelling` ，就是 TypeScript 中装饰器的写法，即 @ + 函数名的组合。
上述示例对装饰器的应用属于**方法装饰器**，此类装饰器本身接收两个参数，一是被装饰的方法，二是方法装饰器的上下文。方法装饰器应返回一个函数，此函数在运行时真正被执行。在上述例子中，我们在装饰器返回的函数中做了两件事情：
1. 打印相应类别的动物的叫声。
2. 调用 `originalMethod.call(this, …args)` ，确保原方法（即装饰器所装饰的方法）能够正确地被执行。
2. 结合「**依赖注入**」这一设计模式，优化模块与 class 的依赖关系。
什么是依赖注入呢？引用同事 [zio](https://github.com/ziofat) 的原话：
> **依赖注入其实是将一个模块所依赖的部分作为参数传入，而不是由模块自己去构造。**
可见，依赖注入解决了实际工程项目中，类、模块间依赖关系层级复杂的问题，将构造单例的行为交由实现依赖注入的框架去处理。
举个例子：
```ts
@injectable
class Dog implements IAnimal {
sayHi() {
console.log('woof woof woof')
}
}
@injectable
class Cat implements IAnimal {
sayHi() {
console.log('meow meow meow')
}
}
class AnimalService {
constructor(
@inject dog: Dog
@inject cat: Cat
) {
this._dog = dog
this._cat = cat
}
sayHiByDog() {
this._dog.sayHi()
}
sayHiByCat() {
this._cat.sayHi()
}
}
```
在上述代码中，`@injectable` 将一个类标记为「可被注入的」，在面向业务的类（即 `AnimalService`）中，使用 `@inject` 注入此类的单例，实现了「依赖倒置」。注意到这里的 `implements IAnimal` 用法，也是实战中依赖注入运用的精妙之处 —— 关心接口，而非具体实现。
3. 实现「AOP」，即 Aspect-oriented programming，面向切面编程。
所谓的「切面」，可以理解成，在复杂的各个业务维度中，只关注一个维度的事务。
例如，使用装饰器，实现对类的某个方法的执行时间记录：
```ts
class MyService {
@recordExecution
myFn() {
// do something...
}
}
function recordExecution(originalMethod: any, context: ClassMethodDecoratorContext) {
return function(...args: any[]) {
console.time('mark execution')
originalMethod.call(this, ...args)
console.timeEnd('mark execution')
}
}
```
## 装饰器的类别
通过以上例子，相信读者已经对装饰器有一定了解，且认识到了装饰器在一些场景的强大之处。在此引用[阮一峰 es6 教程](https://es6.ruanyifeng.com/#docs/decorator#%E7%AE%80%E4%BB%8B%EF%BC%88%E6%96%B0%E8%AF%AD%E6%B3%95%EF%BC%89)稍做总结：
> 装饰器是一种函数，写成`@ + 函数名`，可以用来装饰四种类型的值。
>
> - 类
> - 类的属性
> - 类的方法
> - 属性存取器（accessor, getter, setter）
> 装饰器的执行步骤如下。
>
> 1. 计算各个装饰器的值，按照从左到右，从上到下的顺序。
> 2. 调用方法装饰器。
> 3. 调用类装饰器。
不管是哪种类型的装饰器，它们的函数签名都可以认为是一致的，即均接收 `value`, `context` 两个参数，前者指被装饰的对象，后者指一个存储了上下文信息的对象。
## context 与 metadata 二三讲
四种装饰器的 context，均包含以下信息：
- kind
描述被装饰的 value 的类型，可取 `class`, `method`, `field`, `getter`, `setter`, `accessor` 这些值。
- name
描述被装饰的 value 的名字。
- addInitializer
一个方法，接收一个回调函数，使得开发者可以侵入 value 的初始化过程作修改。
对 `class` 来说，这个回调函数会在类定义最终确认后调用，即相当于在初始化过程的最后一步。
对其他的 value 来说，如果是被 `static` 所修饰的，则会在类定义期间被调用，且早于其他静态属性的赋值过程；否则，会在类初始化期间被调用，且早于 value 自身的初始化。
以下是 `@bound` 类方法装饰器的例子，该装饰器自动为方法绑定 `this`：
```ts
const bound = (value, context: ClassMemberDecoratorContext) {
if (context.private) throw new TypeError("Not supported on private methods.");
context.addInitializer(function () {
this[context.name] = this[context.name].bind(this);
});
}
```
- metadata
和装饰器类似，[metadata](https://github.com/tc39/proposal-decorator-metadata) 也是处于 stage 3 阶段的一个提案。装饰器只能访问到类原型链、类实例的相关数据，而 metadata 给了开发者更大的自由，让程序于运行时访问到编译时决定的元数据。
举个例子：
```ts
function meta(key, value) {
return (_, context) => {
context.metadata[key] = value;
};
}
@meta('a', 'x')
class C {
@meta('b', 'y')
m() {}
}
C[Symbol.metadata].a; // 'x'
C[Symbol.metadata].b; // 'y'
```
在上述程序中，我们通过访问类的 `Symbol.metadata` ，读取到了 meta 装饰器所写入的元数据。对元数据的访问，有且仅有这一种形式。
注意一点，metadata 是作用在类上的，即使它的位置在类方法上。想实现细粒度的元数据存储，可以考虑手动维护若干 `WeakMap`。
除了类装饰器以外，其他3种装饰器的 context 还拥有以下 3 个字段：
- static
布尔值，描述 value 是否为 static 所修饰。
- private
布尔值，描述 value 是否为 private 所修饰。
- access
一个对象，可在运行时访问 value 相关数据。
以类方法装饰器为例，用 `access.get` 可在运行时读取方法值，`access.has` 可在运行时查询对象上是否有某方法，举个例子：
```ts
const typeToYellingMap = {
cat: 'meow~ meow~',
}
let yellingMethodContext: ClassMethodDecoratorContext
class Animal {
type: string
constructor(type: string) {
this.type = type
}
@yelling
greet() {
console.log(`Hello, I'm a(n) ${this.type}!`)
}
accessor y = 1
}
function yelling(originalMethod: any, context: ClassMethodDecoratorContext) {
yellingMethodContext = context
return function (this: any, ...args: any[]) {
console.log(typeToYellingMap[this.type as keyof typeof typeToYellingMap])
originalMethod.call(this, ...args)
}
}
const xcat = new Animal('cat')
xcat.greet() // meow~ meow~
// Hello, I'm a(n) cat!
yellingMethodContext.access.get(xcat).call(xcat) // meow~ meow~
// Hello, I'm a(n) cat!
console.log(yellingMethodContext.access.has(xcat)) // true
```
`getter` 类别的装饰器，其 `context.access` 同样拥有 `has`, `get` 两个方法。
对于 `setter` 类别的装饰器，则是 `has` 与 `set` 方法。
`filed` 与 `accessor` 类别的装饰器，拥有 `has`, `get`, `set` 全部三个方法。
================================================
FILE: advanced/enum.md
================================================
# 枚举
枚举（Enum）类型用于取值被限定在一定范围内的场景，比如一周只能有七天，颜色限定为红绿蓝等。
## 简单的例子
枚举使用 `enum` 关键字来定义：
```ts
enum Days {Sun, Mon, Tue, Wed, Thu, Fri, Sat};
```
枚举成员会被赋值为从 `0` 开始递增的数字，同时也会对枚举值到枚举名进行反向映射：
```ts
enum Days {Sun, Mon, Tue, Wed, Thu, Fri, Sat};
console.log(Days["Sun"] === 0); // true
console.log(Days["Mon"] === 1); // true
console.log(Days["Tue"] === 2); // true
console.log(Days["Sat"] === 6); // true
console.log(Days[0] === "Sun"); // true
console.log(Days[1] === "Mon"); // true
console.log(Days[2] === "Tue"); // true
console.log(Days[6] === "Sat"); // true
```
事实上，上面的例子会被编译为：
```js
var Days;
(function (Days) {
Days[Days["Sun"] = 0] = "Sun";
Days[Days["Mon"] = 1] = "Mon";
Days[Days["Tue"] = 2] = "Tue";
Days[Days["Wed"] = 3] = "Wed";
Days[Days["Thu"] = 4] = "Thu";
Days[Days["Fri"] = 5] = "Fri";
Days[Days["Sat"] = 6] = "Sat";
})(Days || (Days = {}));
```
## 手动赋值
我们也可以给枚举项手动赋值：
```ts
enum Days {Sun = 7, Mon = 1, Tue, Wed, Thu, Fri, Sat};
console.log(Days["Sun"] === 7); // true
console.log(Days["Mon"] === 1); // true
console.log(Days["Tue"] === 2); // true
console.log(Days["Sat"] === 6); // true
```
上面的例子中，未手动赋值的枚举项会接着上一个枚举项递增。
如果未手动赋值的枚举项与手动赋值的重复了，TypeScript 是不会察觉到这一点的：
```ts
enum Days {Sun = 3, Mon = 1, Tue, Wed, Thu, Fri, Sat};
console.log(Days["Sun"] === 3); // true
console.log(Days["Wed"] === 3); // true
console.log(Days[3] === "Sun"); // false
console.log(Days[3] === "Wed"); // true
```
上面的例子中，递增到 `3` 的时候与前面的 `Sun` 的取值重复了，但是 TypeScript 并没有报错，导致 `Days[3]` 的值先是 `"Sun"`，而后又被 `"Wed"` 覆盖了。编译的结果是：
```js
var Days;
(function (Days) {
Days[Days["Sun"] = 3] = "Sun";
Days[Days["Mon"] = 1] = "Mon";
Days[Days["Tue"] = 2] = "Tue";
Days[Days["Wed"] = 3] = "Wed";
Days[Days["Thu"] = 4] = "Thu";
Days[Days["Fri"] = 5] = "Fri";
Days[Days["Sat"] = 6] = "Sat";
})(Days || (Days = {}));
```
所以使用的时候需要注意，最好不要出现这种覆盖的情况。
手动赋值的枚举项可以不是数字，此时需要使用类型断言来让 tsc 无视类型检查 (编译出的 js 仍然是可用的)：
```ts
enum Days {Sun = 7, Mon, Tue, Wed, Thu, Fri, Sat = <any>"S"};
```
```js
var Days;
(function (Days) {
Days[Days["Sun"] = 7] = "Sun";
Days[Days["Mon"] = 8] = "Mon";
Days[Days["Tue"] = 9] = "Tue";
Days[Days["Wed"] = 10] = "Wed";
Days[Days["Thu"] = 11] = "Thu";
Days[Days["Fri"] = 12] = "Fri";
Days[Days["Sat"] = "S"] = "Sat";
})(Days || (Days = {}));
```
当然，手动赋值的枚举项也可以为小数或负数，此时后续未手动赋值的项的递增步长仍为 `1`：
```ts
enum Days {Sun = 7, Mon = 1.5, Tue, Wed, Thu, Fri, Sat};
console.log(Days["Sun"] === 7); // true
console.log(Days["Mon"] === 1.5); // true
console.log(Days["Tue"] === 2.5); // true
console.log(Days["Sat"] === 6.5); // true
```
## 常数项和计算所得项
枚举项有两种类型：常数项（constant member）和计算所得项（computed member）。
前面我们所举的例子都是常数项，一个典型的计算所得项的例子：
```ts
enum Color {Red, Green, Blue = "blue".length};
```
上面的例子中，`"blue".length` 就是一个计算所得项。
上面的例子不会报错，但是**如果紧接在计算所得项后面的是未手动赋值的项，那么它就会因为无法获得初始值而报错**：
```ts
enum Color {Red = "red".length, Green, Blue};
// index.ts(1,33): error TS1061: Enum member must have initializer.
// index.ts(1,40): error TS1061: Enum member must have initializer.
```
下面是常数项和计算所得项的完整定义，部分引用自[中文手册 - 枚举]：
当满足以下条件时，枚举成员被当作是常数：
- 不具有初始化函数并且之前的枚举成员是常数。在这种情况下，当前枚举成员的值为上一个枚举成员的值加 `1`。但第一个枚举元素是个例外。如果它没有初始化方法，那么它的初始值为 `0`。
- 枚举成员使用常数枚举表达式初始化。常数枚举表达式是 TypeScript 表达式的子集，它可以在编译阶段求值。当一个表达式满足下面条件之一时，它就是一个常数枚举表达式：
- 数字字面量
- 引用之前定义的常数枚举成员（可以是在不同的枚举类型中定义的）如果这个成员是在同一个枚举类型中定义的，可以使用非限定名来引用
- 带括号的常数枚举表达式
- `+`, `-`, `~` 一元运算符应用于常数枚举表达式
- `+`, `-`, `*`, `/`, `%`, `<<`, `>>`, `>>>`, `&`, `|`, `^` 二元运算符，常数枚举表达式做为其一个操作对象。若常数枚举表达式求值后为 NaN 或 Infinity，则会在编译阶段报错
所有其它情况的枚举成员被当作是需要计算得出的值。
## 常数枚举
常数枚举是使用 `const enum` 定义的枚举类型：
```ts
const enum Directions {
Up,
Down,
Left,
Right
}
let directions = [Directions.Up, Directions.Down, Directions.Left, Directions.Right];
```
常数枚举与普通枚举的区别是，它会在编译阶段被删除，并且不能包含计算成员。
上例的编译结果是：
```js
var directions = [0 /* Up */, 1 /* Down */, 2 /* Left */, 3 /* Right */];
```
假如包含了计算成员，则会在编译阶段报错：
```ts
const enum Color {Red, Green, Blue = "blue".length};
// index.ts(1,38): error TS2474: In 'const' enum declarations member initializer must be constant expression.
```
## 外部枚举
外部枚举（Ambient Enums）是使用 `declare enum` 定义的枚举类型：
```ts
declare enum Directions {
Up,
Down,
Left,
Right
}
let directions = [Directions.Up, Directions.Down, Directions.Left, Directions.Right];
```
之前提到过，`declare` 定义的类型只会用于编译时的检查，编译结果中会被删除。
上例的编译结果是：
```js
var directions = [Directions.Up, Directions.Down, Directions.Left, Directions.Right];
```
外部枚举与声明语句一样，常出现在声明文件中。
同时使用 `declare` 和 `const` 也是可以的：
```ts
declare const enum Directions {
Up,
Down,
Left,
Right
}
let directions = [Directions.Up, Directions.Down, Directions.Left, Directions.Right];
```
编译结果：
```js
var directions = [0 /* Up */, 1 /* Down */, 2 /* Left */, 3 /* Right */];
```
> TypeScript 的枚举类型的概念[来源于 C#][C# Enum]。
## 参考
- [Enums](http://www.typescriptlang.org/docs/handbook/enums.html)（[中文版][中文手册 - 枚举]）
- [C# Enum][]
[中文手册 - 枚举]: https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Enums.html
[C# Enum]: https://msdn.microsoft.com/zh-cn/library/sbbt4032.aspx
================================================
FILE: advanced/further-reading.md
================================================
# 扩展阅读
此处记录了[官方手册](http://www.typescriptlang.org/docs/handbook/basic-types.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/)）中包含，但是本书未涉及的概念。
我认为它们是一些不重要或者不属于 TypeScript 的概念，所以这里只给出一个简单的释义，详细内容可以点击链接深入理解。
- [Never](http://www.typescriptlang.org/docs/handbook/basic-types.html#never)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Basic%20Types.html#never)）：永远不存在值的类型，一般用于错误处理函数
- [Variable Declarations](http://www.typescriptlang.org/docs/handbook/variable-declarations.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Variable%20Declarations.html)）：使用 `let` 和 `const` 替代 `var`，这是 [ES6 的知识](http://es6.ruanyifeng.com/#docs/let)
- [`this`](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Functions.html#this)：箭头函数的运用，这是 [ES6 的知识](http://es6.ruanyifeng.com/#docs/function)
- [Using Class Types in Generics](http://www.typescriptlang.org/docs/handbook/generics.html#using-class-types-in-generics)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Generics.html#在泛型里使用类类型)）：创建工厂函数时，需要引用构造函数的类类型
- [Best common type](http://www.typescriptlang.org/docs/handbook/type-inference.html#best-common-type)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Type%20Inference.html#最佳通用类型)）：数组的类型推论
- [Contextual Type](http://www.typescriptlang.org/docs/handbook/type-inference.html#contextual-type)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Type%20Inference.html#上下文类型)）：函数输入的类型推论
- [Type Compatibility](http://www.typescriptlang.org/docs/handbook/type-compatibility.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Type%20Compatibility.html)）：允许不严格符合类型，只需要在一定规则下兼容即可
- [Advanced Types](http://www.typescriptlang.org/docs/handbook/advanced-types.html#intersection-types)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Advanced%20Types.html#交叉类型（intersection-types）)）：使用 `&` 将多种类型的共有部分叠加成一种类型
- [Type Guards and Differentiating Types](http://www.typescriptlang.org/docs/handbook/advanced-types.html#type-guards-and-differentiating-types)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Advanced%20Types.html#类型保护与区分类型（type-guards-and-differentiating-types）)）：联合类型在一些情况下被识别为特定的类型
- [Discriminated Unions](http://www.typescriptlang.org/docs/handbook/advanced-types.html#discriminated-unions)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Advanced%20Types.html#可辨识联合（discriminated-unions）)）：使用 `|` 联合多个接口的时候，通过一个共有的属性形成可辨识联合
- [Polymorphic `this` types](http://www.typescriptlang.org/docs/handbook/advanced-types.html#polymorphic-this-types)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Advanced%20Types.html#多态的this类型)）：父类的某个方法返回 `this`，当子类继承父类后，子类的实例调用此方法，返回的 `this` 能够被 TypeScript 正确的识别为子类的实例。
- [Symbols](http://www.typescriptlang.org/docs/handbook/symbols.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Symbols.html)）：新原生类型，这是 [ES6 的知识](http://es6.ruanyifeng.com/#docs/symbol)
- [Iterators and Generators](http://www.typescriptlang.org/docs/handbook/iterators-and-generators.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Iterators%20and%20Generators.html)）：迭代器，这是 [ES6 的知识](http://es6.ruanyifeng.com/#docs/iterator)
- [Namespaces](http://www.typescriptlang.org/docs/handbook/namespaces.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Namespaces.html)）：避免全局污染，现在已被 [ES6 Module](http://es6.ruanyifeng.com/#docs/module) 替代
- [Mixins](http://www.typescriptlang.org/docs/handbook/mixins.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Mixins.html)）：一种编程模式，与 TypeScript 没有直接关系，可以参考 [ES6 中 Mixin 模式的实现](http://es6.ruanyifeng.com/#docs/class#Mixin模式的实现)
================================================
FILE: advanced/generics.md
================================================
# 泛型
泛型（Generics）是指在定义函数、接口或类的时候，不预先指定具体的类型，而在使用的时候再指定类型的一种特性。
## 简单的例子
首先，我们来实现一个函数 `createArray`，它可以创建一个指定长度的数组，同时将每一项都填充一个默认值：
```ts
function createArray(length: number, value: any): Array<any> {
let result = [];
for (let i = 0; i < length; i++) {
result[i] = value;
}
return result;
}
createArray(3, 'x'); // ['x', 'x', 'x']
```
上例中，我们使用了[之前提到过的数组泛型](../basics/type-of-array.md#数组泛型)来定义返回值的类型。
这段代码编译不会报错，但是一个显而易见的缺陷是，它并没有准确的定义返回值的类型：
`Array<any>` 允许数组的每一项都为任意类型。但是我们预期的是，数组中每一项都应该是输入的 `value` 的类型。
这时候，泛型就派上用场了：
```ts
function createArray<T>(length: number, value: T): Array<T> {
let result: T[] = [];
for (let i = 0; i < length; i++) {
result[i] = value;
}
return result;
}
createArray<string>(3, 'x'); // ['x', 'x', 'x']
```
上例中，我们在函数名后添加了 `<T>`，其中 `T` 用来指代任意输入的类型，在后面的输入 `value: T` 和输出 `Array<T>` 中即可使用了。
接着在调用的时候，可以指定它具体的类型为 `string`。当然，也可以不手动指定，而让类型推论自动推算出来：
```ts
function createArray<T>(length: number, value: T): Array<T> {
let result: T[] = [];
for (let i = 0; i < length; i++) {
result[i] = value;
}
return result;
}
createArray(3, 'x'); // ['x', 'x', 'x']
```
## 多个类型参数
定义泛型的时候，可以一次定义多个类型参数：
```ts
function swap<T, U>(tuple: [T, U]): [U, T] {
return [tuple[1], tuple[0]];
}
swap([7, 'seven']); // ['seven', 7]
```
上例中，我们定义了一个 `swap` 函数，用来交换输入的元组。
## 泛型约束
在函数内部使用泛型变量的时候，由于事先不知道它是哪种类型，所以不能随意的操作它的属性或方法：
```ts
function loggingIdentity<T>(arg: T): T {
console.log(arg.length);
return arg;
}
// index.ts(2,19): error TS2339: Property 'length' does not exist on type 'T'.
```
上例中，泛型 `T` 不一定包含属性 `length`，所以编译的时候报错了。
这时，我们可以对泛型进行约束，只允许这个函数传入那些包含 `length` 属性的变量。这就是泛型约束：
```ts
interface Lengthwise {
length: number;
}
function loggingIdentity<T extends Lengthwise>(arg: T): T {
console.log(arg.length);
return arg;
}
```
上例中，我们使用了 `extends` 约束了泛型 `T` 必须符合接口 `Lengthwise` 的形状，也就是必须包含 `length` 属性。
此时如果调用 `loggingIdentity` 的时候，传入的 `arg` 不包含 `length`，那么在编译阶段就会报错了：
```ts
interface Lengthwise {
length: number;
}
function loggingIdentity<T extends Lengthwise>(arg: T): T {
console.log(arg.length);
return arg;
}
loggingIdentity(7);
// index.ts(10,17): error TS2345: Argument of type '7' is not assignable to parameter of type 'Lengthwise'.
```
多个类型参数之间也可以互相约束：
```ts
function copyFields<T extends U, U>(target: T, source: U): T {
for (let id in source) {
target[id] = (<T>source)[id];
}
return target;
}
let x = { a: 1, b: 2, c: 3, d: 4 };
copyFields(x, { b: 10, d: 20 });
```
上例中，我们使用了两个类型参数，其中要求 `T` 继承 `U`，这样就保证了 `U` 上不会出现 `T` 中不存在的字段。
## 泛型接口
[之前学习过](../basics/type-of-function.md#接口中函数的定义)，可以使用接口的方式来定义一个函数需要符合的形状：
```ts
interface SearchFunc {
(source: string, subString: string): boolean;
}
let mySearch: SearchFunc;
mySearch = function(source: string, subString: string) {
return source.search(subString) !== -1;
}
```
当然也可以使用含有泛型的接口来定义函数的形状：
```ts
interface CreateArrayFunc {
<T>(length: number, value: T): Array<T>;
}
let createArray: CreateArrayFunc;
createArray = function<T>(length: number, value: T): Array<T> {
let result: T[] = [];
for (let i = 0; i < length; i++) {
result[i] = value;
}
return result;
}
createArray(3, 'x'); // ['x', 'x', 'x']
```
进一步，我们可以把泛型参数提前到接口名上：
```ts
interface CreateArrayFunc<T> {
(length: number, value: T): Array<T>;
}
let createArray: CreateArrayFunc<any>;
createArray = function<T>(length: number, value: T): Array<T> {
let result: T[] = [];
for (let i = 0; i < length; i++) {
result[i] = value;
}
return result;
}
createArray(3, 'x'); // ['x', 'x', 'x']
```
注意，此时在使用泛型接口的时候，需要定义泛型的类型。
## 泛型类
与泛型接口类似，泛型也可以用于类的类型定义中：
```ts
class GenericNumber<T> {
zeroValue: T;
add: (x: T, y: T) => T;
}
let myGenericNumber = new GenericNumber<number>();
myGenericNumber.zeroValue = 0;
myGenericNumber.add = function(x, y) { return x + y; };
```
## 泛型参数的默认类型
在 TypeScript 2.3 以后，我们可以为泛型中的类型参数指定默认类型。当使用泛型时没有在代码中直接指定类型参数，从实际值参数中也无法推测出时，这个默认类型就会起作用。
```ts
function createArray<T = string>(length: number, value: T): Array<T> {
let result: T[] = [];
for (let i = 0; i < length; i++) {
result[i] = value;
}
return result;
}
```
## 参考
- [Generics](http://www.typescriptlang.org/docs/handbook/generics.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/generics.html)）
- [Generic parameter defaults](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-3.html#generic-parameter-defaults)
================================================
FILE: advanced/string-literal-types.md
================================================
# 字符串字面量类型
字符串字面量类型用来约束取值只能是某几个字符串中的一个。
## 简单的例子
```ts
type EventNames = 'click' | 'scroll' | 'mousemove';
function handleEvent(ele: Element, event: EventNames) {
// do something
}
handleEvent(document.getElementById('hello'), 'scroll'); // 没问题
handleEvent(document.getElementById('world'), 'dblclick'); // 报错，event 不能为 'dblclick'
// index.ts(7,47): error TS2345: Argument of type '"dblclick"' is not assignable to parameter of type 'EventNames'.
```
上例中，我们使用 `type` 定了一个字符串字面量类型 `EventNames`，它只能取三种字符串中的一种。
注意，**类型别名与字符串字面量类型都是使用 `type` 进行定义。**
## 参考
- [Advanced Types # Type Aliases](http://www.typescriptlang.org/docs/handbook/advanced-types.html#string-literal-types)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Advanced%20Types.html#字符串字面量类型)）
================================================
FILE: advanced/tuple.md
================================================
# 元组
数组合并了相同类型的对象，而元组（Tuple）合并了不同类型的对象。
元组起源于函数编程语言（如 F#），这些语言中会频繁使用元组。
## 简单的例子
定义一对值分别为 `string` 和 `number` 的元组：
```ts
let tom: [string, number] = ['Tom', 25];
```
当赋值或访问一个已知索引的元素时，会得到正确的类型：
```ts
let tom: [string, number];
tom[0] = 'Tom';
tom[1] = 25;
tom[0].slice(1);
tom[1].toFixed(2);
```
也可以只赋值其中一项：
```ts
let tom: [string, number];
tom[0] = 'Tom';
```
但是当直接对元组类型的变量进行初始化或者赋值的时候，需要提供所有元组类型中指定的项。
```ts
let tom: [string, number];
tom = ['Tom', 25];
```
```ts
let tom: [string, number];
tom = ['Tom'];
// Property '1' is missing in type '[string]' but required in type '[string, number]'.
```
## 越界的元素
当添加越界的元素时，它的类型会被限制为元组中每个类型的联合类型：
```ts
let tom: [string, number];
tom = ['Tom', 25];
tom.push('male');
tom.push(true);
// Argument of type 'true' is not assignable to parameter of type 'string | number'.
```
## 参考
- [Basic Types # Tuple](http://www.typescriptlang.org/docs/handbook/basic-types.html#tuple)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Basic%20Types.html#元组-tuple)）
================================================
FILE: advanced/type-aliases.md
================================================
# 类型别名
类型别名用来给一个类型起个新名字。
## 简单的例子
```ts
type Name = string;
type NameResolver = () => string;
type NameOrResolver = Name | NameResolver;
function getName(n: NameOrResolver): Name {
if (typeof n === 'string') {
return n;
} else {
return n();
}
}
```
上例中，我们使用 `type` 创建类型别名。
类型别名常用于联合类型。
## 参考
- [Advanced Types # Type Aliases](http://www.typescriptlang.org/docs/handbook/advanced-types.html#type-aliases)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Advanced%20Types.html#类型别名)）
================================================
FILE: basics/README.md
================================================
# 基础
本部分介绍了 TypeScript 中的常用类型和一些基本概念，旨在让大家对 TypeScript 有个初步的理解。具体内容包括：
- [原始数据类型](primitive-data-types.md)
- [任意值](any.md)
- [类型推论](type-inference.md)
- [联合类型](union-types.md)
- [对象的类型——接口](type-of-object-interfaces.md)
- [数组的类型](type-of-array.md)
- [函数的类型](type-of-function.md)
- [类型断言](type-assertion.md)
- [声明文件](declaration-files.md)
- [内置对象](built-in-objects.md)
================================================
FILE: basics/any.md
================================================
# 任意值
任意值（Any）用来表示允许赋值为任意类型。
## 什么是任意值类型
如果是一个普通类型，在赋值过程中改变类型是不被允许的：
```ts
let myFavoriteNumber: string = 'seven';
myFavoriteNumber = 7;
// index.ts(2,1): error TS2322: Type 'number' is not assignable to type 'string'.
```
但如果是 `any` 类型，则允许被赋值为任意类型。
```ts
let myFavoriteNumber: any = 'seven';
myFavoriteNumber = 7;
```
## 任意值的属性和方法
在任意值上访问任何属性都是允许的：
```ts
let anyThing: any = 'hello';
console.log(anyThing.myName);
console.log(anyThing.myName.firstName);
```
也允许调用任何方法：
```ts
let anyThing: any = 'Tom';
anyThing.setName('Jerry');
anyThing.setName('Jerry').sayHello();
anyThing.myName.setFirstName('Cat');
```
可以认为，**声明一个变量为任意值之后，对它的任何操作，返回的内容的类型都是任意值**。
## 未声明类型的变量
**变量如果在声明的时候，未指定其类型，那么它会被识别为任意值类型**：
```ts
let something;
something = 'seven';
something = 7;
something.setName('Tom');
```
等价于
```ts
let something: any;
something = 'seven';
something = 7;
something.setName('Tom');
```
## 参考
- [Basic Types # Any](http://www.typescriptlang.org/docs/handbook/basic-types.html#any)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Basic%20Types.html#任意值)）
================================================
FILE: basics/built-in-objects.md
================================================
# 内置对象
JavaScript 中有很多[内置对象][]，它们可以直接在 TypeScript 中当做定义好了的类型。
内置对象是指根据标准在全局作用域（Global）上存在的对象。这里的标准是指 ECMAScript 和其他环境（比如 DOM）的标准。
## ECMAScript 的内置对象
ECMAScript 标准提供的内置对象有：
`Boolean`、`Error`、`Date`、`RegExp` 等。
我们可以在 TypeScript 中将变量定义为这些类型：
```ts
let b: Boolean = new Boolean(1);
let e: Error = new Error('Error occurred');
let d: Date = new Date();
let r: RegExp = /[a-z]/;
```
更多的内置对象，可以查看 [MDN 的文档][内置对象]。
而他们的定义文件，则在 [TypeScript 核心库的定义文件][]中。
## DOM 和 BOM 的内置对象
DOM 和 BOM 提供的内置对象有：
`Document`、`HTMLElement`、`Event`、`NodeList` 等。
TypeScript 中会经常用到这些类型：
```ts
let body: HTMLElement = document.body;
let allDiv: NodeList = document.querySelectorAll('div');
document.addEventListener('click', function(e: MouseEvent) {
// Do something
});
```
它们的定义文件同样在 [TypeScript 核心库的定义文件][]中。
## TypeScript 核心库的定义文件
[TypeScript 核心库的定义文件][]中定义了所有浏览器环境需要用到的类型，并且是预置在 TypeScript 中的。
当你在使用一些常用的方法的时候，TypeScript 实际上已经帮你做了很多类型判断的工作了，比如：
```ts
Math.pow(10, '2');
// index.ts(1,14): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
```
上面的例子中，`Math.pow` 必须接受两个 `number` 类型的参数。事实上 `Math.pow` 的类型定义如下：
```ts
interface Math {
/**
* Returns the value of a base expression taken to a specified power.
* @param x The base value of the expression.
* @param y The exponent value of the expression.
*/
pow(x: number, y: number): number;
}
```
再举一个 DOM 中的例子：
```ts
document.addEventListener('click', function(e) {
console.log(e.targetCurrent);
});
// index.ts(2,17): error TS2339: Property 'targetCurrent' does not exist on type 'MouseEvent'.
```
上面的例子中，`addEventListener` 方法是在 TypeScript 核心库中定义的：
```ts
interface Document extends Node, GlobalEventHandlers, NodeSelector, DocumentEvent {
addEventListener(type: string, listener: (ev: MouseEvent) => any, useCapture?: boolean): void;
}
```
所以 `e` 被推断成了 `MouseEvent`，而 `MouseEvent` 是没有 `targetCurrent` 属性的，所以报错了。
注意，TypeScript 核心库的定义中不包含 Node.js 部分。
## 用 TypeScript 写 Node.js
Node.js 不是内置对象的一部分，如果想用 TypeScript 写 Node.js，则需要引入第三方声明文件：
```bash
npm install @types/node --save-dev
```
## 参考
- [内置对象][]
- [TypeScript 核心库的定义文件][]
[内置对象]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects
[TypeScript 核心库的定义文件]: https://github.com/Microsoft/TypeScript/tree/master/src/lib
================================================
FILE: basics/declaration-files.md
================================================
# 声明文件
当使用第三方库时，我们需要引用它的声明文件，才能获得对应的代码补全、接口提示等功能。
## 新语法索引
由于本章涉及大量新语法，故在本章开头列出新语法的索引，方便大家在使用这些新语法时能快速查找到对应的讲解：
- [`declare var`](#declare-var) 声明全局变量
- [`declare function`](#declare-function) 声明全局方法
- [`declare class`](#declare-class) 声明全局类
- [`declare enum`](#declare-enum) 声明全局枚举类型
- [`declare namespace`](#declare-namespace) 声明（含有子属性的）全局对象
- [`interface` 和 `type`](#interface-和-type) 声明全局类型
- [`export`](#export) 导出变量
- [`export namespace`](#export-namespace) 导出（含有子属性的）对象
- [`export default`](#export-default) ES6 默认导出
- [`export =`](#export-1) commonjs 导出模块
- [`export as namespace`](#export-as-namespace) UMD 库声明全局变量
- [`declare global`](#declare-global) 扩展全局变量
- [`declare module`](#declare-module) 扩展模块
- [`/// <reference />`](#san-xie-xian-zhi-ling) 三斜线指令
## 什么是声明语句
假如我们想使用第三方库 jQuery，一种常见的方式是在 html 中通过 `<script>` 标签引入 jQuery，然后就可以使用全局变量 `$` 或 `jQuery` 了。
我们通常这样获取一个 `id` 是 `foo` 的元素：
```js
$('#foo');
// or
jQuery('#foo');
```
但是在 ts 中，编译器并不知道 `$` 或 `jQuery` 是什么东西[<sup>1</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/01-jquery)：
```ts
jQuery('#foo');
// ERROR: Cannot find name 'jQuery'.
```
这时，我们需要使用 `declare var` 来定义它的类型[<sup>2</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/02-declare-var)：
```ts
declare var jQuery: (selector: string) => any;
jQuery('#foo');
```
上例中，`declare var` 并没有真的定义一个变量，只是定义了全局变量 `jQuery` 的类型，仅仅会用于编译时的检查，在编译结果中会被删除。它编译结果是：
```js
jQuery('#foo');
```
除了 `declare var` 之外，还有其他很多种声明语句，将会在后面详细介绍。
## 什么是声明文件
通常我们会把声明语句放到一个单独的文件（`jQuery.d.ts`）中，这就是声明文件[<sup>3</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/03-jquery-d-ts)：
```ts
// src/jQuery.d.ts
declare var jQuery: (selector: string) => any;
```
```ts
// src/index.ts
jQuery('#foo');
```
声明文件必需以 `.d.ts` 为后缀。
一般来说，ts 会解析项目中所有的 `*.ts` 文件，当然也包含以 `.d.ts` 结尾的文件。所以当我们将 `jQuery.d.ts` 放到项目中时，其他所有 `*.ts` 文件就都可以获得 `jQuery` 的类型定义了。
```plain
/path/to/project
├── src
| ├── index.ts
| └── jQuery.d.ts
└── tsconfig.json
```
假如仍然无法解析，那么可以检查下 `tsconfig.json` 中的 `files`、`include` 和 `exclude` 配置，确保其包含了 `jQuery.d.ts` 文件。
这里只演示了全局变量这种模式的声明文件，假如是通过模块导入的方式使用第三方库的话，那么引入声明文件又是另一种方式了，将会在后面详细介绍。
### 第三方声明文件
当然，jQuery 的声明文件不需要我们定义了，社区已经帮我们定义好了：[jQuery in DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/jquery/index.d.ts)。
我们可以直接下载下来使用，但是更推荐的是使用 `@types` 统一管理第三方库的声明文件。
`@types` 的使用方式很简单，直接用 npm 安装对应的声明模块即可，以 jQuery 举例：
```bash
npm install @types/jquery --save-dev
```
可以在[这个页面](https://microsoft.github.io/TypeSearch/)搜索你需要的声明文件。
## 书写声明文件
当一个第三方库没有提供声明文件时，我们就需要自己书写声明文件了。前面只介绍了最简单的声明文件内容，而真正书写一个声明文件并不是一件简单的事，以下会详细介绍如何书写声明文件。
在不同的场景下，声明文件的内容和使用方式会有所区别。
库的使用场景主要有以下几种：
- [全局变量](#quan-ju-bian-liang)：通过 `<script>` 标签引入第三方库，注入全局变量
- [npm 包](#npm-bao)：通过 `import foo from 'foo'` 导入，符合 ES6 模块规范
- [UMD 库](#umd-ku)：既可以通过 `<script>` 标签引入，又可以通过 `import` 导入
- [直接扩展全局变量](#zhi-jie-kuo-zhan-quan-ju-bian-liang)：通过 `<script>` 标签引入后，改变一个全局变量的结构
- [在 npm 包或 UMD 库中扩展全局变量](#zai-npm-bao-huo-umd-ku-zhong-kuo-zhan-quan-ju-bian-liang)：引用 npm 包或 UMD 库后，改变一个全局变量的结构
- [模块插件](#mo-kuai-cha-jian)：通过 `<script>` 或 `import` 导入后，改变另一个模块的结构
### 全局变量
全局变量是最简单的一种场景，之前举的例子就是通过 `<script>` 标签引入 jQuery，注入全局变量 `$` 和 `jQuery`。
使用全局变量的声明文件时，如果是以 `npm install @types/xxx --save-dev` 安装的，则不需要任何配置。如果是将声明文件直接存放于当前项目中，则建议和其他源码一起放到 `src` 目录下（或者对应的源码目录下）：
```plain
/path/to/project
├── src
| ├── index.ts
| └── jQuery.d.ts
└── tsconfig.json
```
如果没有生效，可以检查下 `tsconfig.json` 中的 `files`、`include` 和 `exclude` 配置，确保其包含了 `jQuery.d.ts` 文件。
全局变量的声明文件主要有以下几种语法：
- [`declare var`](#declare-var) 声明全局变量
- [`declare function`](#declare-function) 声明全局方法
- [`declare class`](#declare-class) 声明全局类
- [`declare enum`](#declare-enum) 声明全局枚举类型
- [`declare namespace`](#declare-namespace) 声明（含有子属性的）全局对象
- [`interface` 和 `type`](#interface-he-type) 声明全局类型
#### `declare var`
在所有的声明语句中，`declare var` 是最简单的，如之前所学，它能够用来定义一个全局变量的类型。与其类似的，还有 `declare let` 和 `declare const`，使用 `let` 与使用 `var` 没有什么区别：
```ts
// src/jQuery.d.ts
declare let jQuery: (selector: string) => any;
```
```ts
// src/index.ts
jQuery('#foo');
// 使用 declare let 定义的 jQuery 类型，允许修改这个全局变量
jQuery = function(selector) {
return document.querySelector(selector);
};
```
而当我们使用 `const` 定义时，表示此时的全局变量是一个常量，不允许再去修改它的值了[<sup>4</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/04-declare-const-jquery)：
```ts
// src/jQuery.d.ts
declare const jQuery: (selector: string) => any;
jQuery('#foo');
// 使用 declare const 定义的 jQuery 类型，禁止修改这个全局变量
jQuery = function(selector) {
return document.querySelector(selector);
};
// ERROR: Cannot assign to 'jQuery' because it is a constant or a read-only property.
```
一般来说，全局变量都是禁止修改的常量，所以大部分情况都应该使用 `const` 而不是 `var` 或 `let`。
需要注意的是，声明语句中只能定义类型，切勿在声明语句中定义具体的实现[<sup>5</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/05-declare-jquery-value)：
```ts
declare const jQuery = function(selector) {
return document.querySelector(selector);
};
// ERROR: An implementation cannot be declared in ambient contexts.
```
#### `declare function`
`declare function` 用来定义全局函数的类型。jQuery 其实就是一个函数，所以也可以用 `function` 来定义：
```ts
// src/jQuery.d.ts
declare function jQuery(selector: string): any;
```
```ts
// src/index.ts
jQuery('#foo');
```
在函数类型的声明语句中，函数重载也是支持的[<sup>6</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/06-declare-function)：
```ts
// src/jQuery.d.ts
declare function jQuery(selector: string): any;
declare function jQuery(domReadyCallback: () => any): any;
```
```ts
// src/index.ts
jQuery('#foo');
jQuery(function() {
alert('Dom Ready!');
});
```
#### `declare class`
当全局变量是一个类的时候，我们用 `declare class` 来定义它的类型[<sup>7</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/07-declare-class)：
```ts
// src/Animal.d.ts
declare class Animal {
name: string;
constructor(name: string);
sayHi(): string;
}
```
```ts
// src/index.ts
let cat = new Animal('Tom');
```
同样的，`declare class` 语句也只能用来定义类型，不能用来定义具体的实现，比如定义 `sayHi` 方法的具体实现则会报错：
```ts
// src/Animal.d.ts
declare class Animal {
name: string;
constructor(name: string);
sayHi() {
return `My name is ${this.name}`;
};
// ERROR: An implementation cannot be declared in ambient contexts.
}
```
#### `declare enum`
使用 `declare enum` 定义的枚举类型也称作外部枚举（Ambient Enums），举例如下[<sup>8</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/08-declare-enum)：
```ts
// src/Directions.d.ts
declare enum Directions {
Up,
Down,
Left,
Right
}
```
```ts
// src/index.ts
let directions = [Directions.Up, Directions.Down, Directions.Left, Directions.Right];
```
与其他全局变量的类型声明一致，`declare enum` 仅用来定义类型，而不是具体的值。
`Directions.d.ts` 仅仅会用于编译时的检查，声明文件里的内容在编译结果中会被删除。它编译结果是：
```js
var directions = [Directions.Up, Directions.Down, Directions.Left, Directions.Right];
```
其中 `Directions` 是由第三方库定义好的全局变量。
#### `declare namespace`
`namespace` 是 ts 早期时为了解决模块化而创造的关键字，中文称为命名空间。
由于历史遗留原因，在早期还没有 ES6 的时候，ts 提供了一种模块化方案，使用 `module` 关键字表示内部模块。但由于后来 ES6 也使用了 `module` 关键字，ts 为了兼容 ES6，使用 `namespace` 替代了自己的 `module`，更名为命名空间。
随着 ES6 的广泛应用，现在已经不建议再使用 ts 中的 `namespace`，而推荐使用 ES6 的模块化方案了，故我们不再需要学习 `namespace` 的使用了。
`namespace` 被淘汰了，但是在声明文件中，`declare namespace` 还是比较常用的，它用来表示全局变量是一个对象，包含很多子属性。
比如 `jQuery` 是一个全局变量，它是一个对象，提供了一个 `jQuery.ajax` 方法可以调用，那么我们就应该使用 `declare namespace jQuery` 来声明这个拥有多个子属性的全局变量。
```ts
// src/jQuery.d.ts
declare namespace jQuery {
function ajax(url: string, settings?: any): void;
}
```
```ts
// src/index.ts
jQuery.ajax('/api/get_something');
```
注意，在 `declare namespace` 内部，我们直接使用 `function ajax` 来声明函数，而不是使用 `declare function ajax`。类似的，也可以使用 `const`, `class`, `enum` 等语句[<sup>9</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/09-declare-namespace)：
```ts
// src/jQuery.d.ts
declare namespace jQuery {
function ajax(url: string, settings?: any): void;
const version: number;
class Event {
blur(eventType: EventType): void
}
enum EventType {
CustomClick
}
}
```
```ts
// src/index.ts
jQuery.ajax('/api/get_something');
console.log(jQuery.version);
const e = new jQuery.Event();
e.blur(jQuery.EventType.CustomClick);
```
##### 嵌套的命名空间
如果对象拥有深层的层级，则需要用嵌套的 `namespace` 来声明深层的属性的类型[<sup>10</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/10-declare-namespace-nesting)：
```ts
// src/jQuery.d.ts
declare namespace jQuery {
function ajax(url: string, settings?: any): void;
namespace fn {
function extend(object: any): void;
}
}
```
```ts
// src/index.ts
jQuery.ajax('/api/get_something');
jQuery.fn.extend({
check: function() {
return this.each(function() {
this.checked = true;
});
}
});
```
假如 `jQuery` 下仅有 `fn` 这一个属性（没有 `ajax` 等其他属性或方法），则可以不需要嵌套 `namespace`[<sup>11</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/11-declare-namespace-dot)：
```ts
// src/jQuery.d.ts
declare namespace jQuery.fn {
function extend(object: any): void;
}
```
```ts
// src/index.ts
jQuery.fn.extend({
check: function() {
return this.each(function() {
this.checked = true;
});
}
});
```
#### `interface` 和 `type`
除了全局变量之外，可能有一些类型我们也希望能暴露出来。在类型声明文件中，我们可以直接使用 `interface` 或 `type` 来声明一个全局的接口或类型[<sup>12</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/12-interface)：
```ts
// src/jQuery.d.ts
interface AjaxSettings {
method?: 'GET' | 'POST'
data?: any;
}
declare namespace jQuery {
function ajax(url: string, settings?: AjaxSettings): void;
}
```
这样的话，在其他文件中也可以使用这个接口或类型了：
```ts
// src/index.ts
let settings: AjaxSettings = {
method: 'POST',
data: {
name: 'foo'
}
};
jQuery.ajax('/api/post_something', settings);
```
`type` 与 `interface` 类似，不再赘述。
##### 防止命名冲突
暴露在最外层的 `interface` 或 `type` 会作为全局类型作用于整个项目中，我们应该尽可能的减少全局变量或全局类型的数量。故最好将他们放到 `namespace` 下[<sup>13</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/13-avoid-name-conflict)：
```ts
// src/jQuery.d.ts
declare namespace jQuery {
interface AjaxSettings {
method?: 'GET' | 'POST'
data?: any;
}
function ajax(url: string, settings?: AjaxSettings): void;
}
```
注意，在使用这个 `interface` 的时候，也应该加上 `jQuery` 前缀：
```ts
// src/index.ts
let settings: jQuery.AjaxSettings = {
method: 'POST',
data: {
name: 'foo'
}
};
jQuery.ajax('/api/post_something', settings);
```
#### 声明合并
假如 jQuery 既是一个函数，可以直接被调用 `jQuery('#foo')`，又是一个对象，拥有子属性 `jQuery.ajax()`（事实确实如此），那么我们可以组合多个声明语句，它们会不冲突的合并起来[<sup>14</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/14-declaration-merging)：
```ts
// src/jQuery.d.ts
declare function jQuery(selector: string): any;
declare namespace jQuery {
function ajax(url: string, settings?: any): void;
}
```
```ts
// src/index.ts
jQuery('#foo');
jQuery.ajax('/api/get_something');
```
关于声明合并的更多用法，可以查看[声明合并](../advanced/declaration-merging.md)章节。
### npm 包
一般我们通过 `import foo from 'foo'` 导入一个 npm 包，这是符合 ES6 模块规范的。
在我们尝试给一个 npm 包创建声明文件之前，需要先看看它的声明文件是否已经存在。一般来说，npm 包的声明文件可能存在于两个地方：
1. 与该 npm 包绑定在一起。判断依据是 `package.json` 中有 `types` 字段，或者有一个 `index.d.ts` 声明文件。这种模式不需要额外安装其他包，是最为推荐的，所以以后我们自己创建 npm 包的时候，最好也将声明文件与 npm 包绑定在一起。
2. 发布到 `@types` 里。我们只需要尝试安装一下对应的 `@types` 包就知道是否存在该声明文件，安装命令是 `npm install @types/foo --save-dev`。这种模式一般是由于 npm 包的维护者没有提供声明文件，所以只能由其他人将声明文件发布到 `@types` 里了。
假如以上两种方式都没有找到对应的声明文件，那么我们就需要自己为它写声明文件了。由于是通过 `import` 语句导入的模块，所以声明文件存放的位置也有所约束，一般有两种方案：
1. 创建一个 `node_modules/@types/foo/index.d.ts` 文件，存放 `foo` 模块的声明文件。这种方式不需要额外的配置，但是 `node_modules` 目录不稳定，代码也没有被保存到仓库中，无法回溯版本，有不小心被删除的风险，故不太建议用这种方案，一般只用作临时测试。
2. 创建一个 `types` 目录，专门用来管理自己写的声明文件，将 `foo` 的声明文件放到 `types/foo/index.d.ts` 中。这种方式需要配置下 `tsconfig.json` 中的 `paths` 和 `baseUrl` 字段。
目录结构：
```plain
/path/to/project
├── src
| └── index.ts
├── types
| └── foo
| └── index.d.ts
└── tsconfig.json
```
`tsconfig.json` 内容：
```json
{
"compilerOptions": {
"module": "commonjs",
"baseUrl": "./",
"paths": {
"*": ["types/*"]
}
}
}
```
如此配置之后，通过 `import` 导入 `foo` 的时候，也会去 `types` 目录下寻找对应的模块的声明文件了。
注意 `module` 配置可以有很多种选项，不同的选项会影响模块的导入导出模式。这里我们使用了 `commonjs` 这个最常用的选项，后面的教程也都默认使用的这个选项。
不管采用了以上两种方式中的哪一种，我都**强烈建议**大家将书写好的声明文件（通过给第三方库发 pull request，或者直接提交到 `@types` 里）发布到开源社区中，享受了这么多社区的优秀的资源，就应该在力所能及的时候给出一些回馈。只有所有人都参与进来，才能让 ts 社区更加繁荣。
npm 包的声明文件主要有以下几种语法：
- [`export`](#export) 导出变量
- [`export namespace`](#export-namespace) 导出（含有子属性的）对象
- [`export default`](#export-default) ES6 默认导出
- [`export =`](#export-1) commonjs 导出模块
#### `export`
npm 包的声明文件与全局变量的声明文件有很大区别。在 npm 包的声明文件中，使用 `declare` 不再会声明一个全局变量，而只会在当前文件中声明一个局部变量。只有在声明文件中使用 `export` 导出，然后在使用方 `import` 导入后，才会应用到这些类型声明。
`export` 的语法与普通的 ts 中的语法类似，区别仅在于声明文件中禁止定义具体的实现[<sup>15</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/15-export)：
```ts
// types/foo/index.d.ts
export const name: string;
export function getName(): string;
export class Animal {
constructor(name: string);
sayHi(): string;
}
export enum Directions {
Up,
Down,
Left,
Right
}
export interface Options {
data: any;
}
```
对应的导入和使用模块应该是这样：
```ts
// src/index.ts
import { name, getName, Animal, Directions, Options } from 'foo';
console.log(name);
let myName = getName();
let cat = new Animal('Tom');
let directions = [Directions.Up, Directions.Down, Directions.Left, Directions.Right];
let options: Options = {
data: {
name: 'foo'
}
};
```
##### 混用 `declare` 和 `export`
我们也可以使用 `declare` 先声明多个变量，最后再用 `export` 一次性导出。上例的声明文件可以等价的改写为[<sup>16</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/16-declare-and-export)：
```ts
// types/foo/index.d.ts
declare const name: string;
declare function getName(): string;
declare class Animal {
constructor(name: string);
sayHi(): string;
}
declare enum Directions {
Up,
Down,
Left,
Right
}
interface Options {
data: any;
}
export { name, getName, Animal, Directions, Options };
```
注意，与全局变量的声明文件类似，`interface` 前是不需要 `declare` 的。
#### `export namespace`
与 `declare namespace` 类似，`export namespace` 用来导出一个拥有子属性的对象[<sup>17</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/17-export-namespace)：
```ts
// types/foo/index.d.ts
export namespace foo {
const name: string;
namespace bar {
function baz(): string;
}
}
```
```ts
// src/index.ts
import { foo } from 'foo';
console.log(foo.name);
foo.bar.baz();
```
#### `export default`
在 ES6 模块系统中，使用 `export default` 可以导出一个默认值，使用方可以用 `import foo from 'foo'` 而不是 `import { foo } from 'foo'` 来导入这个默认值。
在类型声明文件中，`export default` 用来导出默认值的类型[<sup>18</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/18-export-default)：
```ts
// types/foo/index.d.ts
export default function foo(): string;
```
```ts
// src/index.ts
import foo from 'foo';
foo();
```
注意，只有 `function`、`class` 和 `interface` 可以直接默认导出，其他的变量需要先定义出来，再默认导出[<sup>19</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/19-export-default-enum-error)：
```ts
// types/foo/index.d.ts
export default enum Directions {
// ERROR: Expression expected.
Up,
Down,
Left,
Right
}
```
上例中 `export default enum` 是错误的语法，需要使用 `declare enum` 定义出来，然后使用 `export default` 导出：
```ts
// types/foo/index.d.ts
declare enum Directions {
Up,
Down,
Left,
Right
}
export default Directions;
```
针对这种默认导出，我们一般会将导出语句放在整个声明文件的最前面[<sup>20</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/20-export-default-enum)：
```ts
// types/foo/index.d.ts
export default Directions;
declare enum Directions {
Up,
Down,
Left,
Right
}
```
#### `export =`
在 commonjs 规范中，我们用以下方式来导出一个模块：
```js
// 整体导出
module.exports = foo;
// 单个导出
exports.bar = bar;
```
在 ts 中，针对这种模块导出，有多种方式可以导入，第一种方式是 `const ... = require`：
```js
// 整体导入
const foo = require('foo');
// 单个导入
const bar = require('foo').bar;
```
第二种方式是 `import ... from`，注意针对整体导出，需要使用 `import * as` 来导入：
```ts
// 整体导入
import * as foo from 'foo';
// 单个导入
import { bar } from 'foo';
```
第三种方式是 `import ... require`，这也是 ts 官方推荐的方式：
```ts
// 整体导入
import foo = require('foo');
// 单个导入
import bar = require('foo').bar;
```
对于这种使用 commonjs 规范的库，假如要为它写类型声明文件的话，就需要使用到 `export =` 这种语法了[<sup>21</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/21-export-equal)：
```ts
// types/foo/index.d.ts
export = foo;
declare function foo(): string;
declare namespace foo {
const bar: number;
}
```
需要注意的是，上例中使用了 `export =` 之后，就不能再单个导出 `export { bar }` 了。所以我们通过声明合并，使用 `declare namespace foo` 来将 `bar` 合并到 `foo` 里。
准确地讲，`export =` 不仅可以用在声明文件中，也可以用在普通的 ts 文件中。实际上，`import ... require` 和 `export =` 都是 ts 为了兼容 AMD 规范和 commonjs 规范而创立的新语法，由于并不常用也不推荐使用，所以这里就不详细介绍了，感兴趣的可以看[官方文档](https://www.typescriptlang.org/docs/handbook/modules.html#export--and-import--require)。
由于很多第三方库是 commonjs 规范的，所以声明文件也就不得不用到 `export =` 这种语法了。但是还是需要再强调下，相比与 `export =`，我们更推荐使用 ES6 标准的 `export default` 和 `export`。
### UMD 库
既可以通过 `<script>` 标签引入，又可以通过 `import` 导入的库，称为 UMD 库。相比于 npm 包的类型声明文件，我们需要额外声明一个全局变量，为了实现这种方式，ts 提供了一个新语法 `export as namespace`。
#### `export as namespace`
一般使用 `export as namespace` 时，都是先有了 npm 包的声明文件，再基于它添加一条 `export as namespace` 语句，即可将声明好的一个变量声明为全局变量，举例如下[<sup>22</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/22-export-as-namespace)：
```ts
// types/foo/index.d.ts
export as namespace foo;
export = foo;
declare function foo(): string;
declare namespace foo {
const bar: number;
}
```
当然它也可以与 `export default` 一起使用：
```ts
// types/foo/index.d.ts
export as namespace foo;
export default foo;
declare function foo(): string;
declare namespace foo {
const bar: number;
}
```
### 直接扩展全局变量
有的第三方库扩展了一个全局变量，可是此全局变量的类型却没有相应的更新过来，就会导致 ts 编译错误，此时就需要扩展全局变量的类型。比如扩展 `String` 类型[<sup>23</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/23-merge-global-interface)：
```ts
interface String {
prependHello(): string;
}
'foo'.prependHello();
```
通过声明合并，使用 `interface String` 即可给 `String` 添加属性或方法。
也可以使用 `declare namespace` 给已有的命名空间添加类型声明[<sup>24</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/24-merge-global-namespace)：
```ts
// types/jquery-plugin/index.d.ts
declare namespace JQuery {
interface CustomOptions {
bar: string;
}
}
interface JQueryStatic {
foo(options: JQuery.CustomOptions): string;
}
```
```ts
// src/index.ts
jQuery.foo({
bar: ''
});
```
### 在 npm 包或 UMD 库中扩展全局变量
如之前所说，对于一个 npm 包或者 UMD 库的声明文件，只有 `export` 导出的类型声明才能被导入。所以对于 npm 包或 UMD 库，如果导入此库之后会扩展全局变量，则需要使用另一种语法在声明文件中扩展全局变量的类型，那就是 `declare global`。
#### `declare global`
使用 `declare global` 可以在 npm 包或者 UMD 库的声明文件中扩展全局变量的类型[<sup>25</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/25-declare-global)：
```ts
// types/foo/index.d.ts
declare global {
interface String {
prependHello(): string;
}
}
export {};
```
```ts
// src/index.ts
'bar'.prependHello();
```
注意即使此声明文件不需要导出任何东西，仍然需要导出一个空对象，用来告诉编译器这是一个模块的声明文件，而不是一个全局变量的声明文件。
### 模块插件
有时通过 `import` 导入一个模块插件，可以改变另一个原有模块的结构。此时如果原有模块已经有了类型声明文件，而插件模块没有类型声明文件，就会导致类型不完整，缺少插件部分的类型。ts 提供了一个语法 `declare module`，它可以用来扩展原有模块的类型。
#### `declare module`
如果是需要扩展原有模块的话，需要在类型声明文件中先引用原有模块，再使用 `declare module` 扩展原有模块[<sup>26</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/26-declare-module)：
```ts
// types/moment-plugin/index.d.ts
import * as moment from 'moment';
declare module 'moment' {
export function foo(): moment.CalendarKey;
}
```
```ts
// src/index.ts
import * as moment from 'moment';
import 'moment-plugin';
moment.foo();
```
`declare module` 也可用于在一个文件中一次性声明多个模块的类型[<sup>27</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/27-multiple-declare-module)：
```ts
// types/foo-bar.d.ts
declare module 'foo' {
export interface Foo {
foo: string;
}
}
declare module 'bar' {
export function bar(): string;
}
```
```ts
// src/index.ts
import { Foo } from 'foo';
import * as bar from 'bar';
let f: Foo;
bar.bar();
```
### 声明文件中的依赖
一个声明文件有时会依赖另一个声明文件中的类型，比如在前面的 `declare module` 的例子中，我们就在声明文件中导入了 `moment`，并且使用了 `moment.CalendarKey` 这个类型：
```ts
// types/moment-plugin/index.d.ts
import * as moment from 'moment';
declare module 'moment' {
export function foo(): moment.CalendarKey;
}
```
除了可以在声明文件中通过 `import` 导入另一个声明文件中的类型之外，还有一个语法也可以用来导入另一个声明文件，那就是三斜线指令。
#### 三斜线指令
与 `namespace` 类似，三斜线指令也是 ts 在早期版本中为了描述模块之间的依赖关系而创造的语法。随着 ES6 的广泛应用，现在已经不建议再使用 ts 中的三斜线指令来声明模块之间的依赖关系了。
但是在声明文件中，它还是有一定的用武之地。
类似于声明文件中的 `import`，它可以用来导入另一个声明文件。与 `import` 的区别是，当且仅当在以下几个场景下，我们才需要使用三斜线指令替代 `import`：
- 当我们在**书写**一个全局变量的声明文件时
- 当我们需要**依赖**一个全局变量的声明文件时
##### **书写**一个全局变量的声明文件
这些场景听上去很拗口，但实际上很好理解——在全局变量的声明文件中，是不允许出现 `import`, `export` 关键字的。一旦出现了，那么他就会被视为一个 npm 包或 UMD 库，就不再是全局变量的声明文件了。故当我们在书写一个全局变量的声明文件时，如果需要引用另一个库的类型，那么就必须用三斜线指令了[<sup>28</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/28-triple-slash-directives)：
```ts
// types/jquery-plugin/index.d.ts
/// <reference types="jquery" />
declare function foo(options: JQuery.AjaxSettings): string;
```
```ts
// src/index.ts
foo({});
```
三斜线指令的语法如上，`///` 后面使用 xml 的格式添加了对 `jquery` 类型的依赖，这样就可以在声明文件中使用 `JQuery.AjaxSettings` 类型了。
注意，三斜线指令必须放在文件的最顶端，三斜线指令的前面只允许出现单行或多行注释。
##### **依赖**一个全局变量的声明文件
在另一个场景下，当我们需要依赖一个全局变量的声明文件时，由于全局变量不支持通过 `import` 导入，当然也就必须使用三斜线指令来引入了[<sup>29</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/29-triple-slash-directives-global)：
```ts
// types/node-plugin/index.d.ts
/// <reference types="node" />
export function foo(p: NodeJS.Process): string;
```
```ts
// src/index.ts
import { foo } from 'node-plugin';
foo(global.process);
```
在上面的例子中，我们通过三斜线指引入了 `node` 的类型，然后在声明文件中使用了 `NodeJS.Process` 这个类型。最后在使用到 `foo` 的时候，传入了 `node` 中的全局变量 `process`。
由于引入的 `node` 中的类型都是全局变量的类型，它们是没有办法通过 `import` 来导入的，所以这种场景下也只能通过三斜线指令来引入了。
以上两种使用场景下，都是由于需要书写或需要依赖全局变量的声明文件，所以必须使用三斜线指令。在其他的一些不是必要使用三斜线指令的情况下，就都需要使用 `import` 来导入。
##### 拆分声明文件
当我们的全局变量的声明文件太大时，可以通过拆分为多个文件，然后在一个入口文件中将它们一一引入，来提高代码的可维护性。比如 `jQuery` 的声明文件就是这样的：
```ts
// node_modules/@types/jquery/index.d.ts
/// <reference types="sizzle" />
/// <reference path="JQueryStatic.d.ts" />
/// <reference path="JQuery.d.ts" />
/// <reference path="misc.d.ts" />
/// <reference path="legacy.d.ts" />
export = jQuery;
```
其中用到了 `types` 和 `path` 两种不同的指令。它们的区别是：`types` 用于声明对另一个库的依赖，而 `path` 用于声明对另一个文件的依赖。
上例中，`sizzle` 是与 `jquery` 平行的另一个库，所以需要使用 `types="sizzle"` 来声明对它的依赖。而其他的三斜线指令就是将 `jquery` 的声明拆分到不同的文件中了，然后在这个入口文件中使用 `path="foo"` 将它们一一引入。
##### 其他三斜线指令
除了这两种三斜线指令之外，还有其他的三斜线指令，比如 `/// <reference no-default-lib="true"/>`, `/// <amd-module />` 等，但它们都是废弃的语法，故这里就不介绍了，详情可见[官网](http://www.typescriptlang.org/docs/handbook/triple-slash-directives.html)。
### 自动生成声明文件
如果库的源码本身就是由 ts 写的，那么在使用 `tsc` 脚本将 ts 编译为 js 的时候，添加 `declaration` 选项，就可以同时也生成 `.d.ts` 声明文件了。
我们可以在命令行中添加 `--declaration`（简写 `-d`），或者在 `tsconfig.json` 中添加 `declaration` 选项。这里以 `tsconfig.json` 为例：
```json
{
"compilerOptions": {
"module": "commonjs",
"outDir": "lib",
"declaration": true,
}
}
```
上例中我们添加了 `outDir` 选项，将 ts 文件的编译结果输出到 `lib` 目录下，然后添加了 `declaration` 选项，设置为 `true`，表示将会由 ts 文件自动生成 `.d.ts` 声明文件，也会输出到 `lib` 目录下。
运行 `tsc` 之后，目录结构如下[<sup>30</sup>](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/declaration-files/30-auto-d-ts)：
```plain
/path/to/project
├── lib
| ├── bar
| | ├── index.d.ts
| | └── index.js
| ├── index.d.ts
| └── index.js
├── src
| ├── bar
| | └── index.ts
| └── index.ts
├── package.json
└── tsconfig.json
```
在这个例子中，`src` 目录下有两个 ts 文件，分别是 `src/index.ts` 和 `src/bar/index.ts`，它们被编译到 `lib` 目录下的同时，也会生成对应的两个声明文件 `lib/index.d.ts` 和 `lib/bar/index.d.ts`。它们的内容分别是：
```ts
// src/index.ts
export * from './bar';
export default function foo() {
return 'foo';
}
```
```ts
// src/bar/index.ts
export function bar() {
return 'bar';
}
```
```ts
// lib/index.d.ts
export * from './bar';
export default function foo(): string;
```
```ts
// lib/bar/index.d.ts
export declare function bar(): string;
```
可见，自动生成的声明文件基本保持了源码的结构，而将具体实现去掉了，生成了对应的类型声明。
使用 `tsc` 自动生成声明文件时，每个 ts 文件都会对应一个 `.d.ts` 声明文件。这样的好处是，使用方不仅可以在使用 `import foo from 'foo'` 导入默认的模块时获得类型提示，还可以在使用 `import bar from 'foo/lib/bar'` 导入一个子模块时，也获得对应的类型提示。
除了 `declaration` 选项之外，还有几个选项也与自动生成声明文件有关，这里只简单列举出来，不做详细演示了：
- `declarationDir` 设置生成 `.d.ts` 文件的目录
- `declarationMap` 对每个 `.d.ts` 文件，都生成对应的 `.d.ts.map`（sourcemap）文件
- `emitDeclarationOnly` 仅生成 `.d.ts` 文件，不生成 `.js` 文件
## 发布声明文件
当我们为一个库写好了声明文件之后，下一步就是将它发布出去了。
此时有两种方案：
1. 将声明文件和源码放在一起
2. 将声明文件发布到 `@types` 下
这两种方案中优先选择第一种方案。保持声明文件与源码在一起，使用时就不需要额外增加单独的声明文件库的依赖了，而且也能保证声明文件的版本与源码的版本保持一致。
仅当我们在给别人的仓库添加类型声明文件，但原作者不愿意合并 pull request 时，才需要使用第二种方案，将声明文件发布到 `@types` 下。
### 将声明文件和源码放在一起
如果声明文件是通过 `tsc` 自动生成的，那么无需做任何其他配置，只需要把编译好的文件也发布到 npm 上，使用方就可以获取到类型提示了。
如果是手动写的声明文件，那么需要满足以下条件之一，才能被正确的识别：
- 给 `package.json` 中的 `types` 或 `typings` 字段指定一个类型声明文件地址
- 在项目根目录下，编写一个 `index.d.ts` 文件
- 针对入口文件（`package.json` 中的 `main` 字段指定的入口文件），编写一个同名不同后缀的 `.d.ts` 文件
第一种方式是给 `package.json` 中的 `types` 或 `typings` 字段指定一个类型声明文件地址。比如：
```json
{
"name": "foo",
"version": "1.0.0",
"main": "lib/index.js",
"types": "foo.d.ts",
}
```
指定了 `types` 为 `foo.d.ts` 之后，导入此库的时候，就会去找 `foo.d.ts` 作为此库的类型声明文件了。
`typings` 与 `types` 一样，只是另一种写法。
如果没有指定 `types` 或 `typings`，那么就会在根目录下寻找 `index.d.ts` 文件，将它视为此库的类型声明文件。
如果没有找到 `index.d.ts` 文件，那么就会寻找入口文件（`package.json` 中的 `main` 字段指定的入口文件）是否存在对应同名不同后缀的 `.d.ts` 文件。
比如 `package.json` 是这样时：
```json
{
"name": "foo",
"version": "1.0.0",
"main": "lib/index.js"
}
```
就会先识别 `package.json` 中是否存在 `types` 或 `typings` 字段。发现不存在，那么就会寻找是否存在 `index.d.ts` 文件。如果还是不存在，那么就会寻找是否存在 `lib/index.d.ts` 文件。假如说连 `lib/index.d.ts` 都不存在的话，就会被认为是一个没有提供类型声明文件的库了。
有的库为了支持导入子模块，比如 `import bar from 'foo/lib/bar'`，就需要额外再编写一个类型声明文件 `lib/bar.d.ts` 或者 `lib/bar/index.d.ts`，这与自动生成声明文件类似，一个库中同时包含了多个类型声明文件。
### 将声明文件发布到 `@types` 下
如果我们是在给别人的仓库添加类型声明文件，但原作者不愿意合并 pull request，那么就需要将声明文件发布到 `@types` 下。
与普通的 npm 模块不同，`@types` 是统一由 [DefinitelyTyped][] 管理的。要将声明文件发布到 `@types` 下，就需要给 [DefinitelyTyped][] 创建一个 pull-request，其中包含了类型声明文件，测试代码，以及 `tsconfig.json` 等。
pull-request 需要符合它们的规范，并且通过测试，才能被合并，稍后就会被自动发布到 `@types` 下。
在 [DefinitelyTyped][] 中创建一个新的类型声明，需要用到一些工具，[DefinitelyTyped][] 的文档中已经有了[详细的介绍](https://github.com/DefinitelyTyped/DefinitelyTyped#create-a-new-package)，这里就不赘述了，以官方文档为准。
如果大家有此类需求，可以参考下笔者[提交的 pull-request](https://github.com/DefinitelyTyped/DefinitelyTyped/pull/30336/files) 。
## 参考
- [Writing Declaration Files](http://www.typescriptlang.org/docs/handbook/writing-declaration-files.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/declaration%20files/Introduction.html)）
- [Triple-Slash Directives](http://www.typescriptlang.org/docs/handbook/triple-slash-directives.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Triple-Slash%20Directives.html)）
- [typeRoots or paths](https://github.com/Microsoft/TypeScript/issues/22217#issuecomment-369783776)
- [DefinitelyTyped][]
[DefinitelyTyped]: https://github.com/DefinitelyTyped/DefinitelyTyped/
================================================
FILE: basics/primitive-data-types.md
================================================
# 原始数据类型
JavaScript 的类型分为两种：原始数据类型（[Primitive data types][]）和对象类型（Object types）。
原始数据类型包括：布尔值、数值、字符串、`null`、`undefined` 以及 ES6 中的新类型 [`Symbol`][] 和 ES10 中的新类型 [`BigInt`][]。
本节主要介绍**前五种**原始数据类型在 TypeScript 中的应用。
## 布尔值
布尔值是最基础的数据类型，在 TypeScript 中，使用 `boolean` 定义布尔值类型：
```ts
let isDone: boolean = false;
// 编译通过
// 后面约定，未强调编译错误的代码片段，默认为编译通过
```
注意，使用构造函数 `Boolean` 创造的对象**不是**布尔值：
```ts
let createdByNewBoolean: boolean = new Boolean(1);
// Type 'Boolean' is not assignable to type 'boolean'.
// 'boolean' is a primitive, but 'Boolean' is a wrapper object. Prefer using 'boolean' when possible.
```
事实上 `new Boolean()` 返回的是一个 `Boolean` 对象：
```ts
let createdByNewBoolean: Boolean = new Boolean(1);
```
直接调用 `Boolean` 也可以返回一个 `boolean` 类型：
```ts
let createdByBoolean: boolean = Boolean(1);
```
在 TypeScript 中，`boolean` 是 JavaScript 中的基本类型，而 `Boolean` 是 JavaScript 中的构造函数。其他基本类型（除了 `null` 和 `undefined`）一样，不再赘述。
## 数值
使用 `number` 定义数值类型：
```ts
let decLiteral: number = 6;
let hexLiteral: number = 0xf00d;
// ES6 中的二进制表示法
let binaryLiteral: number = 0b1010;
// ES6 中的八进制表示法
let octalLiteral: number = 0o744;
let notANumber: number = NaN;
let infinityNumber: number = Infinity;
```
编译结果：
```js
var decLiteral = 6;
var hexLiteral = 0xf00d;
// ES6 中的二进制表示法
var binaryLiteral = 10;
// ES6 中的八进制表示法
var octalLiteral = 484;
var notANumber = NaN;
var infinityNumber = Infinity;
```
其中 `0b1010` 和 `0o744` 是 [ES6 中的二进制和八进制表示法][]，它们会被编译为十进制数字。
## 字符串
使用 `string` 定义字符串类型：
```ts
let myName: string = 'Tom';
let myAge: number = 25;
// 模板字符串
let sentence: string = `Hello, my name is ${myName}.
I'll be ${myAge + 1} years old next month.`;
```
编译结果：
```js
var myName = 'Tom';
var myAge = 25;
// 模板字符串
var sentence = "Hello, my name is " + myName + ".\nI'll be " + (myAge + 1) + " years old next month.";
```
其中 <code>`</code> 用来定义 [ES6 中的模板字符串][]，`${expr}` 用来在模板字符串中嵌入表达式。
## 空值
JavaScript 没有空值（Void）的概念，在 TypeScript 中，可以用 `void` 表示没有任何返回值的函数：
```ts
function alertName(): void {
alert('My name is Tom');
}
```
声明一个 `void` 类型的变量没有什么用，因为你只能将它赋值为 `undefined` 和 `null`（只在 --strictNullChecks 未指定时）：
```ts
let unusable: void = undefined;
```
## Null 和 Undefined
在 TypeScript 中，可以使用 `null` 和 `undefined` 来定义这两个原始数据类型：
```ts
let u: undefined = undefined;
let n: null = null;
```
与 `void` 的区别是，`undefined` 和 `null` 是所有类型的子类型。也就是说 `undefined` 类型的变量，可以赋值给 `number` 类型的变量：
```ts
// 这样不会报错
let num: number = undefined;
```
```ts
// 这样也不会报错
let u: undefined;
let num: number = u;
```
而 `void` 类型的变量不能赋值给 `number` 类型的变量：
```ts
let u: void;
let num: number = u;
// Type 'void' is not assignable to type 'number'.
```
## 参考
- [Basic Types](http://www.typescriptlang.org/docs/handbook/basic-types.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Basic%20Types.html)）
- [Primitive data types][]
- [ES6 中的新类型 `Symbol`][]
- [ES6 中的二进制和八进制表示法][]
- [ES6 中的模板字符串][]
[Primitive data types]: https://developer.mozilla.org/en-US/docs/Glossary/Primitive
[`Symbol`]: http://es6.ruanyifeng.com/#docs/symbol
[`BigInt`]: https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/BigInt
[ES6 中的二进制和八进制表示法]: http://es6.ruanyifeng.com/#docs/number#二进制和八进制表示法
[ES6 中的模板字符串]: http://es6.ruanyifeng.com/#docs/string#模板字符串
================================================
FILE: basics/type-assertion.md
================================================
# 类型断言
类型断言（Type Assertion）可以用来手动指定一个值的类型。
## 语法
```ts
值 as 类型
```
或
```ts
<类型>值
```
在 tsx 语法（React 的 jsx 语法的 ts 版）中必须使用前者，即 `值 as 类型`。
形如 `<Foo>` 的语法在 tsx 中表示的是一个 `ReactNode`，在 ts 中除了表示类型断言之外，也可能是表示一个[泛型][]。
故建议大家在使用类型断言时，统一使用 `值 as 类型` 这样的语法，本书中也会贯彻这一思想。
## 类型断言的用途
类型断言的常见用途有以下几种：
### 将一个联合类型断言为其中一个类型
[之前提到过](union-types.md#访问联合类型的属性或方法)，当 TypeScript 不确定一个联合类型的变量到底是哪个类型的时候，我们**只能访问此联合类型的所有类型中共有的属性或方法**：
```ts
interface Cat {
name: string;
run(): void;
}
interface Fish {
name: string;
swim(): void;
}
function getName(animal: Cat | Fish) {
return animal.name;
}
```
而有时候，我们确实需要在还不确定类型的时候就访问其中一个类型特有的属性或方法，比如：
```ts
interface Cat {
name: string;
run(): void;
}
interface Fish {
name: string;
swim(): void;
}
function isFish(animal: Cat | Fish) {
if (typeof animal.swim === 'function') {
return true;
}
return false;
}
// index.ts:11:23 - error TS2339: Property 'swim' does not exist on type 'Cat | Fish'.
// Property 'swim' does not exist on type 'Cat'.
```
上面的例子中，获取 `animal.swim` 的时候会报错。
此时可以使用类型断言，将 `animal` 断言成 `Fish`：
```ts
interface Cat {
name: string;
run(): void;
}
interface Fish {
name: string;
swim(): void;
}
function isFish(animal: Cat | Fish) {
if (typeof (animal as Fish).swim === 'function') {
return true;
}
return false;
}
```
这样就可以解决访问 `animal.swim` 时报错的问题了。
需要注意的是，类型断言只能够「欺骗」TypeScript 编译器，无法避免运行时的错误，反而滥用类型断言可能会导致运行时错误：
```ts
interface Cat {
name: string;
run(): void;
}
interface Fish {
name: string;
swim(): void;
}
function swim(animal: Cat | Fish) {
(animal as Fish).swim();
}
const tom: Cat = {
name: 'Tom',
run() { console.log('run') }
};
swim(tom);
// Uncaught TypeError: animal.swim is not a function`
```
上面的例子编译时不会报错，但在运行时会报错：
```text
Uncaught TypeError: animal.swim is not a function`
```
原因是 `(animal as Fish).swim()` 这段代码隐藏了 `animal` 可能为 `Cat` 的情况，将 `animal` 直接断言为 `Fish` 了，而 TypeScript 编译器信任了我们的断言，故在调用 `swim()` 时没有编译错误。
可是 `swim` 函数接受的参数是 `Cat | Fish`，一旦传入的参数是 `Cat` 类型的变量，由于 `Cat` 上没有 `swim` 方法，就会导致运行时错误了。
总之，使用类型断言时一定要格外小心，尽量避免断言后调用方法或引用深层属性，以减少不必要的运行时错误。
### 将一个父类断言为更加具体的子类
当类之间有继承关系时，类型断言也是很常见的：
```ts
class ApiError extends Error {
code: number = 0;
}
class HttpError extends Error {
statusCode: number = 200;
}
function isApiError(error: Error) {
if (typeof (error as ApiError).code === 'number') {
return true;
}
return false;
}
```
上面的例子中，我们声明了函数 `isApiError`，它用来判断传入的参数是不是 `ApiError` 类型，为了实现这样一个函数，它的参数的类型肯定得是比较抽象的父类 `Error`，这样的话这个函数就能接受 `Error` 或它的子类作为参数了。
但是由于父类 `Error` 中没有 `code` 属性，故直接获取 `error.code` 会报错，需要使用类型断言获取 `(error as ApiError).code`。
大家可能会注意到，在这个例子中有一个更合适的方式来判断是不是 `ApiError`，那就是使用 `instanceof`：
```ts
class ApiError extends Error {
code: number = 0;
}
class HttpError extends Error {
statusCode: number = 200;
}
function isApiError(error: Error) {
if (error instanceof ApiError) {
return true;
}
return false;
}
```
上面的例子中，确实使用 `instanceof` 更加合适，因为 `ApiError` 是一个 JavaScript 的类，能够通过 `instanceof` 来判断 `error` 是否是它的实例。
但是有的情况下 `ApiError` 和 `HttpError` 不是一个真正的类，而只是一个 TypeScript 的接口（`interface`），接口是一个类型，不是一个真正的值，它在编译结果中会被删除，当然就无法使用 `instanceof` 来做运行时判断了：
```ts
interface ApiError extends Error {
code: number;
}
interface HttpError extends Error {
statusCode: number;
}
function isApiError(error: Error) {
if (error instanceof ApiError) {
return true;
}
return false;
}
// index.ts:9:26 - error TS2693: 'ApiError' only refers to a type, but is being used as a value here.
```
此时就只能用类型断言，通过判断是否存在 `code` 属性，来判断传入的参数是不是 `ApiError` 了：
```ts
interface ApiError extends Error {
code: number;
}
interface HttpError extends Error {
statusCode: number;
}
function isApiError(error: Error) {
if (typeof (error as ApiError).code === 'number') {
return true;
}
return false;
}
```
### 将任何一个类型断言为 `any`
理想情况下，TypeScript 的类型系统运转良好，每个值的类型都具体而精确。
当我们引用一个在此类型上不存在的属性或方法时，就会报错：
```ts
const foo: number = 1;
foo.length = 1;
// index.ts:2:5 - error TS2339: Property 'length' does not exist on type 'number'.
```
上面的例子中，数字类型的变量 `foo` 上是没有 `length` 属性的，故 TypeScript 给出了相应的错误提示。
这种错误提示显然是非常有用的。
但有的时候，我们非常确定这段代码不会出错，比如下面这个例子：
```ts
window.foo = 1;
// index.ts:1:8 - error TS2339: Property 'foo' does not exist on type 'Window & typeof globalThis'.
```
上面的例子中，我们需要将 `window` 上添加一个属性 `foo`，但 TypeScript 编译时会报错，提示我们 `window` 上不存在 `foo` 属性。
此时我们可以使用 `as any` 临时将 `window` 断言为 `any` 类型：
```ts
(window as any).foo = 1;
```
在 `any` 类型的变量上，访问任何属性都是允许的。
需要注意的是，将一个变量断言为 `any` 可以说是解决 TypeScript 中类型问题的最后一个手段。
**它极有可能掩盖了真正的类型错误，所以如果不是非常确定，就不要使用 `as any`。**
上面的例子中，我们也可以通过[扩展 window 的类型（TODO）][]解决这个错误，不过如果只是临时的增加 `foo` 属性，`as any` 会更加方便。
总之，**一方面不能滥用 `as any`，另一方面也不要完全否定它的作用，我们需要在类型的严格性和开发的便利性之间掌握平衡**（这也是 [TypeScript 的设计理念][]之一），才能发挥出 TypeScript 最大的价值。
### 将 `any` 断言为一个具体的类型
在日常的开发中，我们不可避免的需要处理 `any` 类型的变量，它们可能是由于第三方库未能定义好自己的类型，也有可能是历史遗留的或其他人编写的烂代码，还可能是受到 TypeScript 类型系统的限制而无法精确定义类型的场景。
遇到 `any` 类型的变量时，我们可以选择无视它，任由它滋生更多的 `any`。
我们也可以选择改进它，通过类型断言及时的把 `any` 断言为精确的类型，亡羊补牢，使我们的代码向着高可维护性的目标发展。
举例来说，历史遗留的代码中有个 `getCacheData`，它的返回值是 `any`：
```ts
function getCacheData(key: string): any {
return (window as any).cache[key];
}
```
那么我们在使用它时，最好能够将调用了它之后的返回值断言成一个精确的类型，这样就方便了后续的操作：
```ts
function getCacheData(key: string): any {
return (window as any).cache[key];
}
interface Cat {
name: string;
run(): void;
}
const tom = getCacheData('tom') as Cat;
tom.run();
```
上面的例子中，我们调用完 `getCacheData` 之后，立即将它断言为 `Cat` 类型。这样的话明确了 `tom` 的类型，后续对 `tom` 的访问时就有了代码补全，提高了代码的可维护性。
## 类型断言的限制
> 本小节的前置知识点：[结构类型系统（TODO）][]、[类型兼容性（TODO）][]
从上面的例子中，我们可以总结出：
- 联合类型可以被断言为其中一个类型
- 父类可以被断言为子类
- 任何类型都可以被断言为 any
- any 可以被断言为任何类型
那么类型断言有没有什么限制呢？是不是任何一个类型都可以被断言为任何另一个类型呢？
答案是否定的——并不是任何一个类型都可以被断言为任何另一个类型。
具体来说，若 `A` 兼容 `B`，那么 `A` 能够被断言为 `B`，`B` 也能被断言为 `A`。
下面我们通过一个简化的例子，来理解类型断言的限制：
```ts
interface Animal {
name: string;
}
interface Cat {
name: string;
run(): void;
}
let tom: Cat = {
name: 'Tom',
run: () => { console.log('run') }
};
let animal: Animal = tom;
```
我们知道，TypeScript 是结构类型系统，类型之间的对比只会比较它们最终的结构，而会忽略它们定义时的关系。
在上面的例子中，`Cat` 包含了 `Animal` 中的所有属性，除此之外，它还有一个额外的方法 `run`。TypeScript 并不关心 `Cat` 和 `Animal` 之间定义时是什么关系，而只会看它们最终的结构有什么关系——所以它与 `Cat extends Animal` 是等价的：
```ts
interface Animal {
name: string;
}
interface Cat extends Animal {
run(): void;
}
```
那么也不难理解为什么 `Cat` 类型的 `tom` 可以赋值给 `Animal` 类型的 `animal` 了——就像面向对象编程中我们可以将子类的实例赋值给类型为父类的变量。
我们把它换成 TypeScript 中更专业的说法，即：`Animal` 兼容 `Cat`。
当 `Animal` 兼容 `Cat` 时，它们就可以互相进行类型断言了：
```ts
interface Animal {
name: string;
}
interface Cat {
name: string;
run(): void;
}
function testAnimal(animal: Animal) {
return (animal as Cat);
}
function testCat(cat: Cat) {
return (cat as Animal);
}
```
这样的设计其实也很容易就能理解：
- 允许 `animal as Cat` 是因为「父类可以被断言为子类」，这个前面已经学习过了
- 允许 `cat as Animal` 是因为既然子类拥有父类的属性和方法，那么被断言为父类，获取父类的属性、调用父类的方法，就不会有任何问题，故「子类可以被断言为父类」
需要注意的是，这里我们使用了简化的父类子类的关系来表达类型的兼容性，而实际上 TypeScript 在判断类型的兼容性时，比这种情况复杂很多，详细请参考[类型的兼容性（TODO)][]章节。
总之，若 `A` 兼容 `B`，那么 `A` 能够被断言为 `B`，`B` 也能被断言为 `A`。
同理，若 `B` 兼容 `A`，那么 `A` 能够被断言为 `B`，`B` 也能被断言为 `A`。
所以这也可以换一种说法：
要使得 `A` 能够被断言为 `B`，只需要 `A` 兼容 `B` 或 `B` 兼容 `A` 即可，这也是为了在类型断言时的安全考虑，毕竟毫无根据的断言是非常危险的。
综上所述：
- 联合类型可以被断言为其中一个类型
- 父类可以被断言为子类
- 任何类型都可以被断言为 any
- any 可以被断言为任何类型
- 要使得 `A` 能够被断言为 `B`，只需要 `A` 兼容 `B` 或 `B` 兼容 `A` 即可
其实前四种情况都是最后一个的特例。
## 双重断言
既然：
- 任何类型都可以被断言为 any
- any 可以被断言为任何类型
那么我们是不是可以使用双重断言 `as any as Foo` 来将任何一个类型断言为任何另一个类型呢？
```ts
interface Cat {
run(): void;
}
interface Fish {
swim(): void;
}
function testCat(cat: Cat) {
return (cat as any as Fish);
}
```
在上面的例子中，若直接使用 `cat as Fish` 肯定会报错，因为 `Cat` 和 `Fish` 互相都不兼容。
但是若使用双重断言，则可以打破「要使得 `A` 能够被断言为 `B`，只需要 `A` 兼容 `B` 或 `B` 兼容 `A` 即可」的限制，将任何一个类型断言为任何另一个类型。
若你使用了这种双重断言，那么十有八九是非常错误的，它很可能会导致运行时错误。
**除非迫不得已，千万别用双重断言。**
## 类型断言 vs 类型转换
类型断言只会影响 TypeScript 编译时的类型，类型断言语句在编译结果中会被删除：
```ts
function toBoolean(something: any): boolean {
return something as boolean;
}
toBoolean(1);
// 返回值为 1
```
在上面的例子中，将 `something` 断言为 `boolean` 虽然可以通过编译，但是并没有什么用，代码在编译后会变成：
```js
function toBoolean(something) {
return something;
}
toBoolean(1);
// 返回值为 1
```
所以类型断言不是类型转换，它不会真的影响到变量的类型。
若要进行类型转换，需要直接调用类型转换的方法：
```ts
function toBoolean(something: any): boolean {
return Boolean(something);
}
toBoolean(1);
// 返回值为 true
```
## 类型断言 vs 类型声明
在这个例子中：
```ts
function getCacheData(key: string): any {
return (window as any).cache[key];
}
interface Cat {
name: string;
run(): void;
}
const tom = getCacheData('tom') as Cat;
tom.run();
```
我们使用 `as Cat` 将 `any` 类型断言为了 `Cat` 类型。
但实际上还有其他方式可以解决这个问题：
```ts
function getCacheData(key: string): any {
return (window as any).cache[key];
}
interface Cat {
name: string;
run(): void;
}
const tom: Cat = getCacheData('tom');
tom.run();
```
上面的例子中，我们通过类型声明的方式，将 `tom` 声明为 `Cat`，然后再将 `any` 类型的 `getCacheData('tom')` 赋值给 `Cat` 类型的 `tom`。
这和类型断言是非常相似的，而且产生的结果也几乎是一样的——`tom` 在接下来的代码中都变成了 `Cat` 类型。
它们的区别，可以通过这个例子来理解：
```ts
interface Animal {
name: string;
}
interface Cat {
name: string;
run(): void;
}
const animal: Animal = {
name: 'tom'
};
let tom = animal as Cat;
```
在上面的例子中，由于 `Animal` 兼容 `Cat`，故可以将 `animal` 断言为 `Cat` 赋值给 `tom`。
但是若直接声明 `tom` 为 `Cat` 类型：
```ts
interface Animal {
name: string;
}
interface Cat {
name: string;
run(): void;
}
const animal: Animal = {
name: 'tom'
};
let tom: Cat = animal;
// index.ts:12:5 - error TS2741: Property 'run' is missing in type 'Animal' but required in type 'Cat'.
```
则会报错，不允许将 `animal` 赋值为 `Cat` 类型的 `tom`。
这很容易理解，`Animal` 可以看作是 `Cat` 的父类，当然不能将父类的实例赋值给类型为子类的变量。
深入的讲，它们的核心区别就在于：
- `animal` 断言为 `Cat`，只需要满足 `Animal` 兼容 `Cat` 或 `Cat` 兼容 `Animal` 即可
- `animal` 赋值给 `tom`，需要满足 `Cat` 兼容 `Animal` 才行
但是 `Cat` 并不兼容 `Animal`。
而在前一个例子中，由于 `getCacheData('tom')` 是 `any` 类型，`any` 兼容 `Cat`，`Cat` 也兼容 `any`，故
```ts
const tom = getCacheData('tom') as Cat;
```
等价于
```ts
const tom: Cat = getCacheData('tom');
```
知道了它们的核心区别，就知道了类型声明是比类型断言更加严格的。
所以为了增加代码的质量，我们最好优先使用类型声明，这也比类型断言的 `as` 语法更加优雅。
## 类型断言 vs 泛型
> 本小节的前置知识点：[泛型][]
还是这个例子：
```ts
function getCacheData(key: string): any {
return (window as any).cache[key];
}
interface Cat {
name: string;
run(): void;
}
const tom = getCacheData('tom') as Cat;
tom.run();
```
我们还有第三种方式可以解决这个问题，那就是泛型：
```ts
function getCacheData<T>(key: string): T {
return (window as any).cache[key];
}
interface Cat {
name: string;
run(): void;
}
const tom = getCacheData<Cat>('tom');
tom.run();
```
通过给 `getCacheData` 函数添加了一个泛型 `<T>`，我们可以更加规范的实现对 `getCacheData` 返回值的约束，这也同时去除掉了代码中的 `any`，是最优的一个解决方案。
## 参考
- [TypeScript Deep Dive / Type Assertion](https://basarat.gitbooks.io/typescript/content/docs/types/type-assertion.html)
- [Advanced Types # Type Guards and Differentiating Types](http://www.typescriptlang.org/docs/handbook/advanced-types.html#type-guards-and-differentiating-types)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Advanced%20Types.html#类型保护与区分类型（type-guards-and-differentiating-types）)）
- [TypeScript 的设计理念][]
[TypeScript 的设计理念]: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals
[泛型]: ../advanced/generics.md
================================================
FILE: basics/type-inference.md
================================================
# 类型推论
如果没有明确的指定类型，那么 TypeScript 会依照类型推论（Type Inference）的规则推断出一个类型。
## 什么是类型推论
以下代码虽然没有指定类型，但是会在编译的时候报错：
```ts
let myFavoriteNumber = 'seven';
myFavoriteNumber = 7;
// index.ts(2,1): error TS2322: Type 'number' is not assignable to type 'string'.
```
事实上，它等价于：
```ts
let myFavoriteNumber: string = 'seven';
myFavoriteNumber = 7;
// index.ts(2,1): error TS2322: Type 'number' is not assignable to type 'string'.
```
TypeScript 会在没有明确的指定类型的时候推测出一个类型，这就是类型推论。
**如果定义的时候没有赋值，不管之后有没有赋值，都会被推断成 `any` 类型而完全不被类型检查**：
```ts
let myFavoriteNumber;
myFavoriteNumber = 'seven';
myFavoriteNumber = 7;
```
## 参考
- [Type Inference](http://www.typescriptlang.org/docs/handbook/type-inference.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Type%20Inference.html)）
================================================
FILE: basics/type-of-array.md
================================================
# 数组的类型
在 TypeScript 中，数组类型有多种定义方式，比较灵活。
## 「类型 + 方括号」表示法
最简单的方法是使用「类型 + 方括号」来表示数组：
```ts
let fibonacci: number[] = [1, 1, 2, 3, 5];
```
数组的项中**不允许**出现其他的类型：
```ts
let fibonacci: number[] = [1, '1', 2, 3, 5];
// Type 'string' is not assignable to type 'number'.
```
数组的一些方法的参数也会根据数组在定义时约定的类型进行限制：
```ts
let fibonacci: number[] = [1, 1, 2, 3, 5];
fibonacci.push('8');
// Argument of type '"8"' is not assignable to parameter of type 'number'.
```
上例中，`push` 方法只允许传入 `number` 类型的参数，但是却传了一个 `"8"` 类型的参数，所以报错了。这里 `"8"` 是一个字符串字面量类型，会在后续章节中详细介绍。
## 数组泛型
我们也可以使用数组泛型（Array Generic） `Array<elemType>` 来表示数组：
```ts
let fibonacci: Array<number> = [1, 1, 2, 3, 5];
```
关于泛型，可以参考[泛型](../advanced/generics.md)一章。
## 用接口表示数组
接口也可以用来描述数组：
```ts
interface NumberArray {
[index: number]: number;
}
let fibonacci: NumberArray = [1, 1, 2, 3, 5];
```
`NumberArray` 表示：只要索引的类型是数字时，那么值的类型必须是数字。
虽然接口也可以用来描述数组，但是我们一般不会这么做，因为这种方式比前两种方式复杂多了。
不过有一种情况例外，那就是它常用来表示类数组。
## 类数组
类数组（Array-like Object）不是数组类型，比如 `arguments`：
```ts
function sum() {
let args: number[] = arguments;
}
// Type 'IArguments' is missing the following properties from type 'number[]': pop, push, concat, join, and 24 more.
```
上例中，`arguments` 实际上是一个类数组，不能用普通的数组的方式来描述，而应该用接口：
```ts
function sum() {
let args: {
[index: number]: number;
length: number;
callee: Function;
} = arguments;
}
```
在这个例子中，我们除了约束当索引的类型是数字时，值的类型必须是数字之外，也约束了它还有 `length` 和 `callee` 两个属性。
事实上常用的类数组都有自己的接口定义，如 `IArguments`, `NodeList`, `HTMLCollection` 等：
```ts
function sum() {
let args: IArguments = arguments;
}
```
其中 `IArguments` 是 TypeScript 中定义好了的类型，它实际上就是：
```ts
interface IArguments {
[index: number]: any;
length: number;
callee: Function;
}
```
关于内置对象，可以参考[内置对象](./built-in-objects.md)一章。
## any 在数组中的应用
一个比较常见的做法是，用 `any` 表示数组中允许出现任意类型：
```ts
let list: any[] = ['xcatliu', 25, { website: 'http://xcatliu.com' }];
```
## 参考
- [Basic Types # Array](http://www.typescriptlang.org/docs/handbook/basic-types.html#array)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Basic%20Types.html#数组)）
- [Interfaces # Indexable Types](http://www.typescriptlang.org/docs/handbook/interfaces.html#indexable-types)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Interfaces.html#数组类型)）
================================================
FILE: basics/type-of-function.md
================================================
# 函数的类型
> [函数是 JavaScript 中的一等公民](https://llh911001.gitbooks.io/mostly-adequate-guide-chinese/content/ch2.html)
## 函数声明
在 JavaScript 中，有两种常见的定义函数的方式——函数声明（Function Declaration）和函数表达式（Function Expression）：
```js
// 函数声明（Function Declaration）
function sum(x, y) {
return x + y;
}
// 函数表达式（Function Expression）
let mySum = function (x, y) {
return x + y;
};
```
一个函数有输入和输出，要在 TypeScript 中对其进行约束，需要把输入和输出都考虑到，其中函数声明的类型定义较简单：
```ts
function sum(x: number, y: number): number {
return x + y;
}
```
注意，**输入多余的（或者少于要求的）参数，是不被允许的**：
```ts
function sum(x: number, y: number): number {
return x + y;
}
sum(1, 2, 3);
// index.ts(4,1): error TS2346: Supplied parameters do not match any signature of call target.
```
```ts
function sum(x: number, y: number): number {
return x + y;
}
sum(1);
// index.ts(4,1): error TS2346: Supplied parameters do not match any signature of call target.
```
## 函数表达式
如果要我们现在写一个函数表达式（Function Expression）的定义，可能会写成这样：
```ts
let mySum = function (x: number, y: number): number {
return x + y;
};
```
这是可以通过编译的，不过事实上，上面的代码只对等号右侧的匿名函数进行了类型定义，而等号左边的 `mySum`，是通过赋值操作进行类型推论而推断出来的。如果需要我们手动给 `mySum` 添加类型，则应该是这样：
```ts
let mySum: (x: number, y: number) => number = function (x: number, y: number): number {
return x + y;
};
```
注意不要混淆了 TypeScript 中的 `=>` 和 ES6 中的 `=>`。
在 TypeScript 的类型定义中，`=>` 用来表示函数的定义，左边是输入类型，需要用括号括起来，右边是输出类型。
在 ES6 中，`=>` 叫做箭头函数，应用十分广泛，可以参考 [ES6 中的箭头函数][]。
## 用接口定义函数的形状
我们也可以使用接口的方式来定义一个函数需要符合的形状：
```ts
interface SearchFunc {
(source: string, subString: string): boolean;
}
let mySearch: SearchFunc;
mySearch = function(source: string, subString: string) {
return source.search(subString) !== -1;
}
```
采用函数表达式|接口定义函数的方式时，对等号左侧进行类型限制，可以保证以后对函数名赋值时保证参数个数、参数类型、返回值类型不变。
## 可选参数
前面提到，输入多余的（或者少于要求的）参数，是不允许的。那么如何定义可选的参数呢？
与接口中的可选属性类似，我们用 `?` 表示可选的参数：
```ts
function buildName(firstName: string, lastName?: string) {
if (lastName) {
return firstName + ' ' + lastName;
} else {
return firstName;
}
}
let tomcat = buildName('Tom', 'Cat');
let tom = buildName('Tom');
```
需要注意的是，可选参数必须接在必需参数后面。换句话说，**可选参数后面不允许再出现必需参数了**：
```ts
function buildName(firstName?: string, lastName: string) {
if (firstName) {
return firstName + ' ' + lastName;
} else {
return lastName;
}
}
let tomcat = buildName('Tom', 'Cat');
let tom = buildName(undefined, 'Tom');
// index.ts(1,40): error TS1016: A required parameter cannot follow an optional parameter.
```
## 参数默认值
在 ES6 中，我们允许给函数的参数添加默认值，**TypeScript 会将添加了默认值的参数识别为可选参数**：
```ts
function buildName(firstName: string, lastName: string = 'Cat') {
return firstName + ' ' + lastName;
}
let tomcat = buildName('Tom', 'Cat');
let tom = buildName('Tom');
```
此时就不受「可选参数必须接在必需参数后面」的限制了：
```ts
function buildName(firstName: string = 'Tom', lastName: string) {
return firstName + ' ' + lastName;
}
let tomcat = buildName('Tom', 'Cat');
let cat = buildName(undefined, 'Cat');
```
> 关于默认参数，可以参考 [ES6 中函数参数的默认值][]。
## 剩余参数
ES6 中，可以使用 `...rest` 的方式获取函数中的剩余参数（rest 参数）：
```js
function push(array, ...items) {
items.forEach(function(item) {
array.push(item);
});
}
let a: any[] = [];
push(a, 1, 2, 3);
```
事实上，`items` 是一个数组。所以我们可以用数组的类型来定义它：
```ts
function push(array: any[], ...items: any[]) {
items.forEach(function(item) {
array.push(item);
});
}
let a = [];
push(a, 1, 2, 3);
```
注意，rest 参数只能是最后一个参数，关于 rest 参数，可以参考 [ES6 中的 rest 参数][]。
## 重载
重载允许一个函数接受不同数量或类型的参数时，作出不同的处理。
比如，我们需要实现一个函数 `reverse`，输入数字 `123` 的时候，输出反转的数字 `321`，输入字符串 `'hello'` 的时候，输出反转的字符串 `'olleh'`。
利用联合类型，我们可以这么实现：
```ts
function reverse(x: number | string): number | string | void {
if (typeof x === 'number') {
return Number(x.toString().split('').reverse().join(''));
} else if (typeof x === 'string') {
return x.split('').reverse().join('');
}
}
```
**然而这样有一个缺点，就是不能够精确的表达，输入为数字的时候，输出也应该为数字，输入为字符串的时候，输出也应该为字符串。**
这时，我们可以使用重载定义多个 `reverse` 的函数类型：
```ts
function reverse(x: number): number;
function reverse(x: string): string;
function reverse(x: number | string): number | string | void {
if (typeof x === 'number') {
return Number(x.toString().split('').reverse().join(''));
} else if (typeof x === 'string') {
return x.split('').reverse().join('');
}
}
```
上例中，我们重复定义了多次函数 `reverse`，前几次都是函数定义，最后一次是函数实现。在编辑器的代码提示中，可以正确的看到前两个提示。
注意，TypeScript 会优先从最前面的函数定义开始匹配，所以多个函数定义如果有包含关系，需要优先把精确的定义写在前面。
## 参考
- [Functions](http://www.typescriptlang.org/docs/handbook/functions.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Functions.html)）
- [Functions # Function Types](http://www.typescriptlang.org/docs/handbook/interfaces.html#function-types)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Interfaces.html#函数类型)）
- [JS 函数式编程指南](https://llh911001.gitbooks.io/mostly-adequate-guide-chinese/content/)
- [ES6 中的箭头函数]
- [ES6 中函数参数的默认值]
- [ES6 中的 rest 参数]
[ES6 中的箭头函数]: http://es6.ruanyifeng.com/#docs/function#箭头函数
[ES6 中函数参数的默认值]: http://es6.ruanyifeng.com/#docs/function#函数参数的默认值
[ES6 中的 rest 参数]: http://es6.ruanyifeng.com/#docs/function#rest参数
================================================
FILE: basics/type-of-object-interfaces.md
================================================
# 对象的类型——接口
在 TypeScript 中，我们使用接口（Interfaces）来定义对象的类型。
## 什么是接口
在面向对象语言中，接口（Interfaces）是一个很重要的概念，它是对行为的抽象，而具体如何行动需要由类（classes）去实现（implement）。
TypeScript 中的接口是一个非常灵活的概念，除了可用于[对类的一部分行为进行抽象](../advanced/class-and-interfaces.md#类实现接口)以外，也常用于对「对象的形状（Shape）」进行描述。
## 简单的例子
```ts
interface Person {
name: string;
age: number;
}
let tom: Person = {
name: 'Tom',
age: 25
};
```
上面的例子中，我们定义了一个接口 `Person`，接着定义了一个变量 `tom`，它的类型是 `Person`。这样，我们就约束了 `tom` 的形状必须和接口 `Person` 一致。
接口一般首字母大写。[有的编程语言中会建议接口的名称加上 `I` 前缀](https://msdn.microsoft.com/en-us/library/8bc1fexb%28v=vs.71%29.aspx)。
定义的变量比接口少了一些属性是不允许的：
```ts
interface Person {
name: string;
age: number;
}
let tom: Person = {
name: 'Tom'
};
// index.ts(6,5): error TS2322: Type '{ name: string; }' is not assignable to type 'Person'.
// Property 'age' is missing in type '{ name: string; }'.
```
多一些属性也是不允许的：
```ts
interface Person {
name: string;
age: number;
}
let tom: Person = {
name: 'Tom',
age: 25,
gender: 'male'
};
// index.ts(9,5): error TS2322: Type '{ name: string; age: number; gender: string; }' is not assignable to type 'Person'.
// Object literal may only specify known properties, and 'gender' does not exist in type 'Person'.
```
可见，**赋值的时候，变量的形状必须和接口的形状保持一致**。
## 可选属性
有时我们希望不要完全匹配一个形状，那么可以用可选属性：
```ts
interface Person {
name: string;
age?: number;
}
let tom: Person = {
name: 'Tom'
};
```
```ts
interface Person {
name: string;
age?: number;
}
let tom: Person = {
name: 'Tom',
age: 25
};
```
可选属性的含义是该属性可以不存在。
这时**仍然不允许添加未定义的属性**：
```ts
interface Person {
name: string;
age?: number;
}
let tom: Person = {
name: 'Tom',
age: 25,
gender: 'male'
};
// examples/playground/index.ts(9,5): error TS2322: Type '{ name: string; age: number; gender: string; }' is not assignable to type 'Person'.
// Object literal may only specify known properties, and 'gender' does not exist in type 'Person'.
```
## 任意属性
有时候我们希望一个接口允许有任意的属性，可以使用如下方式：
```ts
interface Person {
name: string;
age?: number;
[propName: string]: any;
}
let tom: Person = {
name: 'Tom',
gender: 'male'
};
```
使用 `[propName: string]` 定义了任意属性取 `string` 类型的值。
需要注意的是，**一旦定义了任意属性，那么确定属性和可选属性的类型都必须是它的类型的子集**：
```ts
interface Person {
name: string;
age?: number;
[propName: string]: string;
}
let tom: Person = {
name: 'Tom',
age: 25,
gender: 'male'
};
// index.ts(3,5): error TS2411: Property 'age' of type 'number' is not assignable to string index type 'string'.
// index.ts(7,5): error TS2322: Type '{ [x: string]: string | number; name: string; age: number; gender: string; }' is not assignable to type 'Person'.
// Index signatures are incompatible.
// Type 'string | number' is not assignable to type 'string'.
// Type 'number' is not assignable to type 'string'.
```
上例中，任意属性的值允许是 `string`，但是可选属性 `age` 的值却是 `number`，`number` 不是 `string` 的子属性，所以报错了。
另外，在报错信息中可以看出，此时 `{ name: 'Tom', age: 25, gender: 'male' }` 的类型被推断成了 `{ [x: string]: string | number; name: string; age: number; gender: string; }`，这是联合类型和接口的结合。
一个接口中只能定义一个任意属性。如果接口中有多个类型的属性，则可以在任意属性中使用联合类型：
```ts
interface Person {
name: string;
age?: number;
[propName: string]: string | number;
}
let tom: Person = {
name: 'Tom',
age: 25,
gender: 'male'
};
```
## 只读属性
有时候我们希望对象中的一些字段只能在创建的时候被赋值，那么可以用 `readonly` 定义只读属性：
```ts
interface Person {
readonly id: number;
name: string;
age?: number;
[propName: string]: any;
}
let tom: Person = {
id: 89757,
name: 'Tom',
gender: 'male'
};
tom.id = 9527;
// index.ts(14,5): error TS2540: Cannot assign to 'id' because it is a constant or a read-only property.
```
上例中，使用 `readonly` 定义的属性 `id` 初始化后，又被赋值了，所以报错了。
**注意，只读的约束存在于第一次给对象赋值的时候，而不是第一次给只读属性赋值的时候**：
```ts
interface Person {
readonly id: number;
name: string;
age?: number;
[propName: string]: any;
}
let tom: Person = {
name: 'Tom',
gender: 'male'
};
tom.id = 89757;
// index.ts(8,5): error TS2322: Type '{ name: string; gender: string; }' is not assignable to type 'Person'.
// Property 'id' is missing in type '{ name: string; gender: string; }'.
// index.ts(13,5): error TS2540: Cannot assign to 'id' because it is a constant or a read-only property.
```
上例中，报错信息有两处，第一处是在对 `tom` 进行赋值的时候，没有给 `id` 赋值。
第二处是在给 `tom.id` 赋值的时候，由于它是只读属性，所以报错了。
## 参考
- [Interfaces](http://www.typescriptlang.org/docs/handbook/interfaces.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Interfaces.html)）
================================================
FILE: basics/union-types.md
================================================
# 联合类型
联合类型（Union Types）表示取值可以为多种类型中的一种。
## 简单的例子
```ts
let myFavoriteNumber: string | number;
myFavoriteNumber = 'seven';
myFavoriteNumber = 7;
```
```ts
let myFavoriteNumber: string | number;
myFavoriteNumber = true;
// index.ts(2,1): error TS2322: Type 'boolean' is not assignable to type 'string | number'.
// Type 'boolean' is not assignable to type 'number'.
```
联合类型使用 `|` 分隔每个类型。
这里的 `let myFavoriteNumber: string | number` 的含义是，允许 `myFavoriteNumber` 的类型是 `string` 或者 `number`，但是不能是其他类型。
## 访问联合类型的属性或方法
当 TypeScript 不确定一个联合类型的变量到底是哪个类型的时候，我们**只能访问此联合类型的所有类型里共有的属性或方法**：
```ts
function getLength(something: string | number): number {
return something.length;
}
// index.ts(2,22): error TS2339: Property 'length' does not exist on type 'string | number'.
// Property 'length' does not exist on type 'number'.
```
上例中，`length` 不是 `string` 和 `number` 的共有属性，所以会报错。
访问 `string` 和 `number` 的共有属性是没问题的：
```ts
function getString(something: string | number): string {
return something.toString();
}
```
联合类型的变量在被赋值的时候，会根据类型推论的规则推断出一个类型：
```ts
let myFavoriteNumber: string | number;
myFavoriteNumber = 'seven';
console.log(myFavoriteNumber.length); // 5
myFavoriteNumber = 7;
console.log(myFavoriteNumber.length); // 编译时报错
// index.ts(5,30): error TS2339: Property 'length' does not exist on type 'number'.
```
上例中，第二行的 `myFavoriteNumber` 被推断成了 `string`，访问它的 `length` 属性不会报错。
而第四行的 `myFavoriteNumber` 被推断成了 `number`，访问它的 `length` 属性时就报错了。
## 参考
- [Advanced Types # Union Types](http://www.typescriptlang.org/docs/handbook/advanced-types.html#union-types)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Advanced%20Types.html#联合类型)）
================================================
FILE: engineering/README.md
================================================
# 工程
掌握了 TypeScript 的语法就像学会了砌墙的工艺。
我们学习 TypeScript 的目的不是为了造一间小茅屋，而是为了造高楼大厦，这也正是 TypeScript 的类型系统带来的优势。
那么一项大工程应该如何开展呢？本部分的内容就会介绍 TypeScript 工程化的最佳实践，具体内容包括：
- [代码检查](lint.md)
- [编译选项](compiler-options.md)
================================================
FILE: engineering/compiler-options.md
================================================
# 编译选项
TypeScript 提供了非常多的编译选项，但是官方文档对每一项的解释很抽象，这一章会详细介绍每一个选项的作用，并给出对应的示例。
索引（点击选项跳转到详细介绍）：
选项 | 类型 | 默认值 | 描述
--- | --- | --- | ---
[`allowJs`](#allowjs) | `boolean` | `false` | 允许编译 js 文件
[`allowSyntheticDefaultImports`](#allowsyntheticdefaultimports) | `boolean` | `false` | 允许对不包含默认导出的模块使用默认导入。这个选项不会影响生成的代码，只会影响类型检查。
## allowJs
> 允许编译 js 文件。
设置为 `true` 时，js 文件会被 tsc 编译，否则不会。一般在项目中 js, ts 混合开发时需要设置。
[查看示例](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/compiler-options/01-allowJs)
```bash
# 设置为 true 时，编译后的文件包含 foo.js
├── lib
│ ├── foo.js
│ └── index.js
├── src
│ ├── foo.js
│ └── index.ts
├── package.json
└── tsconfig.json
```
```bash
# 设置为 false 时，编译后的文件不包含 foo.js
├── lib
│ └── index.js
├── src
│ ├── foo.js
│ └── index.ts
├── package.json
└── tsconfig.json
```
## allowSyntheticDefaultImports
> 允许对不包含默认导出的模块使用默认导入。这个选项不会影响生成的代码，只会影响类型检查。
`export = foo` 是 ts 为了兼容 commonjs 创造的语法，它对应于 commonjs 中的 `module.exports = foo`。
在 ts 中，如果要引入一个通过 `export = foo` 导出的模块，标准的语法是 `import foo = require('foo')`，或者 `import * as foo from 'foo'`。
但由于历史原因，我们已经习惯了使用 `import foo from 'foo'`。
这个选项就是为了解决这个问题。当它设置为 `true` 时，允许使用 `import foo from 'foo'` 来导入一个通过 `export = foo` 导出的模块。当它设置为 `false` 时，则不允许，会报错。
当然，我们一般不会在 ts 文件中使用 `export = foo` 来导出模块，而是在[写（符合 commonjs 规范的）第三方库的声明文件](../basics/declaration-files#export-1)时，才会用到 `export = foo` 来导出类型。
比如 React 的声明文件中，就是通过 `export = React` 来导出类型：
```ts
export = React;
export as namespace React;
declare namespace React {
// 声明 React 的类型
}
```
此时若我们通过 `import React from 'react'` 来导入 react 则会报错，[查看示例](https://github.com/xcatliu/typescript-tutorial/tree/master/examples/compiler-options/02-allowSyntheticDefaultImports)
：
```ts
import React from 'react';
// Module '"typescript-tutorial/examples/compiler-options/02-allowSyntheticDefaultImports/false/node_modules/@types/react/index"' can only be default-imported using the 'esModuleInterop' flagts(1259)
```
解决办法就是将 `allowSyntheticDefaultImports` 设置为 `true`。
================================================
FILE: engineering/lint.md
================================================
# 代码检查
2019 年 1 月，[TypeScirpt 官方决定全面采用 ESLint](https://www.oschina.net/news/103818/future-typescript-eslint) 作为代码检查的工具，并创建了一个新项目 [typescript-eslint][]，提供了 TypeScript 文件的解析器 [@typescript-eslint/parser](https://github.com/typescript-eslint/typescript-eslint/blob/master/packages/parser) 和相关的配置选项 [@typescript-eslint/eslint-plugin](https://github.com/typescript-eslint/typescript-eslint/blob/master/packages/eslint-plugin) 等。而之前的两个 lint 解决方案都将弃用：
- [typescript-eslint-parser](https://github.com/eslint/typescript-eslint-parser) 已停止维护
- [TSLint](https://palantir.github.io/tslint/) 将提供迁移工具，并在 typescript-eslint 的功能足够完整后停止维护 TSLint（Once we consider ESLint feature-complete w.r.t. TSLint, we will deprecate TSLint and help users migrate to ESLint<sup>[1](https://medium.com/palantir/tslint-in-2019-1a144c2317a9)</sup>）
综上所述，目前以及将来的 TypeScript 的代码检查方案就是 [typescript-eslint][]。
## 什么是代码检查
代码检查主要是用来发现代码错误、统一代码风格。
在 JavaScript 项目中，我们一般使用 [ESLint][] 来进行代码检查，它通过插件化的特性极大的丰富了适用范围，搭配 [typescript-eslint][] 之后，甚至可以用来检查 TypeScript 代码。
## 为什么需要代码检查
有人会觉得，JavaScript 非常灵活，所以需要代码检查。而 TypeScript 已经能够在编译阶段检查出很多问题了，为什么还需要代码检查呢？
因为 TypeScript 关注的重心是类型的检查，而不是代码风格。当团队的人员越来越多时，同样的逻辑不同的人写出来可能会有很大的区别：
- 缩进应该是四个空格还是两个空格？
- 是否应该禁用 `var`？
- 接口名是否应该以 `I` 开头？
- 是否应该强制使用 `===` 而不是 `==`？
这些问题 TypeScript 不会关注，但是却影响到多人协作开发时的效率、代码的可理解性以及可维护性。
下面来看一个具体的例子：
```ts
var myName = 'Tom';
console.log(`My name is ${myNane}`);
console.log(`My name is ${myName.toStrng()}`);
```
以上代码你能看出有什么错误吗？
分别用 tsc 编译和 eslint 检查后，报错信息如下：
```ts
var myName = 'Tom';
// eslint 报错信息：
// Unexpected var, use let or const instead.eslint(no-var)
console.log(`My name is ${myNane}`);
// tsc 报错信息：
// Cannot find name 'myNane'. Did you mean 'myName'?
// eslint 报错信息：
// 'myNane' is not defined.eslint(no-undef)
console.log(`My name is ${myName.toStrng()}`);
// tsc 报错信息：
// Property 'toStrng' does not exist on type 'string'. Did you mean 'toString'?
```
| 存在的问题 | `tsc` 是否报错 | `eslint` 是否报错 |
| --- | --- | --- |
| 应该使用 `let` 或 `const` 而不是 `var` | ❌ | ✅ |
| `myName` 被误写成了 `myNane` | ✅ | ✅ |
| `toString` 被误写成了 `toStrng` | ✅️ | ❌ |
上例中，我们使用了 `var` 来定义一个变量，但其实 ES6 中有更先进的语法 `let` 和 `const`，此时就可以通过 `eslint` 检查出来，提示我们应该使用 `let` 或 `const` 而不是 `var`。
对于未定义的变量 `myNane`，`tsc` 和 `eslint` 都可以检查出来。
由于 `eslint` 无法识别 `myName` 存在哪些方法，所以对于拼写错误的 `toString` 没有检查出来。
由此可见，`eslint` 能够发现出一些 `tsc` 不会关心的错误，检查出一些潜在的问题，所以代码检查还是非常重要的。
## 在 TypeScript 中使用 ESLint
### 安装 ESLint
ESLint 可以安装在当前项目中或全局环境下，因为代码检查是项目的重要组成部分，所以我们一般会将它安装在当前项目中。可以运行下面的脚本来安装：
```bash
npm install --save-dev eslint
```
由于 ESLint 默认使用 [Espree](https://github.com/eslint/espree) 进行语法解析，无法识别 TypeScript 的一些语法，故我们需要安装 [`@typescript-eslint/parser`](https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/parser)，替代掉默认的解析器，别忘了同时安装 `typescript`：
```bash
npm install --save-dev typescript @typescript-eslint/parser
```
接下来需要安装对应的插件 [@typescript-eslint/eslint-plugin](https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/eslint-plugin) 它作为 eslint 默认规则的补充，提供了一些额外的适用于 ts 语法的规则。
```bash
npm install --save-dev @typescript-eslint/eslint-plugin
```
### 创建配置文件
ESLint 需要一个配置文件来决定对哪些规则进行检查，配置文件的名称一般是 `.eslintrc.js` 或 `.eslintrc.json`。
当运行 ESLint 的时候检查一个文件的时候，它会首先尝试读取该文件的目录下的配置文件，然后再一级一级往上查找，将所找到的配置合并起来，作为当前被检查文件的配置。
我们在项目的根目录下创建一个 `.eslintrc.js`，内容如下：
```js
module.exports = {
parser: '@typescript-eslint/parser',
plugins: ['@typescript-eslint'],
rules: {
// 禁止使用 var
'no-var': "error",
// 优先使用 interface 而不是 type
'@typescript-eslint/consistent-type-definitions': [
"error",
"interface"
]
}
}
```
以上配置中，我们指定了两个规则，其中 `no-var` 是 ESLint 原生的规则，`@typescript-eslint/consistent-type-definitions` 是 `@typescript-eslint/eslint-plugin` 新增的规则。
规则的取值一般是一个数组（上例中的 `@typescript-eslint/consistent-type-definitions`），其中第一项是 `off`、`warn` 或 `error` 中的一个，表示关闭、警告和报错。后面的项都是该规则的其他配置。
如果没有其他配置的话，则可以将规则的取值简写为数组中的第一项（上例中的 `no-var`）。
关闭、警告和报错的含义如下：
- 关闭：禁用此规则
- 警告：代码检查时输出错误信息，但是不会影响到 exit code
- 报错：发现错误时，不仅会输出错误信息，而且 exit code 将被设为 1（一般 exit code 不为 0 则表示执行出现错误）
### 检查一个 ts 文件
创建了配置文件之后，我们来创建一个 ts 文件看看是否能用 ESLint 去检查它。
创建一个新文件 `index.ts`，将以下内容复制进去：
```ts
var myName = 'Tom';
type Foo = {};
```
然后执行以下命令：
```bash
./node_modules/.bin/eslint index.ts
```
则会得到如下报错信息：
```bash
/path/to/index.ts
1:1 error Unexpected var, use let or const instead no-var
3:6 error Use an `interface` instead of a `type` @typescript-eslint/consistent-type-definitions
✖ 2 problems (2 errors, 0 warnings)
2 errors and 0 warnings potentially fixable with the `--fix` option.
```
上面的结果显示，刚刚配置的两个规则都生效了：禁止使用 `var`；优先使用 `interface` 而不是 `type`。
需要注意的是，我们使用的是 `./node_modules/.bin/eslint`，而不是全局的 `eslint` 脚本，这是因为代码检查是项目的重要组成部分，所以我们一般会将它安装在当前项目中。
可是每次执行这么长一段脚本颇有不便，我们可以通过在 `package.json` 中添加一个 `script` 来创建一个 npm script 来简化这个步骤：
```json
{
"scripts": {
"eslint": "eslint index.ts"
}
}
```
这时只需执行 `npm run eslint` 即可。
### 检查整个项目的 ts 文件
我们的项目源文件一般是放在 `src` 目录下，所以需要将 `package.json` 中的 `eslint` 脚本改为对一个目录进行检查。由于 `eslint` 默认不会检查 `.ts` 后缀的文件，所以需要加上参数 `--ext .ts`：
```json
{
"scripts": {
"eslint": "eslint src --ext .ts"
}
}
```
此时执行 `npm run eslint` 即会检查 `src` 目录下的所有 `.ts` 后缀的文件。
### 在 VSCode 中集成 ESLint 检查
在编辑器中集成 ESLint 检查，可以在开发过程中就发现错误，甚至可以在保存时自动修复错误，极大的增加了开发效率。
要在 VSCode 中集成 ESLint 检查，我们需要先安装 ESLint 插件，点击「扩展」按钮，搜索 ESLint，然后安装即可。
通过配置 VSCode，可以开启保存时自动修复的功能：
```json
{
"eslint.autoFixOnSave": true,
"eslint.validate": [
"javascript",
"javascriptreact",
{
"language": "typescript",
"autoFix": true
},
],
"typescript.tsdk": "node_modules/typescript/lib"
}
```
就可以在保存文件后，自动修复为：
```ts
let myName = 'Tom';
interface Foo {}
```
### 使用 Prettier 修复格式错误
ESLint 包含了一些代码格式的检查，比如空格、分号等。但前端社区中有一个更先进的工具可以用来格式化代码，那就是 [Prettier](https://prettier.io/)。
Prettier 聚焦于代码的格式化，通过语法分析，重新整理代码的格式，让所有人的代码都保持同样的风格。
首先需要安装 Prettier：
```bash
npm install --save-dev prettier
```
然后创建一个 `prettier.config.js` 文件，里面包含 Prettier 的配置项。Prettier 的配置项很少，这里我推荐大家一个配置规则，作为参考：
```js
// prettier.config.js or .prettierrc.js
module.exports = {
// 一行最多 100 字符
printWidth: 100,
// 使用 4 个空格缩进
tabWidth: 4,
// 不使用缩进符，而使用空格
useTabs: false,
// 行尾需要有分号
semi: true,
// 使用单引号
singleQuote: true,
// 对象的 key 仅在必要时用引号
quoteProps: 'as-needed',
// jsx 不使用单引号，而使用双引号
jsxSingleQuote: false,
// 末尾不需要逗号
trailingComma: 'none',
// 大括号内的首尾需要空格
bracketSpacing: true,
// jsx 标签的反尖括号需要换行
jsxBracketSameLine: false,
// 箭头函数，只有一个参数的时候，也需要括号
arrowParens: 'always',
// 每个文件格式化的范围是文件的全部内容
rangeStart: 0,
rangeEnd: Infinity,
// 不需要写文件开头的 @prettier
requirePragma: false,
// 不需要自动在文件开头插入 @prettier
insertPragma: false,
// 使用默认的折行标准
proseWrap: 'preserve',
// 根据显示样式决定 html 要不要折行
htmlWhitespaceSensitivity: 'css',
// 换行符使用 lf
endOfLine: 'lf'
};
```
接下来安装 VSCode 中的 Prettier 插件，然后修改 `.vscode/settings.json`：
```json
{
"files.eol": "\n",
"editor.tabSize": 4,
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"eslint.autoFixOnSave": true,
"eslint.validate": [
"javascript",
"javascriptreact",
{
"language": "typescript",
"autoFix": true
}
],
"typescript.tsdk": "node_modules/typescript/lib"
}
```
这样就实现了保存文件时自动格式化并且自动修复 ESLint 错误。
需要注意的是，由于 ESLint 也可以检查一些代码格式的问题，所以在和 Prettier 配合使用时，我们一般会把 ESLint 中的代码格式相关的规则禁用掉，否则就会有冲突了。
### 使用 AlloyTeam 的 ESLint 配置
ESLint 原生的规则和 `@typescript-eslint/eslint-plugin` 的规则太多了，而且原生的规则有一些在 TypeScript 中支持的不好，需要禁用掉。
这里我推荐使用 [AlloyTeam ESLint 规则中的 TypeScript 版本](https://github.com/AlloyTeam/eslint-config-alloy#typescript)，它已经为我们提供了一套完善的配置规则，并且与 Prettier 是完全兼容的（eslint-config-alloy 不包含任何代码格式的规则，代码格式的问题交给更专业的 Prettier 去处理）。
安装：
```bash
npm install --save-dev eslint typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-config-alloy
```
在你的项目根目录下创建 `.eslintrc.js`，并将以下内容复制到文件中即可：
```js
module.exports = {
extends: [
'alloy',
'alloy/typescript',
],
env: {
// 您的环境变量（包含多个预定义的全局变量）
// Your environments (which contains several predefined global variables)
//
// browser: true,
// node: true,
// mocha: true,
// jest: true,
// jquery: true
},
globals: {
// 您的全局变量（设置为 false 表示它不允许被重新赋值）
// Your global variables (setting to false means it's not allowed to be reassigned)
//
// myGlobal: false
},
rules: {
// 自定义您的规则
// Customize your rules
}
};
```
更多的使用方法，请参考 [AlloyTeam ESLint 规则](https://github.com/AlloyTeam/eslint-config-alloy)
### 使用 ESLint 检查 tsx 文件
如果需要同时支持对 tsx 文件的检查，则需要对以上步骤做一些调整：
#### 安装 `eslint-plugin-react`
```bash
npm install --save-dev eslint-plugin-react
```
#### package.json 中的 scripts.eslint 添加 `.tsx` 后缀
```json
{
"scripts": {
"eslint": "eslint src --ext .ts,.tsx"
}
}
```
#### VSCode 的配置中新增 typescriptreact 检查
```json
{
"files.eol": "\\n",
"editor.tabSize": 4,
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"eslint.autoFixOnSave": true,
"eslint.validate": [
"javascript",
"javascriptreact",
{
"language": "typescript",
"autoFix": true
},
{
"language": "typescriptreact",
"autoFix": true
}
],
"typescript.tsdk": "node_modules/typescript/lib"
}
```
#### 使用 AlloyTeam ESLint 规则中的 TypeScript React 版本
[AlloyTeam ESLint 规则中的 TypeScript React 版本](https://github.com/AlloyTeam/eslint-config-alloy#typescript-react)
## Troubleshootings
### Cannot find module '@typescript-eslint/parser'
你运行的是全局的 eslint，需要改为运行 `./node_modules/.bin/eslint`。
### VSCode 没有显示出 ESLint 的报错
1. 检查「文件 => 首选项 => 设置」中有没有配置正确
2. 检查必要的 npm 包有没有安装
3. 检查 `.eslintrc.js` 有没有配置
4. 检查文件是不是在 `.eslintignore` 中
如果以上步骤都不奏效，则可以在「文件 => 首选项 => 设置」中配置 `"eslint.trace.server": "messages"`，按 `Ctrl`+`Shift`+`U` 打开输出面板，然后选择 ESLint 输出，查看具体错误。
### 为什么有些定义了的变量（比如使用 `enum` 定义的变量）未使用，ESLint 却没有报错？
因为无法支持这种变量定义的检查。建议在 `tsconfig.json` 中添加以下配置，使 `tsc` 编译过程能够检查出定义了未使用的变量：
```json
{
"compilerOptions": {
"noUnusedLocals": true,
"noUnusedParameters": true
}
}
```
### 启用了 noUnusedParameters 之后，只使用了第二个参数，但是又必须传入第一个参数，这就会报错了
第一个参数以下划线开头即可，参考 https://github.com/Microsoft/TypeScript/issues/9458
[ESLint]: https://eslint.org/
[typescript-eslint]: https://github.com/typescript-eslint/typescript-eslint
================================================
FILE: examples/compiler-options/01-allowJs/false/lib/index.js
================================================
"use strict";
exports.__esModule = true;
var foo_1 = require("./foo");
console.log(foo_1["default"]);
================================================
FILE: examples/compiler-options/01-allowJs/false/package.json
================================================
{
"name": "01-allow-js-false",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"start": "tsc -w",
"build": "tsc",
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "MIT",
"dependencies": {},
"devDependencies": {}
}
================================================
FILE: examples/compiler-options/01-allowJs/false/src/foo.js
================================================
const foo = 1;
export default foo;
================================================
FILE: examples/compiler-options/01-allowJs/false/src/index.ts
================================================
import foo from './foo';
console.log(foo);
================================================
FILE: examples/compiler-options/01-allowJs/false/tsconfig.json
================================================
{
"compilerOptions": {
"allowJs": false,
"outDir": "lib"
}
}
================================================
FILE: examples/compiler-options/01-allowJs/true/lib/foo.js
================================================
"use strict";
exports.__esModule = true;
var foo = 1;
exports["default"] = foo;
================================================
FILE: examples/compiler-options/01-allowJs/true/lib/index.js
================================================
"use strict";
exports.__esModule = true;
var foo_1 = require("./foo");
console.log(foo_1["default"]);
================================================
FILE: examples/compiler-options/01-allowJs/true/package.json
================================================
{
"name": "01-allow-js-true",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"start": "tsc -w",
"build": "tsc",
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "MIT",
"dependencies": {},
"devDependencies": {}
}
================================================
FILE: examples/compiler-options/01-allowJs/true/src/foo.js
================================================
const foo = 1;
export default foo;
================================================
FILE: examples/compiler-options/01-allowJs/true/src/index.ts
================================================
import foo from './foo';
console.log(foo);
================================================
FILE: examples/compiler-options/01-allowJs/true/tsconfig.json
================================================
{
"compilerOptions": {
"allowJs": true,
"outDir": "lib"
}
}
================================================
FILE: examples/compiler-options/02-allowSyntheticDefaultImports/false/package.json
================================================
{
"name": "02-allow-synthetic-default-imports-false",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"start": "tsc -w",
"build": "tsc",
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "MIT",
"dependencies": {
"react": "^16.12.0"
},
"devDependencies": {
"@types/react": "^16.9.14"
}
}
================================================
FILE: examples/compiler-options/02-allowSyntheticDefaultImports/false/src/index.ts
================================================
import React from 'react';
================================================
FILE: examples/compiler-options/02-allowSyntheticDefaultImports/false/tsconfig.json
================================================
{
"compilerOptions": {
"allowSyntheticDefaultImports": false,
"outDir": "lib"
}
}
================================================
FILE: examples/compiler-options/02-allowSyntheticDefaultImports/true/package.json
================================================
{
"name": "02-allow-synthetic-default-imports-false",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"start": "tsc -w",
"build": "tsc",
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "MIT",
"dependencies": {
"react": "^16.12.0"
},
"devDependencies": {
"@types/react": "^16.9.14"
}
}
================================================
FILE: examples/compiler-options/02-allowSyntheticDefaultImports/true/src/index.ts
================================================
import React from 'react';
================================================
FILE: examples/compiler-options/02-allowSyntheticDefaultImports/true/tsconfig.json
================================================
{
"compilerOptions": {
"allowSyntheticDefaultImports": true,
"outDir": "lib"
}
}
================================================
FILE: examples/declaration-files/01-jquery/src/index.ts
================================================
jQuery('#foo');
// ERROR: Cannot find name 'jQuery'.
================================================
FILE: examples/declaration-files/01-jquery/tsconfig.json
================================================
{}
================================================
FILE: examples/declaration-files/02-declare-var/src/index.ts
================================================
// eslint-disable-next-line no-var
declare var jQuery: (selector: string) => any;
jQuery('#foo');
================================================
FILE: examples/declaration-files/02-declare-var/tsconfig.json
================================================
{}
================================================
FILE: examples/declaration-files/03-jquery-d-ts/src/index.ts
================================================
// src/index.ts
jQuery('#foo');
================================================
FILE: examples/declaration-files/03-jquery-d-ts/src/jQuery.d.ts
================================================
// src/jQuery.d.ts
declare var jQuery: (selector: string) => any;
================================================
FILE: examples/declaration-files/03-jquery-d-ts/tsconfig.json
================================================
{
"files": ["src/index.ts", "src/jQuery.d.ts"]
}
================================================
FILE: examples/declaration-files/04-declare-const-jquery/src/index.ts
================================================
// src/index.ts
jQuery('#foo');
// 使用 declare const 定义的 jQuery 类型，禁止修改这个全局变量
jQuery = function(selector) {
return document.querySelector(selector);
};
// ERROR: Cannot assign to 'jQuery' because it is a constant or a read-only property.
================================================
FILE: examples/declaration-files/04-declare-const-jquery/src/jQuery.d.ts
================================================
// src/jQuery.d.ts
declare const jQuery: (selector: string) => any;
================================================
FILE: examples/declaration-files/04-declare-const-jquery/tsconfig.json
================================================
{}
================================================
FILE: examples/declaration-files/05-declare-jquery-value/src/jQuery.d.ts
================================================
declare const jQuery = function(selector) {
return document.querySelector(selector);
};
// ERROR: An implementation cannot be declared in ambient contexts.
================================================
FILE: examples/declaration-files/05-declare-jquery-value/tsconfig.json
================================================
{}
================================================
FILE: examples/declaration-files/06-declare-function/src/index.ts
================================================
// src/index.ts
jQuery('#foo');
jQuery(function() {
alert('Dom Ready!');
});
================================================
FILE: examples/declaration-files/06-declare-function/src/jQuery.d.ts
================================================
// src/jQuery.d.ts
declare function jQuery(selector: string): any;
declare function jQuery(domReadyCallback: () => any): any;
================================================
FILE: examples/declaration-files/06-declare-function/tsconfig.json
================================================
{}
================================================
FILE: examples/declaration-files/07-declare-class/src/Animal.d.ts
================================================
// src/Animal.d.ts
declare class Animal {
name: string;
constructor(name: string);
sayHi(): string;
}
================================================
FILE: examples/declaration-files/07-declare-class/src/index.ts
================================================
// src/index.ts
let cat = new Animal('Tom');
================================================
FILE: examples/declaration-files/07-declare-class/tsconfig.json
================================================
{}
================================================
FILE: examples/declaration-files/08-declare-enum/src/Directions.d.ts
================================================
// src/Directions.d.ts
declare enum Directions {
Up,
Down,
Left,
Right
}
================================================
FILE: examples/declaration-files/08-declare-enum/src/index.ts
================================================
// src/index.ts
let directions = [Directions.Up, Directions.Down, Directions.Left, Directions.Right];
================================================
FILE: examples/declaration-files/08-declare-enum/tsconfig.json
================================================
{}
================================================
FILE: examples/declaration-files/09-declare-namespace/src/index.ts
================================================
// src/index.ts
jQuery.ajax('/api/get_something');
console.log(jQuery.version);
const e = new jQuery.Event();
e.blur(jQuery.EventType.CustomClick);
================================================
FILE: examples/declaration-files/09-declare-namespace/src/jQuery.d.ts
================================================
// src/jQuery.d.ts
declare namespace jQuery {
function ajax(url: string, settings?: any): void;
const version: number;
class Event {
blur(eventType: EventType): void;
}
enum EventType {
CustomClick
}
}
================================================
FILE: examples/declaration-files/09-declare-namespace/tsconfig.json
================================================
{}
================================================
FILE: examples/declaration-files/10-declare-namespace-nesting/src/index.ts
================================================
// src/index.ts
jQuery.ajax('/api/get_something');
jQuery.fn.extend({
check: function() {
return this.each(function() {
this.checked = true;
});
}
});
================================================
FILE: examples/declaration-files/10-declare-namespace-nesting/src/jQuery.d.ts
================================================
// src/jQuery.d.ts
declare namespace jQuery {
function ajax(url: string, settings?: any): void;
namespace fn {
function extend(object: any): void;
}
}
================================================
FILE: examples/declaration-files/10-declare-namespace-nesting/tsconfig.json
================================================
{}
================================================
FILE: examples/declaration-files/11-declare-namespace-dot/src/index.ts
================================================
// src/index.ts
jQuery.fn.extend({
check: function() {
return this.each(function() {
this.checked = true;
});
}
});
================================================
FILE: examples/declaration-files/11-declare-namespace-dot/src/jQuery.d.ts
================================================
// src/jQuery.d.ts
declare namespace jQuery.fn {
function extend(object: any): void;
}
================================================
FILE: examples/declaration-files/11-declare-namespace-dot/tsconfig.json
================================================
{}
================================================
FILE: examples/declaration-files/12-interface/src/index.ts
================================================
// src/index.ts
let settings: AjaxSettings = {
method: 'POST',
data: {
name: 'foo'
}
};
jQuery.ajax('/api/post_something', settings);
================================================
FILE: examples/declaration-files/12-interface/src/jQuery.d.ts
================================================
// src/jQuery.d.ts
interface AjaxSettings {
method?: 'GET' | 'POST';
data?: any;
}
declare namespace jQuery {
function ajax(url: string, settings?: AjaxSettings): void;
}
================================================
FILE: examples/declaration-files/12-interface/tsconfig.json
================================================
{}
================================================
FILE: examples/declaration-files/13-avoid-name-conflict/src/index.ts
================================================
// src/index.ts
let settings: jQuery.AjaxSettings = {
method: 'POST',
data: {
name: 'foo'
}
};
jQuery.ajax('/api/post_something', settings);
================================================
FILE: examples/declaration-files/13-avoid-name-conflict/src/jQuery.d.ts
================================================
// src/jQuery.d.ts
declare namespace jQuery {
interface AjaxSettings {
method?: 'GET' | 'POST';
data?: any;
}
function ajax(url: string, settings?: AjaxSettings): void;
}
================================================
FILE: examples/declaration-files/13-avoid-name-conflict/tsconfig.json
================================================
{}
================================================
FILE: examples/declaration-files/14-declaration-merging/src/index.ts
================================================
// src/index.ts
jQuery('#foo');
jQuery.ajax('/api/get_something');
================================================
FILE: examples/declaration-files/14-declaration-merging/src/jQuery.d.ts
================================================
// src/jQuery.d.ts
declare function jQuery(selector: string): any;
declare namespace jQuery {
function ajax(url: string, settings?: any): void;
}
================================================
FILE: examples/declaration-files/14-declaration-merging/tsconfig.json
================================================
{}
================================================
FILE: examples/declaration-files/15-export/src/index.ts
================================================
// src/index.ts
import { name, getName, Animal, Directions, Options } from 'foo';
console.log(name);
let myName = getName();
let cat = new Animal('Tom');
let directions = [Directions.Up, Directions.Down, Directions.Left, Directions.Right];
let options: Options = {
data: {
name: 'foo'
}
};
================================================
FILE: examples/declaration-files/15-export/tsconfig.json
================================================
{
"compilerOptions": {
"module": "commonjs",
"baseUrl": "./",
"paths": {
"*": ["types/*"]
}
}
}
================================================
FILE: examples/declaration-files/15-export/types/foo/index.d.ts
================================================
// types/foo/index.d.ts
export const name: string;
export function getName(): string;
export class Animal {
constructor(name: string);
sayHi(): string;
}
export enum Directions {
Up,
Down,
Left,
Right
}
export interface Options {
data: any;
}
================================================
FILE: examples/declaration-files/16-declare-and-export/src/index.ts
================================================
// src/index.ts
import { name, getName, Animal, Directions, Options } from 'foo';
console.log(name);
let myName = getName();
let cat = new Animal('Tom');
let directions = [Directions.Up, Directions.Down, Directions.Left, Directions.Right];
let options: Options = {
data: {
name: 'foo'
}
};
================================================
FILE: examples/declaration-files/16-declare-and-export/tsconfig.json
================================================
{
"compilerOptions": {
"module": "commonjs",
"baseUrl": "./",
"paths": {
"*": ["types/*"]
}
}
}
================================================
FILE: examples/declaration-files/16-declare-and-export/types/foo/index.d.ts
================================================
// types/foo/index.d.ts
declare const name: string;
declare function getName(): string;
declare class Animal {
constructor(name: string);
sayHi(): string;
}
declare enum Directions {
Up,
Down,
Left,
Right
}
interface Options {
data: any;
}
export { name, getName, Animal, Directions, Options };
================================================
FILE: examples/declaration-files/17-export-namespace/src/index.ts
================================================
// src/index.ts
import { foo } from 'foo';
console.log(foo.name);
foo.bar.baz();
================================================
FILE: examples/declaration-files/17-export-namespace/tsconfig.json
================================================
{
"compilerOptions": {
"module": "commonjs",
"baseUrl": "./",
"paths": {
"*": ["types/*"]
}
}
}
================================================
FILE: examples/declaration-files/17-export-namespace/types/foo/index.d.ts
================================================
// types/foo/index.d.ts
export namespace foo {
const name: string;
namespace bar {
function baz(): string;
}
}
================================================
FILE: examples/declaration-files/18-export-default/src/index.ts
================================================
// src/index.ts
import foo from 'foo';
foo();
================================================
FILE: examples/declaration-files/18-export-default/tsconfig.json
================================================
{
"compilerOptions": {
"module": "commonjs",
"baseUrl": "./",
"paths": {
"*": ["types/*"]
}
}
}
================================================
FILE: examples/declaration-files/18-export-default/types/foo/index.d.ts
================================================
// types/foo/index.d.ts
export default function foo(): string;
================================================
FILE: examples/declaration-files/19-export-default-enum-error/src/index.ts
================================================
// src/index.ts
import foo from 'foo';
console.log(foo.Down);
================================================
FILE: examples/declaration-files/19-export-default-enum-error/tsconfig.json
================================================
{
"compilerOptions": {
"module": "commonjs",
"baseUrl": "./",
"paths": {
"*": ["types/*"]
}
}
}
================================================
FILE: examples/declaration-files/19-export-default-enum-error/types/foo/index.d.ts
================================================
// types/foo/index.d.ts
export default enum Directions {
// ERROR: Expression expected.
Up,
Down,
Left,
Right
}
================================================
FILE: examples/declaration-files/20-export-default-enum/src/index.ts
================================================
// src/index.ts
import foo from 'foo';
console.log(foo.Down);
================================================
FILE: examples/declaration-files/20-export-default-enum/tsconfig.json
================================================
{
"compilerOptions": {
"module": "commonjs",
"baseUrl": "./",
"paths": {
"*": ["types/*"]
}
}
}
================================================
FILE: examples/declaration-files/20-export-default-enum/types/foo/index.d.ts
================================================
// types/foo/index.d.ts
export default Directions;
declare enum Directions {
Up,
Down,
Left,
Right
}
================================================
FILE: examples/declaration-files/21-export-equal/src/index.ts
================================================
// 整体导入
import foo = require('foo');
// 单个导入
import bar = foo.bar;
================================================
FILE: examples/declaration-files/21-export-equal/tsconfig.json
================================================
{
"compilerOptions": {
"module": "commonjs",
"baseUrl": "./",
"paths": {
"*": ["types/*"]
}
}
}
================================================
FILE: examples/declaration-files/21-export-equal/types/foo/index.d.ts
================================================
// types/foo/index.d.ts
export = foo;
declare function foo(): string;
declare namespace foo {
const bar: number;
}
================================================
FILE: examples/declaration-files/22-export-as-namespace/src/index.ts
================================================
// src/index.ts
foo();
console.log(foo.bar);
================================================
FILE: examples/declaration-files/22-export-as-namespace/tsconfig.json
================================================
{
"compilerOptions": {
"module": "commonjs",
"baseUrl": "./",
"paths": {
"*": ["types/*"]
}
}
}
================================================
FILE: examples/declaration-files/22-export-as-namespace/types/foo/index.d.ts
================================================
// types/foo/index.d.ts
export as namespace foo;
export = foo;
declare function foo(): string;
declare namespace foo {
const bar: number;
}
================================================
FILE: examples/declaration-files/23-merge-global-interface/src/index.ts
================================================
interface String {
prependHello(): string;
}
'foo'.prependHello();
================================================
FILE: examples/declaration-files/23-merge-global-interface/tsconfig.json
================================================
{}
================================================
FILE: examples/declaration-files/24-merge-global-namespace/package.json
================================================
{
"name": "24-merge-global-namespace",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "MIT",
"dependencies": {
"jquery": "^3.5.0"
},
"devDependencies": {
"@types/jquery": "^3.3.29"
}
}
================================================
FILE: examples/declaration-files/24-merge-global-namespace/src/index.ts
================================================
// src/index.ts
jQuery.foo({
bar: ''
});
================================================
FILE: examples/declaration-files/24-merge-global-namespace/tsconfig.json
================================================
{
"compilerOptions": {
"module": "commonjs",
"baseUrl": "./",
"paths": {
"*": ["types/*"]
}
}
}
================================================
FILE: examples/declaration-files/24-merge-global-namespace/types/jquery-plugin/index.d.ts
================================================
// types/jquery-plugin/index.d.ts
declare namespace JQuery {
interface CustomOptions {
bar: string;
}
}
interface JQueryStatic {
foo(options: JQuery.CustomOptions): string;
}
================================================
FILE: examples/declaration-files/25-declare-global/src/index.ts
================================================
// src/index.ts
'foo'.prependHello();
================================================
FILE: examples/declaration-files/25-declare-global/tsconfig.json
================================================
{
"compilerOptions": {
"module": "commonjs",
"baseUrl": "./",
"paths": {
"*": ["types/*"]
}
}
}
================================================
FILE: examples/declaration-files/25-declare-global/types/foo/index.d.ts
================================================
// types/foo/index.d.ts
declare global {
interface String {
prependHello(): string;
}
}
export {};
================================================
FILE: examples/declaration-files/26-declare-module/package.json
================================================
{
"name": "26-declare-module",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "MIT",
"dependencies": {
"moment": "^2.24.0"
},
"devDependencies": {}
}
================================================
FILE: examples/declaration-files/26-declare-module/src/index.ts
================================================
// src/index.ts
import * as moment from 'moment';
import 'moment-plugin';
moment.foo();
================================================
FILE: examples/declaration-files/26-declare-module/tsconfig.json
================================================
{
"compilerOptions": {
"module": "commonjs",
"baseUrl": "./",
"paths": {
"*": ["types/*"]
}
}
}
================================================
FILE: examples/declaration-files/26-declare-module/types/moment-plugin/index.d.ts
================================================
// types/moment-plugin/index.d.ts
import * as moment from 'moment';
declare module 'moment' {
export function foo(): moment.CalendarKey;
}
================================================
FILE: examples/declaration-files/27-multiple-declare-module/src/index.ts
================================================
// src/index.ts
import { Foo } from 'foo';
import * as bar from 'bar';
let f: Foo;
bar.bar();
================================================
FILE: examples/declaration-files/27-multiple-declare-module/tsconfig.json
================================================
{
"compilerOptions": {
"module": "commonjs",
"baseUrl": "./",
"paths": {
"*": ["types/*"]
}
}
}
================================================
FILE: examples/declaration-files/27-multiple-declare-module/types/foo-bar.d.ts
================================================
// types/foo-bar.d.ts
declare module 'foo' {
export interface Foo {
foo: string;
}
}
declare module 'bar' {
export function bar(): string;
}
================================================
FILE: examples/declaration-files/28-triple-slash-directives/package.json
================================================
{
"name": "28-triple-slash-directives",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "MIT",
"dependencies": {
"jquery": "^3.5.0"
},
"devDependencies": {
"@types/jquery": "^3.3.29"
}
}
================================================
FILE: examples/declaration-files/28-triple-slash-directives/src/index.ts
================================================
// src/index.ts
foo({});
================================================
FILE: examples/declaration-files/28-triple-slash-directives/tsconfig.json
================================================
{
"compilerOptions": {
"module": "commonjs",
"baseUrl": "./",
"paths": {
"*": ["types/*"]
}
}
}
================================================
FILE: examples/declaration-files/28-triple-slash-directives/types/jquery-plugin/index.d.ts
================================================
// types/jquery-plugin/index.d.ts
/// <reference types="jquery" />
declare function foo(options: JQuery.AjaxSettings): string;
================================================
FILE: examples/declaration-files/29-triple-slash-directives-global/package.json
================================================
{
"name": "29-triple-slash-directives-global",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "MIT",
"dependencies": {},
"devDependencies": {
"@types/node": "^12.0.1"
}
}
================================================
FILE: examples/declaration-files/29-triple-slash-directives-global/src/index.ts
================================================
// src/index.ts
import { foo } from 'node-plugin';
foo(global.process);
================================================
FILE: examples/declaration-files/29-triple-slash-directives-global/tsconfig.json
================================================
{
"compilerOptions": {
"module": "commonjs",
"baseUrl": "./",
"paths": {
"*": ["types/*"]
}
}
}
================================================
FILE: examples/declaration-files/29-triple-slash-directives-global/types/node-plugin/index.d.ts
================================================
// types/node-plugin/index.d.ts
/// <reference types="node" />
export function foo(p: NodeJS.Process): string;
================================================
FILE: examples/declaration-files/30-auto-d-ts/lib/bar/index.d.ts
================================================
export declare function bar(): string;
//# sourceMappingURL=index.d.ts.map
================================================
FILE: examples/declaration-files/30-auto-d-ts/lib/bar/index.js
================================================
"use strict";
exports.__esModule = true;
function bar() {
return 'bar';
}
exports.bar = bar;
================================================
FILE: examples/declaration-files/30-auto-d-ts/lib/index.d.ts
================================================
export * from './bar';
export default function foo(): string;
//# sourceMappingURL=index.d.ts.map
================================================
FILE: examples/declaration-files/30-auto-d-ts/lib/index.js
================================================
"use strict";
function __export(m) {
for (var p in m) if (!exports.hasOwnProperty(p)) exports[p] = m[p];
}
exports.__esModule = true;
__export(require("./bar"));
function foo() {
return 'foo';
}
exports["default"] = foo;
================================================
FILE: examples/declaration-files/30-auto-d-ts/package.json
================================================
{
"name": "30-auto-d-ts",
"version": "1.0.0",
"description": "",
"main": "lib/index.js",
"scripts": {
"start": "tsc -w",
"build": "tsc",
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "MIT",
"devDependencies": {
"typescript": "^3.4.5"
}
}
================================================
FILE: examples/declaration-files/30-auto-d-ts/src/bar/index.ts
================================================
export function bar() {
return 'bar';
}
================================================
FILE: examples/declaration-files/30-auto-d-ts/src/index.ts
================================================
export * from './bar';
export default function foo() {
return 'foo';
}
================================================
FILE: examples/declaration-files/30-auto-d-ts/tsconfig.json
================================================
{
"compilerOptions": {
"module": "commonjs",
"outDir": "lib",
"declaration": true
}
}
================================================
FILE: introduction/README.md
================================================
---
prev: README.md
---
# 简介
本部分介绍了在学习 TypeScript 之前需要了解的知识，具体内容包括：
- [什么是 TypeScript](what-is-typescript.md)
- [安装 TypeScript](get-typescript.md)
- [Hello TypeScript](hello-typescript.md)
================================================
FILE: introduction/get-typescript.md
================================================
# 安装 TypeScript
TypeScript 的命令行工具安装方法如下：
```bash
npm install -g typescript
```
以上命令会在全局环境下安装 `tsc` 命令，安装完成之后，我们就可以在任何地方执行 `tsc` 命令了。
编译一个 TypeScript 文件很简单：
```bash
tsc hello.ts
```
我们约定使用 TypeScript 编写的文件以 `.ts` 为后缀，用 TypeScript 编写 React 时，以 `.tsx` 为后缀。
## 编辑器
TypeScript 最大的优势之一便是增强了编辑器和 IDE 的功能，包括代码补全、接口提示、跳转到定义、重构等。
主流的编辑器都支持 TypeScript，这里我推荐使用 [Visual Studio Code](https://code.visualstudio.com/)。
它是一款开源，跨终端的轻量级编辑器，内置了对 TypeScript 的支持。
另外它本身也是[用 TypeScript 编写的](https://github.com/Microsoft/vscode/)。
下载安装：https://code.visualstudio.com/
获取其他编辑器或 IDE 对 TypeScript 的支持：
- [Sublime Text](https://github.com/Microsoft/TypeScript-Sublime-Plugin)
- [WebStorm](https://www.jetbrains.com/webstorm/)
- [Vim](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Editor-Support#vim)
- [Emacs](https://github.com/ananthakumaran/tide)
- [Eclipse](https://github.com/palantir/eclipse-typescript)
- [Atom](https://atom.io/packages/atom-typescript)
- [Visual Studio 2019](https://marketplace.visualstudio.com/search?term=TypeScriptTeam&target=VS&category=All%20categories&vsVersion=vs2019&sortBy=UpdatedDate)
- [Visual Studio 2017](https://marketplace.visualstudio.com/search?term=TypeScriptTeam&target=VS&category=All%20categories&vsVersion=vs15&sortBy=UpdatedDate)
================================================
FILE: introduction/hello-typescript.md
================================================
# Hello TypeScript
我们从一个简单的例子开始。
将以下代码复制到 `hello.ts` 中：
```ts
function sayHello(person: string) {
return 'Hello, ' + person;
}
let user = 'Tom';
console.log(sayHello(user));
```
然后执行
```bash
tsc hello.ts
```
这时候会生成一个编译好的文件 `hello.js`：
```js
function sayHello(person) {
return 'Hello, ' + person;
}
var user = 'Tom';
console.log(sayHello(user));
```
在 TypeScript 中，我们使用 `:` 指定变量的类型，`:` 的前后有没有空格都可以。
上述例子中，我们用 `:` 指定 `person` 参数类型为 `string`。但是编译为 js 之后，并没有什么检查的代码被插入进来。
这是因为 **TypeScript 只会在编译时对类型进行静态检查，如果发现有错误，编译的时候就会报错**。而在运行时，与普通的 JavaScript 文件一样，不会对类型进行检查。
如果我们需要保证运行时的参数类型，还是得手动对类型进行判断：
```ts
function sayHello(person: string) {
if (typeof person === 'string') {
return 'Hello, ' + person;
} else {
throw new Error('person is not a string');
}
}
let user = 'Tom';
console.log(sayHello(user));
```
> `let` 是 ES6 中的关键字，和 `var` 类似，用于定义一个局部变量，可以参阅 [let 和 const 命令](http://es6.ruanyifeng.com/#docs/let)。
下面尝试把这段代码编译一下：
```ts
function sayHello(person: string) {
return 'Hello, ' + person;
}
let user = [0, 1, 2];
console.log(sayHello(user));
```
编辑器中会提示错误，编译的时候也会出错：
```bash
hello.ts:6:22 - error TS2345: Argument of type 'number[]' is not assignable to parameter of type 'string'.
```
但是还是生成了 js 文件：
```js
function sayHello(person) {
return 'Hello, ' + person;
}
var user = [0, 1, 2];
console.log(sayHello(user));
```
这是因为 **TypeScript 编译的时候即使报错了，还是会生成编译结果**，我们仍然可以使用这个编译之后的文件。
如果要在报错的时候终止 js 文件的生成，可以在 `tsconfig.json` 中配置 `noEmitOnError` 即可。关于 `tsconfig.json`，请参阅[官方手册](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/tsconfig.json.html)）。
================================================
FILE: introduction/what-is-typescript.md
================================================
# 什么是 TypeScript
> Typed JavaScript at Any Scale.
> 添加了类型系统的 JavaScript，适用于任何规模的项目。
以上描述是官网<sup>[[1]](#link-1)</sup>对于 TypeScript 的定义。
它强调了 TypeScript 的两个最重要的特性——类型系统、适用于任何规模。
## TypeScript 的特性
### 类型系统
从 TypeScript 的名字就可以看出来，「类型」是其最核心的特性。
我们知道，JavaScript 是一门非常灵活的编程语言：
- 它没有类型约束，一个变量可能初始化时是字符串，过一会儿又被赋值为数字。
- 由于隐式类型转换的存在，有的变量的类型很难在运行前就确定。
- 基于原型的面向对象编程，使得原型上的属性或方法可以在运行时被修改。
- 函数是 JavaScript 中的一等公民<sup>[[2]](#link-2)</sup>，可以赋值给变量，也可以当作参数或返回值。
这种灵活性就像一把双刃剑，一方面使得 JavaScript 蓬勃发展，无所不能，从 2013 年开始就一直蝉联最普遍使用的编程语言排行榜冠军<sup>[[3]](#link-3)</sup>；另一方面也使得它的代码质量参差不齐，维护成本高，运行时错误多。
而 TypeScript 的类型系统，在很大程度上弥补了 JavaScript 的缺点。
#### TypeScript 是静态类型
类型系统按照「类型检查的时机」来分类，可以分为动态类型和静态类型。
动态类型是指在运行时才会进行类型检查，这种语言的类型错误往往会导致运行时错误。JavaScript 是一门解释型语言<sup>[[4]](#link-4)</sup>，没有编译阶段，所以它是动态类型，以下这段代码在运行时才会报错：
```js
let foo = 1;
foo.split(' ');
// Uncaught TypeError: foo.split is not a function
// 运行时会报错（foo.split 不是一个函数），造成线上 bug
```
静态类型是指编译阶段就能确定每个变量的类型，这种语言的类型错误往往会导致语法错误。TypeScript 在运行前需要先编译为 JavaScript，而在编译阶段就会进行类型检查，所以 **TypeScript 是静态类型**，这段 TypeScript 代码在编译阶段就会报错了：
```ts
let foo = 1;
foo.split(' ');
// Property 'split' does not exist on type 'number'.
// 编译时会报错（数字没有 split 方法），无法通过编译
```
你可能会奇怪，这段 TypeScript 代码看上去和 JavaScript 没有什么区别呀。
没错！大部分 JavaScript 代码都只需要经过少量的修改（或者完全不用修改）就变成 TypeScript 代码，这得益于 TypeScript 强大的[类型推论][]，即使不去手动声明变量 `foo` 的类型，也能在变量初始化时自动推论出它是一个 `number` 类型。
完整的 TypeScript 代码是这样的：
```ts
let foo: number = 1;
foo.split(' ');
// Property 'split' does not exist on type 'number'.
// 编译时会报错（数字没有 split 方法），无法通过编译
```
#### TypeScript 是弱类型
类型系统按照「是否允许隐式类型转换」来分类，可以分为强类型和弱类型。
以下这段代码不管是在 JavaScript 中还是在 TypeScript 中都是可以正常运行的，运行时数字 `1` 会被隐式类型转换为字符串 `'1'`，加号 `+` 被识别为字符串拼接，所以打印出结果是字符串 `'11'`。
```js
console.log(1 + '1');
// 打印出字符串 '11'
```
TypeScript 是完全兼容 JavaScript 的，它不会修改 JavaScript 运行时的特性，所以**它们都是弱类型**。
作为对比，Python 是强类型，以下代码会在运行时报错：
```py
print(1 + '1')
# TypeError: unsupported operand type(s) for +: 'int' and 'str'
```
若要修复该错误，需要进行强制类型转换：
```py
print(str(1) + '1')
# 打印出字符串 '11'
```
> 强/弱是相对的，Python 在处理整型和浮点型相加时，会将整型隐式转换为浮点型，但是这并不影响 Python 是强类型的结论，因为大部分情况下 Python 并不会进行隐式类型转换。相比而言，JavaScript 和 TypeScript 中不管加号两侧是什么类型，都可以通过隐式类型转换计算出一个结果——而不是报错——所以 JavaScript 和 TypeScript 都是弱类型。
> 虽然 TypeScript 不限制加号两侧的类型，但是我们可以借助 TypeScript 提供的类型系统，以及 ESLint 提供的代码检查功能，来限制加号两侧必须同为数字或同为字符串<sup>[[5]](#link-5)</sup>。这在一定程度上使得 TypeScript 向「强类型」更近一步了——当然，这种限制是可选的。
这样的类型系统体现了 TypeScript 的核心设计理念<sup>[[6]](#link-6)</sup>：在完整保留 JavaScript 运行时行为的基础上，通过引入静态类型系统来提高代码的可维护性，减少可能出现的 bug。
### 适用于任何规模
TypeScript 非常适用于大型项目——这是显而易见的，类型系统可以为大型项目带来更高的可维护性，以及更少的 bug。
在中小型项目中推行 TypeScript 的最大障碍就是认为使用 TypeScript 需要写额外的代码，降低开发效率。但事实上，由于有[类型推论][]，大部分类型都不需要手动声明了。相反，TypeScript 增强了编辑器（IDE）的功能，包括代码补全、接口提示、跳转到定义、代码重构等，这在很大程度上提高了开发效率。而且 TypeScript 有近百个[编译选项][]，如果你认为类型检查过于严格，那么可以通过修改编译选项来降低类型检查的标准。
TypeScript 还可以和 JavaScript 共存。这意味着如果你有一个使用 JavaScript 开发的旧项目，又想使用 TypeScript 的特性，那么你不需要急着把整个项目都迁移到 TypeScript，你可以使用 TypeScript 编写新文件，然后在后续更迭中逐步迁移旧文件。如果一些 JavaScript 文件的迁移成本太高，TypeScript 也提供了一个方案，可以让你在不修改 JavaScript 文件的前提下，编写一个[类型声明文件][]，实现旧项目的渐进式迁移。
事实上，就算你从来没学习过 TypeScript，你也可能已经在不知不觉中使用到了 TypeScript——在 VSCode 编辑器中编写 JavaScript 时，代码补全和接口提示等功能就是通过 TypeScript Language Service 实现的<sup>[[7]](#link-7)</sup>：
一些第三方库原生支持了 TypeScript，在使用时就能获得代码补全了，比如 Vue 3.0<sup>[[8]](#link-8)</sup>：
有一些第三方库原生不支持 TypeScript，但是可以通过安装社区维护的类型声明库<sup>[[9]](#link-9)</sup>（比如通过运行 `npm install --save-dev @types/react` 来安装 React 的类型声明库）来获得代码补全能力——不管是在 JavaScript 项目中还是在 TypeScript 中项目中都是支持的：
由此可见，TypeScript 的发展已经深入到前端社区的方方面面了，任何规模的项目都或多或少得到了 TypeScript 的支持。
### 与标准同步发展
TypeScript 的另一个重要的特性就是坚持与 ECMAScript 标准<sup>[[10]](#link-10)</sup>同步发展。
ECMAScript 是 JavaScript 核心语法的标准，自 2015 年起，每年都会发布一个新版本，包含一些新的语法。
一个新的语法从提案到变成正式标准，需要经历以下几个阶段：
- Stage 0：展示阶段，仅仅是提出了讨论、想法，尚未正式提案。
- Stage 1：征求意见阶段，提供抽象的 API 描述，讨论可行性，关键算法等。
- Stage 2：草案阶段，使用正式的规范语言精确描述其语法和语义。
- Stage 3：候选人阶段，语法的设计工作已完成，需要浏览器、Node.js 等环境支持，搜集用户的反馈。
- Stage 4：定案阶段，已准备好将其添加到正式的 ECMAScript 标准中。
一个语法进入到 Stage 3 阶段后，TypeScript 就会实现它。一方面，让我们可以尽早的使用到最新的语法，帮助它进入到下一个阶段；另一方面，处于 Stage 3 阶段的语法已经比较稳定了，基本不会有语法的变更，这使得我们能够放心的使用它。
除了实现 ECMAScript 标准之外，TypeScript 团队也推进了诸多语法提案，比如可选链操作符（`?.`）<sup>[[11]](#link-11)</sup>、空值合并操作符（`??`）<sup>[[12]](#link-12)</sup>、Throw 表达式<sup>[[13]](#link-13)</sup>、正则匹配索引<sup>[[14]](#link-14)</sup>等。
## 总结
什么是 TypeScript？
- TypeScript 是添加了类型系统的 JavaScript，适用于任何规模的项目。
- TypeScript 是一门静态类型、弱类型的语言。
- TypeScript 是完全兼容 JavaScript 的，它不会修改 JavaScript 运行时的特性。
- TypeScript 可以编译为 JavaScript，然后运行在浏览器、Node.js 等任何能运行 JavaScript 的环境中。
- TypeScript 拥有很多编译选项，类型检查的严格程度由你决定。
- TypeScript 可以和 JavaScript 共存，这意味着 JavaScript 项目能够渐进式的迁移到 TypeScript。
- TypeScript 增强了编辑器（IDE）的功能，提供了代码补全、接口提示、跳转到定义、代码重构等能力。
- TypeScript 拥有活跃的社区，大多数常用的第三方库都提供了类型声明。
- TypeScript 与标准同步发展，符合最新的 ECMAScript 标准（stage 3）。
## 附：TypeScript 的发展历史
- 2012-10：微软发布了 TypeScript 第一个版本（0.8），此前已经在微软内部开发了两年。
- 2014-04：TypeScript 发布了 1.0 版本。
- 2014-10：Angular 发布了 2.0 版本，它是一个基于 TypeScript 开发的前端框架。
- 2015-01：ts-loader 发布，webpack 可以编译 TypeScript 文件了。
- 2015-04：微软发布了 Visual Studio Code，它内置了对 TypeScript 语言的支持，它自身也是用 TypeScript 开发的。
- 2016-05：`@types/react` 发布，TypeScript 可以开发 React 应用了。
- 2016-05：`@types/node` 发布，TypeScript 可以开发 Node.js 应用了。
- 2016-09：TypeScript 发布了 2.0 版本。
- 2018-06：TypeScript 发布了 3.0 版本。
- 2019-02：TypeScript 宣布由官方团队来维护 typescript-eslint，以支持在 TypeScript 文件中运行 ESLint 检查。
- 2020-05：Deno 发布了 1.0 版本，它是一个 JavaScript 和 TypeScript 运行时。
- 2020-08：TypeScript 发布了 4.0 版本。
- 2020-09：Vue 发布了 3.0 版本，官方支持 TypeScript。
## 参考资料
1. <span id="link-1">[TypeScript 官网](https://www.typescriptlang.org/)</span>
2. <span id="link-2">[第 2 章: 一等公民的函数](https://llh911001.gitbooks.io/mostly-adequate-guide-chinese/content/ch2.html) · 函数式编程指北</span>
3. <span id="link-3">[StackOverflow 2020 开发者调查报告](https://insights.stackoverflow.com/survey/2020)</span>
4. <span id="link-4">[斯坦福 JavaScript 第一课](https://web.stanford.edu/class/cs98si/slides/overview.html)</span>
5. <span id="link-5">[TypeScript ESLint 规则 `restrict-plus-operands`](https://github.com/typescript-eslint/typescript-eslint/blob/master/packages/eslint-plugin/docs/rules/restrict-plus-operands.md)</span>
6. <span id="link-6">[TypeScript 设计理念](https://github.com/microsoft/TypeScript/wiki/TypeScript-Design-Goals)</span>
7. <span id="link-7">[Visual Studio Code 中集成了 TypeScript](https://code.visualstudio.com/docs/languages/typescript)</span>
8. <span id="link-8">[Vue 3.0 支持 TypeScript](https://v3.vuejs.org/guide/typescript-support.html)</span>
9. <span id="link-9">[Definitely Typed](https://github.com/DefinitelyTyped/DefinitelyTyped)——TypeScript 团队帮助维护的类型定义仓库</span>
10. <span id="link-10">[ECMAScript 标准](https://tc39.es/process-document/)</span>
11. <span id="link-11">[可选链操作符（`?.`）](https://github.com/tc39/proposal-optional-chaining)</span>
12. <span id="link-12">[空值合并操作符（`??`）](https://github.com/tc39/proposal-nullish-coalescing)</span>
13. <span id="link-13">[Throw 表达式](https://github.com/tc39/proposal-throw-expressions)</span>
14. <span id="link-14">[正则匹配索引](https://github.com/tc39/proposal-regexp-match-indices)</span>
================================================
FILE: introduction/why-typescript.md
================================================
你可能或多或少听说过这样的言论：
- TypeScript 只适用于大公司的大型项目
- TypeScript 适合多人协作开发，一个人维护的项目就没必要使用了
- TypeScript 学习成本高，开发成本高
- 旧项目是 JavaScript，所以没必要改造成 TypeScript 了
我想说，都 2021 年了，赶紧上车吧，绝大部分项目都应该使用 TypeScript！
大型项目不必多说，TypeScript 的类型系统能够集成到 IDE（或编辑器）中，通过代码补全、代码提示、跳转到定义等功能，极大的提高代码的可维护性，提高开发效率，降低 bug 率。
> 动态类型一时爽，代码重构火葬场。
如果你没有学过 TypeScript，那么可能连这样的接口提示都看不懂了：
## 为什么选择 TypeScript
[TypeScript 官网][TypeScript]列举了一些优势，不过我更愿意自己总结一下：
### TypeScript 增加了代码的可读性和可维护性
- 类型系统实际上是最好的文档，大部分的函数看看类型的定义就可以知道如何使用了
- 可以在编译阶段就发现大部分错误，这总比在运行时候出错好
- 增强了编辑器和 IDE 的功能，包括代码补全、接口提示、跳转到定义、代码重构等
### TypeScript 非常包容
- TypeScript 是 JavaScript 的超集，`.js` 文件可以直接重命名为 `.ts` 即可
- 即使不显式的定义类型，也能够自动做出[类型推论](../basics/type-inference.md)
- TypeScript 的类型系统是图灵完备的，可以定义从简单到复杂的几乎一切类型
- 即使 TypeScript 编译报错，也可以生成 JavaScript 文件
- 兼容第三方库，即使第三方库不是用 TypeScript 写的，也可以编写单独的类型文件供 TypeScript 读取
### TypeScript 拥有活跃的社区
- 大部分第三方库都有提供给 TypeScript 的类型定义文件
- Angular、Vue、VS Code、Ant Design 等等耳熟能详的项目都是使用 TypeScript 编写的
- TypeScript 拥抱了 ES6 规范，支持 ESNext 草案中处于第三阶状态（Stage 3）的特性
### TypeScript 的缺点
任何事物都是有两面性的，我认为 TypeScript 的弊端在于：
- 有一定的学习成本，需要理解接口（Interfaces）、泛型（Generics）、类（Classes）、枚举类型（Enums）等前端工程师可能不是很熟悉的概念
- 短期可能会增加一些开发成本，毕竟要多写一些类型的定义，不过对于一个需要长期维护的项目，TypeScript 能够减少其维护成本
- 集成到构建流程需要一些工作量
- 可能和一些库结合的不是很完美
大家可以根据自己团队和项目的情况判断是否需要使用 TypeScript。
StackOverflow 2020 开发者调查报告，TypeScript 击败 Python
================================================
FILE: package.json
================================================
{
"name": "typescript-tutorial",
"version": "0.1.0",
"description": "从 JavaScript 程序员的角度总结思考，循序渐进的理解 TypeScript",
"main": "README.md",
"scripts": {
"start": "deno run --unstable --allow-read --allow-write --allow-net --allow-run ../pagic/mod.ts build --serve --watch",
"build": "deno run --unstable --allow-read --allow-write --allow-net --allow-run ../pagic/mod.ts build",
"test": "npm run lint",
"pandoc": "pandoc -o TypeScript\\ 入门教程.epub --resource-path assets pandoc-metadata.txt $(cat pandoc-list.txt)",
"lint": "run-s eclint prettier lint-md eslint",
"lint:fix": "run-s eclint:fix prettier:fix lint-md:fix",
"eclint": "bash -c 'eclint check $(git ls-files -- . \":!:*.epub\")'",
"eclint:fix": "bash -c 'eclint fix $(git ls-files -- . \":!:*.epub\")'",
"prettier": "prettier -l \"./**/*\"",
"prettier:fix": "prettier --write -l \"./**/*\"",
"lint-md": "lint-md .",
"lint-md:fix": "lint-md --fix .",
"eslint": "eslint --ext .ts examples",
"eslint:fix": "eslint --ext .ts --fix examples"
},
"husky": {
"hooks": {
"pre-commit": "npm test",
"pre-push": "npm test"
}
},
"repository": {
"type": "git",
"url": "git+https://github.com/xcatliu/typescript-tutorial.git"
},
"keywords": [
"typescript",
"tutorial",
"javascript"
],
"author": "xcatliu <xcatliu@gmail.com>",
"license": "MIT",
"bugs": {
"url": "https://github.com/xcatliu/typescript-tutorial/issues"
},
"homepage": "https://github.com/xcatliu/typescript-tutorial#readme",
"devDependencies": {
"@typescript-eslint/eslint-plugin": "^5.59.9",
"@typescript-eslint/parser": "^5.59.9",
"eclint": "^2.8.1",
"eslint": "^8.42.0",
"eslint-config-alloy": "^5.0.0",
"eslint-plugin-react": "^7.32.2",
"husky": "^8.0.3",
"lint-md-cli": "^0.1.2",
"npm-run-all": "^4.1.5",
"prettier": "^2.8.8",
"typescript": "^5.1.3"
}
}
================================================
FILE: pagic.config.tsx
================================================
import { React } from 'https://deno.land/x/pagic@v1.6.3/mod.ts';
export default {
srcDir: '.',
exclude: ['examples'],
theme: 'docs',
plugins: ['sidebar', 'prev_next', 'gitalk', 'ga'],
title: 'TypeScript 入门教程',
description: '从 JavaScript 程序员的角度总结思考，循序渐进的理解 TypeScript',
github: 'https://github.com/xcatliu/typescript-tutorial',
head: <link rel="icon" type="image/png" href="/favicon.png" />,
nav: [
{
text: '赞助作者',
link: 'https://github.com/xcatliu/buy-me-a-coffee',
target: '_blank',
popover: (
<>
<img src="/assets/wechat.jpg" width="256" style={{ marginRight: '1rem', verticalAlign: 'top' }} />
<img src="/assets/alipay.jpg" width="256" style={{ verticalAlign: 'top' }} />
</>
),
},
{
text: '加入微信群',
popover: (
<>
<p style={{ marginTop: 0, marginBottom: '1rem', width: 256 }}>一群已满，请扫码加二群</p>
<img src="/assets/join-wechat.jpg" width="256" />
</>
),
},
{
text: '加入 QQ 群',
link: 'https://jq.qq.com/?_wv=1027&k=5nkkFCl',
target: '_blank',
popover: (
<>
<p style={{ marginTop: 0, marginBottom: '1rem', width: 256 }}>
一群（767142358）已满，请扫码加二群（706191218）
</p>
<img src="/assets/join-qq.jpg" width="256" />
</>
),
},
{
text: '本网站使用 Pagic 构建',
link: 'https://github.com/xcatliu/pagic',
target: '_blank',
},
],
sidebar: {
'/': [
{
link: 'introduction/README.md',
children: [
'introduction/what-is-typescript.md',
'introduction/get-typescript.md',
'introduction/hello-typescript.md',
],
},
{
link: 'basics/README.md',
children: [
'basics/primitive-data-types.md',
'basics/any.md',
'basics/type-inference.md',
'basics/union-types.md',
'basics/type-of-object-interfaces.md',
'basics/type-of-array.md',
'basics/type-of-function.md',
'basics/type-assertion.md',
'basics/declaration-files.md',
'basics/built-in-objects.md',
],
},
{
link: 'advanced/README.md',
children: [
'advanced/type-aliases.md',
'advanced/string-literal-types.md',
'advanced/tuple.md',
'advanced/enum.md',
'advanced/class.md',
'advanced/class-and-interfaces.md',
'advanced/generics.md',
'advanced/declaration-merging.md',
'advanced/decorator.md',
'advanced/further-reading.md',
],
},
{
link: 'engineering/README.md',
children: ['engineering/lint.md', 'engineering/compiler-options.md'],
},
'thanks/README.md',
],
},
tools: {
editOnGitHub: true,
backToTop: true,
},
// tocAd: (
// <div
// dangerouslySetInnerHTML={{
// __html: `
// <script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>
// <!-- 192*128 -->
// <ins
// class="adsbygoogle"
// style="display:inline-block;width:192px;height:128px"
// data-ad-client="ca-pub-8483371329009107"
// data-ad-slot="6487368873"
// ></ins>
// <script>
// (adsbygoogle = window.adsbygoogle || []).push({});
// </script>`
// }}
// />
// ),
gitalk: {
clientID: '29aa4941759fc887ed4f',
clientSecret: '33e355efdf3a1959624506a5d88311145208471b',
repo: 'typescript-tutorial',
owner: 'xcatliu',
admin: ['xcatliu'],
pagerDirection: 'first',
},
ga: {
id: 'UA-45256157-14',
},
port: 8001,
};
================================================
FILE: pandoc-list.txt
================================================
README.md
introduction/README.md
introduction/what-is-typescript.md
introduction/get-typescript.md
introduction/hello-typescript.md
basics/README.md
basics/primitive-data-types.md
basics/any.md
basics/type-inference.md
basics/union-types.md
basics/type-of-object-interfaces.md
basics/type-of-array.md
basics/type-of-function.md
basics/type-assertion.md
basics/declaration-files.md
basics/built-in-objects.md
advanced/README.md
advanced/type-aliases.md
advanced/string-literal-types.md
advanced/tuple.md
advanced/enum.md
advanced/class.md
advanced/class-and-interfaces.md
advanced/generics.md
advanced/declaration-merging.md
advanced/further-reading.md
engineering/README.md
engineering/lint.md
engineering/compiler-options.md
thanks/README.md
================================================
FILE: pandoc-metadata.txt
================================================
---
title: TypeScript 入门教程
author: xcatliu
description: 从 JavaScript 程序员的角度总结思考，循序渐进的理解 TypeScript
language: zh-CN
cover-image: pandoc-cover.jpg
...
================================================
FILE: thanks/README.md
================================================
# 感谢
- 感谢[创造和维护 TypeScript 的人们](https://github.com/Microsoft/TypeScript/graphs/contributors)，给我们带来了如此优秀的工具
- 感谢 [@zhongsp](https://github.com/zhongsp/) 对[官方手册的翻译](https://zhongsp.gitbooks.io/typescript-handbook/content/index.html)，本书参考了大量他的翻译，能一直坚持跟进非常不容易
- 感谢 [@阮一峰](http://www.ruanyifeng.com/home.html) 老师的 [ECMAScript 6 入门](http://es6.ruanyifeng.com/)，本书引用了多处 ES6 的知识
最后，感谢你阅读完本书，希望你会有所收获。
## 下一步
- 在 [GitHub](https://github.com/xcatliu/typescript-tutorial) 上关注本书
- 阅读[官方手册](http://www.typescriptlang.org/docs/handbook/basic-types.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/)）巩固知识
- 阅读 [Project Configuration](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html)（[中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/tsconfig.json.html)） 学习如何配置 TypeScript 工程
- 查看[官方示例](http://www.typescriptlang.org/samples/index.html)，学习真实项目
gitextract_f_xb4944/
├── .editorconfig
├── .eslintignore
├── .eslintrc.js
├── .github/
│ ├── FUNDING.yml
│ └── workflows/
│ └── gh-pages.yml
├── .gitignore
├── .lintmdrc
├── .npmrc
├── .prettierignore
├── .prettierrc.js
├── .vscode/
│ └── settings.json
├── README.md
├── TypeScript 入门教程 2020.epub
├── TypeScript 入门教程.epub
├── advanced/
│ ├── README.md
│ ├── class-and-interfaces.md
│ ├── class.md
│ ├── declaration-merging.md
│ ├── decorator.md
│ ├── enum.md
│ ├── further-reading.md
│ ├── generics.md
│ ├── string-literal-types.md
│ ├── tuple.md
│ └── type-aliases.md
├── basics/
│ ├── README.md
│ ├── any.md
│ ├── built-in-objects.md
│ ├── declaration-files.md
│ ├── primitive-data-types.md
│ ├── type-assertion.md
│ ├── type-inference.md
│ ├── type-of-array.md
│ ├── type-of-function.md
│ ├── type-of-object-interfaces.md
│ └── union-types.md
├── engineering/
│ ├── README.md
│ ├── compiler-options.md
│ └── lint.md
├── examples/
│ ├── compiler-options/
│ │ ├── 01-allowJs/
│ │ │ ├── false/
│ │ │ │ ├── lib/
│ │ │ │ │ └── index.js
│ │ │ │ ├── package.json
│ │ │ │ ├── src/
│ │ │ │ │ ├── foo.js
│ │ │ │ │ └── index.ts
│ │ │ │ └── tsconfig.json
│ │ │ └── true/
│ │ │ ├── lib/
│ │ │ │ ├── foo.js
│ │ │ │ └── index.js
│ │ │ ├── package.json
│ │ │ ├── src/
│ │ │ │ ├── foo.js
│ │ │ │ └── index.ts
│ │ │ └── tsconfig.json
│ │ └── 02-allowSyntheticDefaultImports/
│ │ ├── false/
│ │ │ ├── package.json
│ │ │ ├── src/
│ │ │ │ └── index.ts
│ │ │ └── tsconfig.json
│ │ └── true/
│ │ ├── package.json
│ │ ├── src/
│ │ │ └── index.ts
│ │ └── tsconfig.json
│ └── declaration-files/
│ ├── 01-jquery/
│ │ ├── src/
│ │ │ └── index.ts
│ │ └── tsconfig.json
│ ├── 02-declare-var/
│ │ ├── src/
│ │ │ └── index.ts
│ │ └── tsconfig.json
│ ├── 03-jquery-d-ts/
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 04-declare-const-jquery/
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 05-declare-jquery-value/
│ │ ├── src/
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 06-declare-function/
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 07-declare-class/
│ │ ├── src/
│ │ │ ├── Animal.d.ts
│ │ │ └── index.ts
│ │ └── tsconfig.json
│ ├── 08-declare-enum/
│ │ ├── src/
│ │ │ ├── Directions.d.ts
│ │ │ └── index.ts
│ │ └── tsconfig.json
│ ├── 09-declare-namespace/
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 10-declare-namespace-nesting/
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 11-declare-namespace-dot/
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 12-interface/
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 13-avoid-name-conflict/
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 14-declaration-merging/
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ └── jQuery.d.ts
│ │ └── tsconfig.json
│ ├── 15-export/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo/
│ │ └── index.d.ts
│ ├── 16-declare-and-export/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo/
│ │ └── index.d.ts
│ ├── 17-export-namespace/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo/
│ │ └── index.d.ts
│ ├── 18-export-default/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo/
│ │ └── index.d.ts
│ ├── 19-export-default-enum-error/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo/
│ │ └── index.d.ts
│ ├── 20-export-default-enum/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo/
│ │ └── index.d.ts
│ ├── 21-export-equal/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo/
│ │ └── index.d.ts
│ ├── 22-export-as-namespace/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo/
│ │ └── index.d.ts
│ ├── 23-merge-global-interface/
│ │ ├── src/
│ │ │ └── index.ts
│ │ └── tsconfig.json
│ ├── 24-merge-global-namespace/
│ │ ├── package.json
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── jquery-plugin/
│ │ └── index.d.ts
│ ├── 25-declare-global/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo/
│ │ └── index.d.ts
│ ├── 26-declare-module/
│ │ ├── package.json
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── moment-plugin/
│ │ └── index.d.ts
│ ├── 27-multiple-declare-module/
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── foo-bar.d.ts
│ ├── 28-triple-slash-directives/
│ │ ├── package.json
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── jquery-plugin/
│ │ └── index.d.ts
│ ├── 29-triple-slash-directives-global/
│ │ ├── package.json
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── tsconfig.json
│ │ └── types/
│ │ └── node-plugin/
│ │ └── index.d.ts
│ └── 30-auto-d-ts/
│ ├── lib/
│ │ ├── bar/
│ │ │ ├── index.d.ts
│ │ │ └── index.js
│ │ ├── index.d.ts
│ │ └── index.js
│ ├── package.json
│ ├── src/
│ │ ├── bar/
│ │ │ └── index.ts
│ │ └── index.ts
│ └── tsconfig.json
├── introduction/
│ ├── README.md
│ ├── get-typescript.md
│ ├── hello-typescript.md
│ ├── what-is-typescript.md
│ └── why-typescript.md
├── package.json
├── pagic.config.tsx
├── pandoc-list.txt
├── pandoc-metadata.txt
└── thanks/
└── README.md
SYMBOL INDEX (24 symbols across 17 files)
FILE: examples/declaration-files/07-declare-class/src/Animal.d.ts
class Animal (line 3) | class Animal {
FILE: examples/declaration-files/08-declare-enum/src/Directions.d.ts
type Directions (line 3) | enum Directions {
FILE: examples/declaration-files/09-declare-namespace/src/jQuery.d.ts
class Event (line 6) | class Event {
type EventType (line 9) | enum EventType {
FILE: examples/declaration-files/12-interface/src/jQuery.d.ts
type AjaxSettings (line 3) | interface AjaxSettings {
FILE: examples/declaration-files/13-avoid-name-conflict/src/jQuery.d.ts
type AjaxSettings (line 4) | interface AjaxSettings {
FILE: examples/declaration-files/15-export/types/foo/index.d.ts
class Animal (line 5) | class Animal {
type Directions (line 9) | enum Directions {
type Options (line 15) | interface Options {
FILE: examples/declaration-files/16-declare-and-export/types/foo/index.d.ts
class Animal (line 5) | class Animal {
type Directions (line 9) | enum Directions {
type Options (line 15) | interface Options {
FILE: examples/declaration-files/19-export-default-enum-error/types/foo/index.d.ts
type Directions (line 3) | enum Directions {
FILE: examples/declaration-files/20-export-default-enum/types/foo/index.d.ts
type Directions (line 5) | enum Directions {
FILE: examples/declaration-files/23-merge-global-interface/src/index.ts
type String (line 1) | interface String {
FILE: examples/declaration-files/24-merge-global-namespace/types/jquery-plugin/index.d.ts
type CustomOptions (line 4) | interface CustomOptions {
type JQueryStatic (line 9) | interface JQueryStatic {
FILE: examples/declaration-files/25-declare-global/types/foo/index.d.ts
type String (line 4) | interface String {
FILE: examples/declaration-files/27-multiple-declare-module/types/foo-bar.d.ts
type Foo (line 4) | interface Foo {
FILE: examples/declaration-files/30-auto-d-ts/lib/bar/index.js
function bar (line 3) | function bar() {
FILE: examples/declaration-files/30-auto-d-ts/lib/index.js
function __export (line 2) | function __export(m) {
function foo (line 7) | function foo() {
FILE: examples/declaration-files/30-auto-d-ts/src/bar/index.ts
function bar (line 1) | function bar() {
FILE: examples/declaration-files/30-auto-d-ts/src/index.ts
function foo (line 3) | function foo() {
Condensed preview — 161 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (172K chars).
[
{
"path": ".editorconfig",
"chars": 367,
"preview": "# EditorConfig is awesome: https://EditorConfig.org\n\n# top-most EditorConfig file\nroot = true\n\n# Unix-style newlines wit"
},
{
"path": ".eslintignore",
"chars": 7,
"preview": "*.d.ts\n"
},
{
"path": ".eslintrc.js",
"chars": 636,
"preview": "module.exports = {\n extends: ['alloy', 'alloy/react', 'alloy/typescript'],\n env: {\n // Your environments (which con"
},
{
"path": ".github/FUNDING.yml",
"chars": 612,
"preview": "# These are supported funding model platforms\n\ngithub: xcatliu\npatreon: # Replace with a single Patreon username\nopen_co"
},
{
"path": ".github/workflows/gh-pages.yml",
"chars": 895,
"preview": "name: gh-pages\n\non:\n push:\n branches:\n - master\n\njobs:\n build-and-deploy:\n runs-on: ubuntu-22.04\n steps:"
},
{
"path": ".gitignore",
"chars": 28,
"preview": ".DS_Store\nnode_modules\ndist\n"
},
{
"path": ".lintmdrc",
"chars": 99,
"preview": "{\n \"excludeFiles\": [],\n \"rules\": {\n \"no-trailing-punctuation\": 0,\n \"no-long-code\": 0\n }\n}\n"
},
{
"path": ".npmrc",
"chars": 37,
"preview": "registry=https://registry.npmjs.org/\n"
},
{
"path": ".prettierignore",
"chars": 154,
"preview": "*.md\n*.png\n*.epub\n\nnode_modules\n\nassets\n\n.DS_Store\n.editorconfig\n.eslintignore\n.gitignore\n.lintmdrc\n.prettierignore\n.npm"
},
{
"path": ".prettierrc.js",
"chars": 955,
"preview": "// .prettierrc.js\nmodule.exports = {\n // 一行最多 120 字符\n printWidth: 120,\n // 使用 2 个空格缩进\n tabWidth: 2,\n // 不使用缩进符，而使用空"
},
{
"path": ".vscode/settings.json",
"chars": 520,
"preview": "{\n \"files.eol\": \"\\n\",\n \"editor.tabSize\": 2,\n \"editor.formatOnSave\": true,\n \"editor.defaultFormatter\": \"esbenp.pretti"
},
{
"path": "README.md",
"chars": 2217,
"preview": "---\nnext: introduction/README.md\n---\n\n# TypeScript 入门教程\n\n[![Actions Status](https://github.com/xcatliu/typescript-tutori"
},
{
"path": "advanced/README.md",
"chars": 260,
"preview": "# 进阶\n\n本部分介绍一些高级的类型与技术，具体内容包括：\n\n- [类型别名](type-aliases.md)\n- [字符串字面量类型](string-literal-types.md)\n- [元组](tuple.md)\n- [枚举](e"
},
{
"path": "advanced/class-and-interfaces.md",
"chars": 4235,
"preview": "# 类与接口\n\n[之前学习过](../basics/type-of-object-interfaces.md)，接口（Interfaces）可以用于对「对象的形状（Shape）」进行描述。\n\n这一章主要介绍接口的另一个用途，对类的一部分行为"
},
{
"path": "advanced/class.md",
"chars": 8333,
"preview": "# 类\n\n传统方法中，JavaScript 通过构造函数实现类的概念，通过原型链实现继承。而在 ES6 中，我们终于迎来了 `class`。\n\nTypeScript 除了实现了所有 ES6 中的类的功能以外，还添加了一些新的用法。\n\n这一节"
},
{
"path": "advanced/declaration-merging.md",
"chars": 1661,
"preview": "# 声明合并\n\n如果定义了两个相同名字的函数、接口或类，那么它们会合并成一个类型：\n\n## 函数的合并\n\n[之前学习过](../basics/type-of-function.md#重载)，我们可以使用重载定义多个函数类型：\n\n```ts\n"
},
{
"path": "advanced/decorator.md",
"chars": 7615,
"preview": "# 装饰器\n\n写在前面：本章只介绍 TypeScript 5.0+ 的装饰器用法，对于 5.0 以下的版本，请参考 [TypeScript 官方文档](https://www.typescriptlang.org/docs/handbook"
},
{
"path": "advanced/enum.md",
"chars": 5113,
"preview": "# 枚举\n\n枚举（Enum）类型用于取值被限定在一定范围内的场景，比如一周只能有七天，颜色限定为红绿蓝等。\n\n## 简单的例子\n\n枚举使用 `enum` 关键字来定义：\n\n```ts\nenum Days {Sun, Mon, Tue, We"
},
{
"path": "advanced/further-reading.md",
"chars": 3899,
"preview": "# 扩展阅读\n\n此处记录了[官方手册](http://www.typescriptlang.org/docs/handbook/basic-types.html)（[中文版](https://zhongsp.gitbooks.io/type"
},
{
"path": "advanced/generics.md",
"chars": 4549,
"preview": "# 泛型\n\n泛型（Generics）是指在定义函数、接口或类的时候，不预先指定具体的类型，而在使用的时候再指定类型的一种特性。\n\n## 简单的例子\n\n首先，我们来实现一个函数 `createArray`，它可以创建一个指定长度的数组，同时将"
},
{
"path": "advanced/string-literal-types.md",
"chars": 794,
"preview": "# 字符串字面量类型\n\n字符串字面量类型用来约束取值只能是某几个字符串中的一个。\n\n## 简单的例子\n\n```ts\ntype EventNames = 'click' | 'scroll' | 'mousemove';\nfunction h"
},
{
"path": "advanced/tuple.md",
"chars": 1038,
"preview": "# 元组\n\n数组合并了相同类型的对象，而元组（Tuple）合并了不同类型的对象。\n\n元组起源于函数编程语言（如 F#），这些语言中会频繁使用元组。\n\n## 简单的例子\n\n定义一对值分别为 `string` 和 `number` 的元组：\n\n"
},
{
"path": "advanced/type-aliases.md",
"chars": 543,
"preview": "# 类型别名\n\n类型别名用来给一个类型起个新名字。\n\n## 简单的例子\n\n```ts\ntype Name = string;\ntype NameResolver = () => string;\ntype NameOrResolver = N"
},
{
"path": "basics/README.md",
"chars": 370,
"preview": "# 基础\n\n本部分介绍了 TypeScript 中的常用类型和一些基本概念，旨在让大家对 TypeScript 有个初步的理解。具体内容包括：\n\n- [原始数据类型](primitive-data-types.md)\n- [任意值](any"
},
{
"path": "basics/any.md",
"chars": 1102,
"preview": "# 任意值\n\n任意值（Any）用来表示允许赋值为任意类型。\n\n## 什么是任意值类型\n\n如果是一个普通类型，在赋值过程中改变类型是不被允许的：\n\n```ts\nlet myFavoriteNumber: string = 'seven';\nm"
},
{
"path": "basics/built-in-objects.md",
"chars": 2326,
"preview": "# 内置对象\n\nJavaScript 中有很多[内置对象][]，它们可以直接在 TypeScript 中当做定义好了的类型。\n\n内置对象是指根据标准在全局作用域（Global）上存在的对象。这里的标准是指 ECMAScript 和其他环境（"
},
{
"path": "basics/declaration-files.md",
"chars": 27835,
"preview": "# 声明文件\n\n当使用第三方库时，我们需要引用它的声明文件，才能获得对应的代码补全、接口提示等功能。\n\n## 新语法索引\n\n由于本章涉及大量新语法，故在本章开头列出新语法的索引，方便大家在使用这些新语法时能快速查找到对应的讲解：\n\n- [`"
},
{
"path": "basics/primitive-data-types.md",
"chars": 3276,
"preview": "# 原始数据类型\n\nJavaScript 的类型分为两种：原始数据类型（[Primitive data types][]）和对象类型（Object types）。\n\n原始数据类型包括：布尔值、数值、字符串、`null`、`undefined"
},
{
"path": "basics/type-assertion.md",
"chars": 11298,
"preview": "# 类型断言\n\n类型断言（Type Assertion）可以用来手动指定一个值的类型。\n\n## 语法\n\n```ts\n值 as 类型\n```\n\n或\n\n```ts\n<类型>值\n```\n\n在 tsx 语法（React 的 jsx 语法的 ts 版"
},
{
"path": "basics/type-inference.md",
"chars": 793,
"preview": "# 类型推论\n\n如果没有明确的指定类型，那么 TypeScript 会依照类型推论（Type Inference）的规则推断出一个类型。\n\n## 什么是类型推论\n\n以下代码虽然没有指定类型，但是会在编译的时候报错：\n\n```ts\nlet m"
},
{
"path": "basics/type-of-array.md",
"chars": 2344,
"preview": "# 数组的类型\n\n在 TypeScript 中，数组类型有多种定义方式，比较灵活。\n\n## 「类型 + 方括号」表示法\n\n最简单的方法是使用「类型 + 方括号」来表示数组：\n\n```ts\nlet fibonacci: number[] = "
},
{
"path": "basics/type-of-function.md",
"chars": 5170,
"preview": "# 函数的类型\n\n> [函数是 JavaScript 中的一等公民](https://llh911001.gitbooks.io/mostly-adequate-guide-chinese/content/ch2.html)\n\n## 函数声"
},
{
"path": "basics/type-of-object-interfaces.md",
"chars": 4586,
"preview": "# 对象的类型——接口\n\n在 TypeScript 中，我们使用接口（Interfaces）来定义对象的类型。\n\n## 什么是接口\n\n在面向对象语言中，接口（Interfaces）是一个很重要的概念，它是对行为的抽象，而具体如何行动需要由类"
},
{
"path": "basics/union-types.md",
"chars": 1690,
"preview": "# 联合类型\n\n联合类型（Union Types）表示取值可以为多种类型中的一种。\n\n## 简单的例子\n\n```ts\nlet myFavoriteNumber: string | number;\nmyFavoriteNumber = 'se"
},
{
"path": "engineering/README.md",
"chars": 209,
"preview": "# 工程\n\n掌握了 TypeScript 的语法就像学会了砌墙的工艺。\n\n我们学习 TypeScript 的目的不是为了造一间小茅屋，而是为了造高楼大厦，这也正是 TypeScript 的类型系统带来的优势。\n\n那么一项大工程应该如何开展呢"
},
{
"path": "engineering/compiler-options.md",
"chars": 2005,
"preview": "# 编译选项\n\nTypeScript 提供了非常多的编译选项，但是官方文档对每一项的解释很抽象，这一章会详细介绍每一个选项的作用，并给出对应的示例。\n\n索引（点击选项跳转到详细介绍）：\n\n选项 | 类型 | 默认值 | 描述\n--- | -"
},
{
"path": "engineering/lint.md",
"chars": 10693,
"preview": "# 代码检查\n\n2019 年 1 月，[TypeScirpt 官方决定全面采用 ESLint](https://www.oschina.net/news/103818/future-typescript-eslint) 作为代码检查的工具，"
},
{
"path": "examples/compiler-options/01-allowJs/false/lib/index.js",
"chars": 102,
"preview": "\"use strict\";\nexports.__esModule = true;\nvar foo_1 = require(\"./foo\");\nconsole.log(foo_1[\"default\"]);\n"
},
{
"path": "examples/compiler-options/01-allowJs/false/package.json",
"chars": 335,
"preview": "{\n \"name\": \"01-allow-js-false\",\n \"version\": \"1.0.0\",\n \"description\": \"\",\n \"main\": \"index.js\",\n \"scripts\":"
},
{
"path": "examples/compiler-options/01-allowJs/false/src/foo.js",
"chars": 35,
"preview": "const foo = 1;\nexport default foo;\n"
},
{
"path": "examples/compiler-options/01-allowJs/false/src/index.ts",
"chars": 43,
"preview": "import foo from './foo';\nconsole.log(foo);\n"
},
{
"path": "examples/compiler-options/01-allowJs/false/tsconfig.json",
"chars": 85,
"preview": "{\n \"compilerOptions\": {\n \"allowJs\": false,\n \"outDir\": \"lib\"\n }\n}\n"
},
{
"path": "examples/compiler-options/01-allowJs/true/lib/foo.js",
"chars": 80,
"preview": "\"use strict\";\nexports.__esModule = true;\nvar foo = 1;\nexports[\"default\"] = foo;\n"
},
{
"path": "examples/compiler-options/01-allowJs/true/lib/index.js",
"chars": 102,
"preview": "\"use strict\";\nexports.__esModule = true;\nvar foo_1 = require(\"./foo\");\nconsole.log(foo_1[\"default\"]);\n"
},
{
"path": "examples/compiler-options/01-allowJs/true/package.json",
"chars": 334,
"preview": "{\n \"name\": \"01-allow-js-true\",\n \"version\": \"1.0.0\",\n \"description\": \"\",\n \"main\": \"index.js\",\n \"scripts\": "
},
{
"path": "examples/compiler-options/01-allowJs/true/src/foo.js",
"chars": 35,
"preview": "const foo = 1;\nexport default foo;\n"
},
{
"path": "examples/compiler-options/01-allowJs/true/src/index.ts",
"chars": 43,
"preview": "import foo from './foo';\nconsole.log(foo);\n"
},
{
"path": "examples/compiler-options/01-allowJs/true/tsconfig.json",
"chars": 84,
"preview": "{\n \"compilerOptions\": {\n \"allowJs\": true,\n \"outDir\": \"lib\"\n }\n}\n"
},
{
"path": "examples/compiler-options/02-allowSyntheticDefaultImports/false/package.json",
"chars": 431,
"preview": "{\n \"name\": \"02-allow-synthetic-default-imports-false\",\n \"version\": \"1.0.0\",\n \"description\": \"\",\n \"main\": \"in"
},
{
"path": "examples/compiler-options/02-allowSyntheticDefaultImports/false/src/index.ts",
"chars": 27,
"preview": "import React from 'react';\n"
},
{
"path": "examples/compiler-options/02-allowSyntheticDefaultImports/false/tsconfig.json",
"chars": 106,
"preview": "{\n \"compilerOptions\": {\n \"allowSyntheticDefaultImports\": false,\n \"outDir\": \"lib\"\n }\n}\n"
},
{
"path": "examples/compiler-options/02-allowSyntheticDefaultImports/true/package.json",
"chars": 431,
"preview": "{\n \"name\": \"02-allow-synthetic-default-imports-false\",\n \"version\": \"1.0.0\",\n \"description\": \"\",\n \"main\": \"in"
},
{
"path": "examples/compiler-options/02-allowSyntheticDefaultImports/true/src/index.ts",
"chars": 27,
"preview": "import React from 'react';\n"
},
{
"path": "examples/compiler-options/02-allowSyntheticDefaultImports/true/tsconfig.json",
"chars": 105,
"preview": "{\n \"compilerOptions\": {\n \"allowSyntheticDefaultImports\": true,\n \"outDir\": \"lib\"\n }\n}\n"
},
{
"path": "examples/declaration-files/01-jquery/src/index.ts",
"chars": 53,
"preview": "jQuery('#foo');\n// ERROR: Cannot find name 'jQuery'.\n"
},
{
"path": "examples/declaration-files/01-jquery/tsconfig.json",
"chars": 3,
"preview": "{}\n"
},
{
"path": "examples/declaration-files/02-declare-var/src/index.ts",
"chars": 99,
"preview": "// eslint-disable-next-line no-var\ndeclare var jQuery: (selector: string) => any;\n\njQuery('#foo');\n"
},
{
"path": "examples/declaration-files/02-declare-var/tsconfig.json",
"chars": 3,
"preview": "{}\n"
},
{
"path": "examples/declaration-files/03-jquery-d-ts/src/index.ts",
"chars": 33,
"preview": "// src/index.ts\n\njQuery('#foo');\n"
},
{
"path": "examples/declaration-files/03-jquery-d-ts/src/jQuery.d.ts",
"chars": 67,
"preview": "// src/jQuery.d.ts\n\ndeclare var jQuery: (selector: string) => any;\n"
},
{
"path": "examples/declaration-files/03-jquery-d-ts/tsconfig.json",
"chars": 53,
"preview": "{\n \"files\": [\"src/index.ts\", \"src/jQuery.d.ts\"]\n}\n"
},
{
"path": "examples/declaration-files/04-declare-const-jquery/src/index.ts",
"chars": 242,
"preview": "// src/index.ts\n\njQuery('#foo');\n// 使用 declare const 定义的 jQuery 类型，禁止修改这个全局变量\njQuery = function(selector) {\n return d"
},
{
"path": "examples/declaration-files/04-declare-const-jquery/src/jQuery.d.ts",
"chars": 69,
"preview": "// src/jQuery.d.ts\n\ndeclare const jQuery: (selector: string) => any;\n"
},
{
"path": "examples/declaration-files/04-declare-const-jquery/tsconfig.json",
"chars": 3,
"preview": "{}\n"
},
{
"path": "examples/declaration-files/05-declare-jquery-value/src/jQuery.d.ts",
"chars": 160,
"preview": "declare const jQuery = function(selector) {\n return document.querySelector(selector);\n};\n// ERROR: An implementation "
},
{
"path": "examples/declaration-files/05-declare-jquery-value/tsconfig.json",
"chars": 3,
"preview": "{}\n"
},
{
"path": "examples/declaration-files/06-declare-function/src/index.ts",
"chars": 82,
"preview": "// src/index.ts\n\njQuery('#foo');\njQuery(function() {\n alert('Dom Ready!');\n});\n"
},
{
"path": "examples/declaration-files/06-declare-function/src/jQuery.d.ts",
"chars": 127,
"preview": "// src/jQuery.d.ts\n\ndeclare function jQuery(selector: string): any;\ndeclare function jQuery(domReadyCallback: () => any)"
},
{
"path": "examples/declaration-files/06-declare-function/tsconfig.json",
"chars": 3,
"preview": "{}\n"
},
{
"path": "examples/declaration-files/07-declare-class/src/Animal.d.ts",
"chars": 115,
"preview": "// src/Animal.d.ts\n\ndeclare class Animal {\n name: string;\n constructor(name: string);\n sayHi(): string;\n}\n"
},
{
"path": "examples/declaration-files/07-declare-class/src/index.ts",
"chars": 46,
"preview": "// src/index.ts\n\nlet cat = new Animal('Tom');\n"
},
{
"path": "examples/declaration-files/07-declare-class/tsconfig.json",
"chars": 3,
"preview": "{}\n"
},
{
"path": "examples/declaration-files/08-declare-enum/src/Directions.d.ts",
"chars": 90,
"preview": "// src/Directions.d.ts\n\ndeclare enum Directions {\n Up,\n Down,\n Left,\n Right\n}\n"
},
{
"path": "examples/declaration-files/08-declare-enum/src/index.ts",
"chars": 103,
"preview": "// src/index.ts\n\nlet directions = [Directions.Up, Directions.Down, Directions.Left, Directions.Right];\n"
},
{
"path": "examples/declaration-files/08-declare-enum/tsconfig.json",
"chars": 3,
"preview": "{}\n"
},
{
"path": "examples/declaration-files/09-declare-namespace/src/index.ts",
"chars": 149,
"preview": "// src/index.ts\n\njQuery.ajax('/api/get_something');\nconsole.log(jQuery.version);\nconst e = new jQuery.Event();\ne.blur(jQ"
},
{
"path": "examples/declaration-files/09-declare-namespace/src/jQuery.d.ts",
"chars": 243,
"preview": "// src/jQuery.d.ts\n\ndeclare namespace jQuery {\n function ajax(url: string, settings?: any): void;\n const version: "
},
{
"path": "examples/declaration-files/09-declare-namespace/tsconfig.json",
"chars": 3,
"preview": "{}\n"
},
{
"path": "examples/declaration-files/10-declare-namespace-nesting/src/index.ts",
"chars": 188,
"preview": "// src/index.ts\n\njQuery.ajax('/api/get_something');\njQuery.fn.extend({\n check: function() {\n return this.each("
},
{
"path": "examples/declaration-files/10-declare-namespace-nesting/src/jQuery.d.ts",
"chars": 172,
"preview": "// src/jQuery.d.ts\n\ndeclare namespace jQuery {\n function ajax(url: string, settings?: any): void;\n namespace fn {\n"
},
{
"path": "examples/declaration-files/10-declare-namespace-nesting/tsconfig.json",
"chars": 3,
"preview": "{}\n"
},
{
"path": "examples/declaration-files/11-declare-namespace-dot/src/index.ts",
"chars": 153,
"preview": "// src/index.ts\n\njQuery.fn.extend({\n check: function() {\n return this.each(function() {\n this.check"
},
{
"path": "examples/declaration-files/11-declare-namespace-dot/src/jQuery.d.ts",
"chars": 92,
"preview": "// src/jQuery.d.ts\n\ndeclare namespace jQuery.fn {\n function extend(object: any): void;\n}\n"
},
{
"path": "examples/declaration-files/11-declare-namespace-dot/tsconfig.json",
"chars": 3,
"preview": "{}\n"
},
{
"path": "examples/declaration-files/12-interface/src/index.ts",
"chars": 155,
"preview": "// src/index.ts\n\nlet settings: AjaxSettings = {\n method: 'POST',\n data: {\n name: 'foo'\n }\n};\njQuery.ajax"
},
{
"path": "examples/declaration-files/12-interface/src/jQuery.d.ts",
"chars": 184,
"preview": "// src/jQuery.d.ts\n\ninterface AjaxSettings {\n method?: 'GET' | 'POST';\n data?: any;\n}\ndeclare namespace jQuery {\n "
},
{
"path": "examples/declaration-files/12-interface/tsconfig.json",
"chars": 3,
"preview": "{}\n"
},
{
"path": "examples/declaration-files/13-avoid-name-conflict/src/index.ts",
"chars": 162,
"preview": "// src/index.ts\n\nlet settings: jQuery.AjaxSettings = {\n method: 'POST',\n data: {\n name: 'foo'\n }\n};\njQue"
},
{
"path": "examples/declaration-files/13-avoid-name-conflict/src/jQuery.d.ts",
"chars": 200,
"preview": "// src/jQuery.d.ts\n\ndeclare namespace jQuery {\n interface AjaxSettings {\n method?: 'GET' | 'POST';\n dat"
},
{
"path": "examples/declaration-files/13-avoid-name-conflict/tsconfig.json",
"chars": 3,
"preview": "{}\n"
},
{
"path": "examples/declaration-files/14-declaration-merging/src/index.ts",
"chars": 68,
"preview": "// src/index.ts\n\njQuery('#foo');\njQuery.ajax('/api/get_something');\n"
},
{
"path": "examples/declaration-files/14-declaration-merging/src/jQuery.d.ts",
"chars": 151,
"preview": "// src/jQuery.d.ts\n\ndeclare function jQuery(selector: string): any;\ndeclare namespace jQuery {\n function ajax(url: st"
},
{
"path": "examples/declaration-files/14-declaration-merging/tsconfig.json",
"chars": 3,
"preview": "{}\n"
},
{
"path": "examples/declaration-files/15-export/src/index.ts",
"chars": 308,
"preview": "// src/index.ts\n\nimport { name, getName, Animal, Directions, Options } from 'foo';\n\nconsole.log(name);\nlet myName = getN"
},
{
"path": "examples/declaration-files/15-export/tsconfig.json",
"chars": 148,
"preview": "{\n \"compilerOptions\": {\n \"module\": \"commonjs\",\n \"baseUrl\": \"./\",\n \"paths\": {\n \"*\": [\""
},
{
"path": "examples/declaration-files/15-export/types/foo/index.d.ts",
"chars": 272,
"preview": "// types/foo/index.d.ts\n\nexport const name: string;\nexport function getName(): string;\nexport class Animal {\n constru"
},
{
"path": "examples/declaration-files/16-declare-and-export/src/index.ts",
"chars": 308,
"preview": "// src/index.ts\n\nimport { name, getName, Animal, Directions, Options } from 'foo';\n\nconsole.log(name);\nlet myName = getN"
},
{
"path": "examples/declaration-files/16-declare-and-export/tsconfig.json",
"chars": 148,
"preview": "{\n \"compilerOptions\": {\n \"module\": \"commonjs\",\n \"baseUrl\": \"./\",\n \"paths\": {\n \"*\": [\""
},
{
"path": "examples/declaration-files/16-declare-and-export/types/foo/index.d.ts",
"chars": 325,
"preview": "// types/foo/index.d.ts\n\ndeclare const name: string;\ndeclare function getName(): string;\ndeclare class Animal {\n cons"
},
{
"path": "examples/declaration-files/17-export-namespace/src/index.ts",
"chars": 83,
"preview": "// src/index.ts\n\nimport { foo } from 'foo';\n\nconsole.log(foo.name);\nfoo.bar.baz();\n"
},
{
"path": "examples/declaration-files/17-export-namespace/tsconfig.json",
"chars": 148,
"preview": "{\n \"compilerOptions\": {\n \"module\": \"commonjs\",\n \"baseUrl\": \"./\",\n \"paths\": {\n \"*\": [\""
},
{
"path": "examples/declaration-files/17-export-namespace/types/foo/index.d.ts",
"chars": 132,
"preview": "// types/foo/index.d.ts\n\nexport namespace foo {\n const name: string;\n namespace bar {\n function baz(): stri"
},
{
"path": "examples/declaration-files/18-export-default/src/index.ts",
"chars": 48,
"preview": "// src/index.ts\n\nimport foo from 'foo';\n\nfoo();\n"
},
{
"path": "examples/declaration-files/18-export-default/tsconfig.json",
"chars": 148,
"preview": "{\n \"compilerOptions\": {\n \"module\": \"commonjs\",\n \"baseUrl\": \"./\",\n \"paths\": {\n \"*\": [\""
},
{
"path": "examples/declaration-files/18-export-default/types/foo/index.d.ts",
"chars": 64,
"preview": "// types/foo/index.d.ts\n\nexport default function foo(): string;\n"
},
{
"path": "examples/declaration-files/19-export-default-enum-error/src/index.ts",
"chars": 64,
"preview": "// src/index.ts\n\nimport foo from 'foo';\n\nconsole.log(foo.Down);\n"
},
{
"path": "examples/declaration-files/19-export-default-enum-error/tsconfig.json",
"chars": 148,
"preview": "{\n \"compilerOptions\": {\n \"module\": \"commonjs\",\n \"baseUrl\": \"./\",\n \"paths\": {\n \"*\": [\""
},
{
"path": "examples/declaration-files/19-export-default-enum-error/types/foo/index.d.ts",
"chars": 129,
"preview": "// types/foo/index.d.ts\n\nexport default enum Directions {\n// ERROR: Expression expected.\n Up,\n Down,\n Left,\n "
},
{
"path": "examples/declaration-files/20-export-default-enum/src/index.ts",
"chars": 64,
"preview": "// src/index.ts\n\nimport foo from 'foo';\n\nconsole.log(foo.Down);\n"
},
{
"path": "examples/declaration-files/20-export-default-enum/tsconfig.json",
"chars": 148,
"preview": "{\n \"compilerOptions\": {\n \"module\": \"commonjs\",\n \"baseUrl\": \"./\",\n \"paths\": {\n \"*\": [\""
},
{
"path": "examples/declaration-files/20-export-default-enum/types/foo/index.d.ts",
"chars": 119,
"preview": "// types/foo/index.d.ts\n\nexport default Directions;\n\ndeclare enum Directions {\n Up,\n Down,\n Left,\n Right\n}\n"
},
{
"path": "examples/declaration-files/21-export-equal/src/index.ts",
"chars": 67,
"preview": "// 整体导入\nimport foo = require('foo');\n// 单个导入\nimport bar = foo.bar;\n"
},
{
"path": "examples/declaration-files/21-export-equal/tsconfig.json",
"chars": 148,
"preview": "{\n \"compilerOptions\": {\n \"module\": \"commonjs\",\n \"baseUrl\": \"./\",\n \"paths\": {\n \"*\": [\""
},
{
"path": "examples/declaration-files/21-export-equal/types/foo/index.d.ts",
"chars": 121,
"preview": "// types/foo/index.d.ts\n\nexport = foo;\n\ndeclare function foo(): string;\ndeclare namespace foo {\n const bar: number;\n}"
},
{
"path": "examples/declaration-files/22-export-as-namespace/src/index.ts",
"chars": 46,
"preview": "// src/index.ts\n\nfoo();\nconsole.log(foo.bar);\n"
},
{
"path": "examples/declaration-files/22-export-as-namespace/tsconfig.json",
"chars": 148,
"preview": "{\n \"compilerOptions\": {\n \"module\": \"commonjs\",\n \"baseUrl\": \"./\",\n \"paths\": {\n \"*\": [\""
},
{
"path": "examples/declaration-files/22-export-as-namespace/types/foo/index.d.ts",
"chars": 146,
"preview": "// types/foo/index.d.ts\n\nexport as namespace foo;\nexport = foo;\n\ndeclare function foo(): string;\ndeclare namespace foo {"
},
{
"path": "examples/declaration-files/23-merge-global-interface/src/index.ts",
"chars": 72,
"preview": "interface String {\n prependHello(): string;\n}\n\n'foo'.prependHello();\n"
},
{
"path": "examples/declaration-files/23-merge-global-interface/tsconfig.json",
"chars": 3,
"preview": "{}\n"
},
{
"path": "examples/declaration-files/24-merge-global-namespace/package.json",
"chars": 364,
"preview": "{\n \"name\": \"24-merge-global-namespace\",\n \"version\": \"1.0.0\",\n \"description\": \"\",\n \"main\": \"index.js\",\n \"s"
},
{
"path": "examples/declaration-files/24-merge-global-namespace/src/index.ts",
"chars": 46,
"preview": "// src/index.ts\n\njQuery.foo({\n bar: ''\n});\n"
},
{
"path": "examples/declaration-files/24-merge-global-namespace/tsconfig.json",
"chars": 148,
"preview": "{\n \"compilerOptions\": {\n \"module\": \"commonjs\",\n \"baseUrl\": \"./\",\n \"paths\": {\n \"*\": [\""
},
{
"path": "examples/declaration-files/24-merge-global-namespace/types/jquery-plugin/index.d.ts",
"chars": 197,
"preview": "// types/jquery-plugin/index.d.ts\n\ndeclare namespace JQuery {\n interface CustomOptions {\n bar: string;\n }\n}"
},
{
"path": "examples/declaration-files/25-declare-global/src/index.ts",
"chars": 39,
"preview": "// src/index.ts\n\n'foo'.prependHello();\n"
},
{
"path": "examples/declaration-files/25-declare-global/tsconfig.json",
"chars": 148,
"preview": "{\n \"compilerOptions\": {\n \"module\": \"commonjs\",\n \"baseUrl\": \"./\",\n \"paths\": {\n \"*\": [\""
},
{
"path": "examples/declaration-files/25-declare-global/types/foo/index.d.ts",
"chars": 117,
"preview": "// types/foo/index.d.ts\n\ndeclare global {\n interface String {\n prependHello(): string;\n }\n}\n\nexport {};\n"
},
{
"path": "examples/declaration-files/26-declare-module/package.json",
"chars": 317,
"preview": "{\n \"name\": \"26-declare-module\",\n \"version\": \"1.0.0\",\n \"description\": \"\",\n \"main\": \"index.js\",\n \"scripts\":"
},
{
"path": "examples/declaration-files/26-declare-module/src/index.ts",
"chars": 90,
"preview": "// src/index.ts\n\nimport * as moment from 'moment';\nimport 'moment-plugin';\n\nmoment.foo();\n"
},
{
"path": "examples/declaration-files/26-declare-module/tsconfig.json",
"chars": 148,
"preview": "{\n \"compilerOptions\": {\n \"module\": \"commonjs\",\n \"baseUrl\": \"./\",\n \"paths\": {\n \"*\": [\""
},
{
"path": "examples/declaration-files/26-declare-module/types/moment-plugin/index.d.ts",
"chars": 145,
"preview": "// types/moment-plugin/index.d.ts\n\nimport * as moment from 'moment';\n\ndeclare module 'moment' {\n export function foo("
},
{
"path": "examples/declaration-files/27-multiple-declare-module/src/index.ts",
"chars": 96,
"preview": "// src/index.ts\n\nimport { Foo } from 'foo';\nimport * as bar from 'bar';\n\nlet f: Foo;\nbar.bar();\n"
},
{
"path": "examples/declaration-files/27-multiple-declare-module/tsconfig.json",
"chars": 148,
"preview": "{\n \"compilerOptions\": {\n \"module\": \"commonjs\",\n \"baseUrl\": \"./\",\n \"paths\": {\n \"*\": [\""
},
{
"path": "examples/declaration-files/27-multiple-declare-module/types/foo-bar.d.ts",
"chars": 163,
"preview": "// types/foo-bar.d.ts\n\ndeclare module 'foo' {\n export interface Foo {\n foo: string;\n }\n}\n\ndeclare module 'b"
},
{
"path": "examples/declaration-files/28-triple-slash-directives/package.json",
"chars": 365,
"preview": "{\n \"name\": \"28-triple-slash-directives\",\n \"version\": \"1.0.0\",\n \"description\": \"\",\n \"main\": \"index.js\",\n \""
},
{
"path": "examples/declaration-files/28-triple-slash-directives/src/index.ts",
"chars": 26,
"preview": "// src/index.ts\n\nfoo({});\n"
},
{
"path": "examples/declaration-files/28-triple-slash-directives/tsconfig.json",
"chars": 148,
"preview": "{\n \"compilerOptions\": {\n \"module\": \"commonjs\",\n \"baseUrl\": \"./\",\n \"paths\": {\n \"*\": [\""
},
{
"path": "examples/declaration-files/28-triple-slash-directives/types/jquery-plugin/index.d.ts",
"chars": 129,
"preview": "// types/jquery-plugin/index.d.ts\n\n/// <reference types=\"jquery\" />\n\ndeclare function foo(options: JQuery.AjaxSettings):"
},
{
"path": "examples/declaration-files/29-triple-slash-directives-global/package.json",
"chars": 338,
"preview": "{\n \"name\": \"29-triple-slash-directives-global\",\n \"version\": \"1.0.0\",\n \"description\": \"\",\n \"main\": \"index.js\""
},
{
"path": "examples/declaration-files/29-triple-slash-directives-global/src/index.ts",
"chars": 74,
"preview": "// src/index.ts\n\nimport { foo } from 'node-plugin';\n\nfoo(global.process);\n"
},
{
"path": "examples/declaration-files/29-triple-slash-directives-global/tsconfig.json",
"chars": 148,
"preview": "{\n \"compilerOptions\": {\n \"module\": \"commonjs\",\n \"baseUrl\": \"./\",\n \"paths\": {\n \"*\": [\""
},
{
"path": "examples/declaration-files/29-triple-slash-directives-global/types/node-plugin/index.d.ts",
"chars": 113,
"preview": "// types/node-plugin/index.d.ts\n\n/// <reference types=\"node\" />\n\nexport function foo(p: NodeJS.Process): string;\n"
},
{
"path": "examples/declaration-files/30-auto-d-ts/lib/bar/index.d.ts",
"chars": 75,
"preview": "export declare function bar(): string;\n//# sourceMappingURL=index.d.ts.map\n"
},
{
"path": "examples/declaration-files/30-auto-d-ts/lib/bar/index.js",
"chars": 97,
"preview": "\"use strict\";\nexports.__esModule = true;\nfunction bar() {\n return 'bar';\n}\nexports.bar = bar;\n"
},
{
"path": "examples/declaration-files/30-auto-d-ts/lib/index.d.ts",
"chars": 98,
"preview": "export * from './bar';\nexport default function foo(): string;\n//# sourceMappingURL=index.d.ts.map\n"
},
{
"path": "examples/declaration-files/30-auto-d-ts/lib/index.js",
"chars": 229,
"preview": "\"use strict\";\nfunction __export(m) {\n for (var p in m) if (!exports.hasOwnProperty(p)) exports[p] = m[p];\n}\nexports._"
},
{
"path": "examples/declaration-files/30-auto-d-ts/package.json",
"chars": 346,
"preview": "{\n \"name\": \"30-auto-d-ts\",\n \"version\": \"1.0.0\",\n \"description\": \"\",\n \"main\": \"lib/index.js\",\n \"scripts\": "
},
{
"path": "examples/declaration-files/30-auto-d-ts/src/bar/index.ts",
"chars": 44,
"preview": "export function bar() {\n return 'bar';\n}\n"
},
{
"path": "examples/declaration-files/30-auto-d-ts/src/index.ts",
"chars": 76,
"preview": "export * from './bar';\n\nexport default function foo() {\n return 'foo';\n}\n"
},
{
"path": "examples/declaration-files/30-auto-d-ts/tsconfig.json",
"chars": 118,
"preview": "{\n \"compilerOptions\": {\n \"module\": \"commonjs\",\n \"outDir\": \"lib\",\n \"declaration\": true\n }\n}\n"
},
{
"path": "introduction/README.md",
"chars": 192,
"preview": "---\nprev: README.md\n---\n\n# 简介\n\n本部分介绍了在学习 TypeScript 之前需要了解的知识，具体内容包括：\n\n- [什么是 TypeScript](what-is-typescript.md)\n- [安装 T"
},
{
"path": "introduction/get-typescript.md",
"chars": 1274,
"preview": "# 安装 TypeScript\n\nTypeScript 的命令行工具安装方法如下：\n\n```bash\nnpm install -g typescript\n```\n\n以上命令会在全局环境下安装 `tsc` 命令，安装完成之后，我们就可以在任何"
},
{
"path": "introduction/hello-typescript.md",
"chars": 1699,
"preview": "# Hello TypeScript\n\n我们从一个简单的例子开始。\n\n将以下代码复制到 `hello.ts` 中：\n\n```ts\nfunction sayHello(person: string) {\n return 'Hello, "
},
{
"path": "introduction/what-is-typescript.md",
"chars": 7230,
"preview": "# 什么是 TypeScript\n\n> Typed JavaScript at Any Scale. \n> 添加了类型系统的 JavaScript，适用于任何规模的项目。\n\n以上描述是官网<sup>[[1]](#link-1)</sup>"
},
{
"path": "introduction/why-typescript.md",
"chars": 1413,
"preview": "\n你可能或多或少听说过这样的言论：\n\n- TypeScript 只适用于大公司的大型项目\n- TypeScript 适合多人协作开发，一个人维护的项目就没必要使用了\n- TypeScript 学习成本高，开发成本高\n- 旧项目是 JavaS"
},
{
"path": "package.json",
"chars": 1945,
"preview": "{\n \"name\": \"typescript-tutorial\",\n \"version\": \"0.1.0\",\n \"description\": \"从 JavaScript 程序员的角度总结思考，循序渐进的理解 TypeScript\",\n"
},
{
"path": "pagic.config.tsx",
"chars": 3704,
"preview": "import { React } from 'https://deno.land/x/pagic@v1.6.3/mod.ts';\n\nexport default {\n srcDir: '.',\n exclude: ['examples'"
},
{
"path": "pandoc-list.txt",
"chars": 743,
"preview": "README.md\nintroduction/README.md\nintroduction/what-is-typescript.md\nintroduction/get-typescript.md\nintroduction/hello-ty"
},
{
"path": "pandoc-metadata.txt",
"chars": 149,
"preview": "---\ntitle: TypeScript 入门教程\nauthor: xcatliu\ndescription: 从 JavaScript 程序员的角度总结思考，循序渐进的理解 TypeScript\nlanguage: zh-CN\ncover"
},
{
"path": "thanks/README.md",
"chars": 891,
"preview": "# 感谢\n\n- 感谢[创造和维护 TypeScript 的人们](https://github.com/Microsoft/TypeScript/graphs/contributors)，给我们带来了如此优秀的工具\n- 感谢 [@zhong"
}
]
// ... and 2 more files (download for full content)
About this extraction
This page contains the full source code of the xcatliu/typescript-tutorial GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 161 files (147.8 KB), approximately 61.8k tokens, and a symbol index with 24 extracted functions, classes, methods, constants, and types. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.