TypeScript不是存在于真空中。 它从JavaScript生态系统和大量现存的JavaScript而来。 将JavaScript代码转换成TypeScript虽乏味却不是难事。 接下来这篇教程将教你怎么做。 在开始转换TypeScript之前,我们假设你已经理解了足够多本手册里的内容。

设置目录

如果你在写纯JavaScript,你大概是想直接运行这些JavaScript文件, 这些文件存在于 srclibdist目录里,它们可以按照预想运行。

若如此,那么你写的纯JavaScript文件将做为TypeScript的输入,你将要运行的是TypeScript的输出。 在从JS到TS的转换过程中,我们会分离输入文件以防TypeScript覆盖它们。 你也可以指定输出目录。

你可能还需要对JavaScript做一些中间处理,比如合并或经过Babel再次编译。 在这种情况下,你应该已经有了如下的目录结构。

那么现在,我们假设你已经设置了这样的目录结构:

projectRoot
├── src
│   ├── file1.js
│   └── file2.js
├── built
└── tsconfig.json

如果你在src目录外还有tests文件夹,那么在src里可以有一个tsconfig.json文件,在tests里还可以有一个。

书写配置文件

TypeScript使用tsconfig.json文件管理工程配置,例如你想包含哪些文件和进行哪些检查。 让我们先创建一个简单的工程配置文件:

{
    "compilerOptions": {
        "outDir": "./built",
        "allowJs": true,
        "target": "es5"
    },
    "include": [
        "./src/**/*"
    ]
}

这里我们为TypeScript设置了一些东西:

  1. 读取所有可识别的src目录下的文件(通过include)。
  2. 接受JavaScript做为输入(通过allowJs)。
  3. 生成的所有文件放在built目录下(通过outDir)。
  4. 将JavaScript代码降级到低版本比如ECMAScript 5(通过target)。

现在,如果你在工程根目录下运行tsc,就可以在built目录下看到生成的文件。 built下的文件应该与src下的文件相同。 现在你的工程里的TypeScript已经可以工作了。

早期收益

现在你已经可以看到TypeScript带来的好处,它能帮助我们理解当前工程。 如果你打开像 VS CodeVisual Studio这样的编译器,你就能使用像自动补全这样的工具。 你还可以配置如下的选项来帮助查找BUG:

  • noImplicitReturns 会防止你忘记在函数末尾返回值。
  • noFallthroughCasesInSwitch 会防止在switch代码块里的两个case之间忘记添加break语句。

TypeScript还能发现那些执行不到的代码和标签,你可以通过设置allowUnreachableCodeallowUnusedLabels选项来禁用。

与构建工具进行集成

在你的构建管道中可能包含多个步骤。 比如为每个文件添加一些内容。 每种工具的使用方法都是不同的,我们会尽可能的包涵主流的工具。

Gulp

如果你在使用时髦的Gulp,我们已经有一篇关于使用Gulp结合TypeScript并与常见构建工具Browserify,Babelify和Uglify进行集成的教程。 请阅读这篇教程。

Webpack

Webpack集成非常简单。 你可以使用 ts-loader,它是一个TypeScript的加载器,结合source-map-loader方便调试。 运行:

npm install ts-loader source-map-loader

并将下面的选项合并到你的webpack.config.js文件里:

module.exports = {
    entry: "./src/index.ts",
    output: {
        filename: "./dist/bundle.js",
    },

    // Enable sourcemaps for debugging webpack's output.
    devtool: "source-map",

    resolve: {
        // Add '.ts' and '.tsx' as resolvable extensions.
        extensions: ["", ".webpack.js", ".web.js", ".ts", ".tsx", ".js"]
    },

    module: {
        loaders: [
            // All files with a '.ts' or '.tsx' extension will be handled by 'ts-loader'.
            { test: /\.tsx?$/, loader: "ts-loader" }
        ],

        preLoaders: [
            // All output '.js' files will have any sourcemaps re-processed by 'source-map-loader'.
            { test: /\.js$/, loader: "source-map-loader" }
        ]
    },

    // Other options...
};

要注意的是ts-loader必须在其它处理.js文件的加载器之前运行。 你可以在React和Webpack教程里找到使用Webpack的例子。

转换到TypeScript文件

到目前为止,你已经做好了使用TypeScript文件的准备。 第一步,将 .js文件重命名为.ts文件。 如果你使用了JSX,则重命名为 .tsx文件。

第一步达成? 太棒了! 你已经成功地将一个文件从JavaScript转换成了TypeScript!

当然了,你可能感觉哪里不对劲儿。 如果你在支持TypeScript的编辑器(或运行 tsc --pretty)里打开了那个文件,你可能会看到有些行上有红色的波浪线。 你可以把它们当做在Microsoft Word里看到的红色波浪线一样。 但是TypeScript仍然会编译你的代码,就好比Word还是允许你打印你的文档一样。

如果对你来说这种行为太随便了,你可以让它变得严格些。 如果,你 不想在发生错误的时候,TypeScript还会被编译成JavaScript,你可以使用noEmitOnError选项。 从某种意义上来讲,TypeScript具有一个调整它的严格性的刻度盘,你可以将指针拔动到你想要的位置。

如果你计划使用可用的高度严格的设置,最好现在就启用它们(查看启用严格检查)。 比如,如果你不想让TypeScript将没有明确指定的类型默默地推断为 any类型,可以在修改文件之前启用noImplicitAny。 你可能会觉得这有些过度严格,但是长期收益很快就能显现出来。

去除错误

我们提到过,若不出所料,在转换后将会看到错误信息。 重要的是我们要逐一的查看它们并决定如何处理。 通常这些都是真正的BUG,但有时必须要告诉TypeScript你要做的是什么。

由模块导入

首先你可能会看到一些类似Cannot find name 'require'.Cannot find name 'define'.的错误。 遇到这种情况说明你在使用模块。 你仅需要告诉TypeScript它们是存在的:

// For Node/CommonJS
declare function require(path: string): any;

// For RequireJS/AMD
declare function define(...args: any[]): any;

最好是避免使用这些调用而改用TypeScript的导入语法。

首先,你要使用TypeScript的module标记来启用一些模块系统。 可用的选项有 commonjsamdsystem,and umd

如果代码里存在下面的Node/CommonJS代码:

var foo = require("foo");

foo.doStuff();

或者下面的RequireJS/AMD代码:

define(["foo"], function(foo) {
    foo.doStuff();
})

那么可以写做下面的TypeScript代码:

import foo = require("foo");

foo.doStuff();

获取声明文件

如果你开始做转换到TypeScript导入,你可能会遇到Cannot find module 'foo'.这样的错误。 问题出在没有 声明文件来描述你的代码库。 幸运的是这非常简单。 如果TypeScript报怨像是没有 lodash包,那你只需这样做

npm install -s @types/lodash

如果你没有使用commonjs模块模块选项,那么就需要将moduleResolution选项设置为node

之后,你应该就可以导入lodash了,并且会获得精确的自动补全功能。

由模块导出

通常来讲,由模块导出涉及添加属性到exportsmodule.exports。 TypeScript允许你使用顶级的导出语句。 比如,你要导出下面的函数:

module.exports.feedPets = function(pets) {
    // ...
}

那么你可以这样写:

export function feedPets(pets) {
    // ...
}

有时你会完全重写导出对象。 这是一个常见模式,这会将模块变为可立即调用的模块:

var express = require("express");
var app = express();

之前你可以是这样写的:

function foo() {
    // ...
}
module.exports = foo;

在TypeScript里,你可以使用export =来代替。

function foo() {
    // ...
}
export = foo;

过多或过少的参数

有时你会发现你在调用一个具有过多或过少参数的函数。 通常,这是一个BUG,但在某些情况下,你可以声明一个使用 arguments对象的函数而不需要写出所有参数:

function myCoolFunction() {
    if (arguments.length == 2 && !Array.isArray(arguments[1])) {
        var f = arguments[0];
        var arr = arguments[1];
        // ...
    }
    // ...
}

myCoolFunction(function(x) { console.log(x) }, [1, 2, 3, 4]);
myCoolFunction(function(x) { console.log(x) }, 1, 2, 3, 4);

这种情况下,我们需要利用TypeScript的函数重载来告诉调用者myCoolFunction函数的调用方式。

function myCoolFunction(f: (x: number) => void, nums: number[]): void;
function myCoolFunction(f: (x: number) => void, ...nums: number[]): void;
function myCoolFunction() {
    if (arguments.length == 2 && !Array.isArray(arguments[1])) {
        var f = arguments[0];
        var arr = arguments[1];
        // ...
    }
    // ...
}

我们为myCoolFunction函数添加了两个重载签名。 第一个检查 myCoolFunction函数是否接收一个函数(它又接收一个number参数)和一个number数组。 第二个同样是接收了一个函数,并且使用剩余参数( ...nums)来表示之后的其它所有参数必须是number类型。