在前面的章节中,我们都是直接用 tsc 指令加上参数来编译 TypeScript 程序,并且利用 declare 关键字来声明 Node.js 才有的对象和函数。在这个章节,我们会创建 Node.js 项目,运用 TypeScript 的 tsconfig.json 文件来设置编译参数,并加装套件让 TypeScript 能直接支持 Node.js 内置的对象和函数的类型检查。
为了专注学习用 Node.js 项目开发 TypeScript 的方式,我们要继续使用上一章撰写过的代码来继续实作猜数字程序。
创建 Node.js 项目
首先,创建一个用来存放 TypeScript 项目的目录 node-guessing-game。
然后在该目录下运行以下指令来创建 Node.js 项目:
这个指令会创建 package.json 文件,为 JavaScript 的套件设置档,格式为一个 JSON 对象。
为了方便我们编译 TypeScript 程序和运行 JavaScript 程序,将 package.json 的 scripts 字段修改如下:
{
...
"scripts": {
"build": "tsc index.ts",
"build:watch": "npm run build -- --watch"
}
...
}
如此一来,我们就可以在程序项目的根目录下,运行 npm run build 指令来编译 index.ts。也可以运行 npm run build:watch 来持续监看 TypeScript 的源代码有没有变动,如果有的话就自动编译。
npm run build -- --watch 指令中的 -- 参数,表示要将写在其之后的参数提供给 npm run build 指令对应到的指令,而非提供给 npm 本身。而 tsc 指令加上 --watch 参数,就会去监看输入的文件是否有变动,有的话就会自动编译。
将 TypeScript 安装到 Node.js 项目
考虑到我们的 Node.js 项目可能会由别人来帮忙维护,而别人的开发环境中可能不会安装 TypeScript,又或者他们用的 TypeScript 版本和我们用的相去甚远,而造成 TypeScript 程序无法通过编译。我们应该要将 TypeScript 安装至我们的 Node.js 项目。除上述原因之外,有些 TypeScript 相关的套件也需要项目目录下有 TypeScript 存在才能正确运作。
现在我们已经有了 package.json 设置档,所以可以很轻易地替我们的项目加入依赖套件。在 package.json 设置档中,可以加上 dependencies 字段,来设置这个项目要依赖于哪些套件。设置好之后,只要在程序项目根目录运行 npm install 指令,就可以把这些依赖套件从 npm 的网络空间上下载回来,放置在程序项目根目录的 node_modules 目录中。不过我们通常不需要手动编辑 dependencies 字段,直接使用以下格式的 npm 指令就可以快速地将指定套件加进 dependencies 字段,也会立刻将其下载到 node_modules 目录中。
install 这个子命令可以简写为 i。
我们在第一章安装 tsc 时用的 npm i -g typescript 指令,用了一个 -g 参数,这个是让套件安装到全域的 node_modules 目录,而不是当前的 Node.js 项目中。通常指令工具类的 JavaScript 套件会加上 -g 参数来安装,这样就可以直接在终端机下使用。而若不用 -g 参数来安装指令工具类的 JavaScript 套件,则要透过在 package.json 的 scripts 字段中撰写指令才可以直接(直接使用指令工具的名称而不撰写其路径)调用。
运行以下指令可以在当前 Node.js 项目中安装 TypeScript。
注意以上指令使用 -D 参数,-D 参数即 --save-dev 参数,会将套件保存在 devDependencies 字段下,而不是 dependencies 字段。
devDependencies 字段下的套件,只有在目前这个项目使用 npm install 指令时才会被安装。而 dependencies 字段下的套件,别的套件若有依赖于目前这个套件,则在别的套件项目下使用 npm install 指令时,也会去安装目前这个套件的 package.json 设置档中的 dependencies 字段下的套件。
由于 TypeScript 只会在我们开发目前这个套件时才会用到,用来将 TypeScript 的程序编译为 JavaScript 程序,因此将其加入 devDependencies 字段下即可,不需要加进 dependencies 字段。
撰写 TypeScript 程序
我们可以直接将上一章撰写过的猜数字代码拷贝到目前这个项目中来用。记得源代码文件要存放在程序项目根目录下,文件名为 index.ts,这样才能够被 npm run build 指令编译。
declare const require;
declare const process;
const isBrowser: boolean = typeof window === "object";
function showMessage(text: string): void {
if (isBrowser) {
alert(text);
} else {
console.log(text);
}
}
async function showMessageAndInputText(text: string): Promise<string> {
if (isBrowser) {
return prompt(text);
} else {
console.log(text);
const readline = require("node:readline");
const rl = readline.createInterface({ input: process.stdin });
const lineResolver: Promise<string> = new Promise<string>(resolve => {
rl.on("line", line => resolve(line));
});
const line: string = await lineResolver;
rl.close();
return line;
}
}
async function main(): Promise<void> {
showMessage("Guess the number!");
const secretNumber: number = Math.floor(Math.random() * 100 + 1);
showMessage(`The secret number is: ${secretNumber}`);
while (true) {
const line: string = await showMessageAndInputText("Please input your guess.");
const guess: number = parseInt(line);
if (isNaN(guess)) {
showMessage("Please type a number!");
} else {
showMessage(`You guessed: ${guess}`);
if (guess < secretNumber) {
showMessage("Too small!");
} else if (guess > secretNumber) {
showMessage("Too big!");
} else {
showMessage("You win!");
break;
}
}
}
}
main();
不过很显然地,在撰写完上面的 TypeScript 程序后,运行 npm run build 指令,是会编译失败的。
您的第一个反应可能会去修改 package.json 中的 scripts 字段,将 tsc 指令的部份加上 -t 甚至是 --lib 参数,来让 tsc 能够正确编译我们的 TypeScript 程序。是可以这样做没错,但还有一个更好的作法,那就是添加一个 TypeScript 的设置档。
TypeScript 的设置档
tsc 指令预设会去读取当前工作目录下的 tsconfig.json 文件作为设置档。所以我们可以在 Node.js 项目的根目录中,添加一个 tsconfig.json 文件让它来读取。这个设置档也是 JSON 对象格式,在把它创建出来后,可以先加上以下内容:
{
"compilerOptions": {
}
}
compilerOptions 字段就是用来设置我们在使用 tsc 指令时要加上的额外参数。例如要加上 -t ES6 参数的话,tsconfig.json 的写法如下:
{
"compilerOptions": {
"target": "ES6"
}
}
理论上,我们的猜数字程序只要有了这个设置档就可以被成功编译了,但此时实际运行 npm run build 指令,也还是会编译失败。这是因为,当使用 tsc 指令时,若有指定文件,就不会去读取 tsconfig.json 设置档了。所以说,我们要将 package.json 中 tsc 指令的 index.ts 拿掉。
{
...
"scripts": {
"build": "tsc",
"build:watch": "npm run build -- --watch"
}
...
}
此时运行 npm run build 指令,index.ts 就能够被成功编译。
不过 tsc 是怎么知道要去编译 index.ts 文件的?其实它并不完全知道我们就是要编译 index.ts 文件,而是在预设情况下,它会把工作目录底下包含子目录中的 .ts 和 .tsx 文件都拿来编译,并在 .ts 和 .tsx 文件的所在目录之下,输出 .js 文件。
如果要指定 tsc 编译的文件,就要在 tsconfig.json 设置档中添加 files 字段。这个 files 字段的值是一个字符串数组,每个字符串表示一个文件路径,不能使用 glob 文件路径。如果要使用 glob 文件路径,可以改用 include 字段(还可以搭配 exclude 字段来排除文件)。glob 文件路径简单来说就是一般的文件路径,但能以星号 * 表示同层级下的任意字符,也能以双星号 ** 表示任意层级的目录。
举例来说,因为我们的这个项目只需要编译 index.ts 文件,所以可以将 tsconfig.json 设置档改写如下:
{
"compilerOptions": {
"target": "ES6"
},
"files": [
"index.ts"
]
}
如果想要将 JavaScript 版本降到 ES5,但激活 ES6 的 Promise 对象的话,可以将 tsconfig.json 设置档改写如下:
{
"compilerOptions": {
"target": "ES5",
"lib": [
"dom",
"es5",
"scripthost",
"es2015.promise",
"es2015.iterable"
]
},
"files": [
"index.ts"
]
}
让 TypeScript 支持 Node.js 内置的对象和函数
如果我们的 TypeScript 程序有用到 Node.js 内置的对象和函数的话,上一章提供的方法是利用 declare 关键字来将它们「假声明」出来。虽然这样也可以用,但是我们无法准确地去设置这些被声明出来的对象和函数的类型,也就没有办法在编译阶段时进行有效的类型检查。所以最好还是让 TypeScript 能够直接支持 Node.js。
TypeScript 可以借由安装额外套件的方式来扩充其支持的对象和函数,那么要装什么样的套件才能够让 TypeScript 能够支持 Node.js 呢?
在 TypeScript 生态圈有个很重要的官方开源项目──DefinitelyTyped。这个项目整理了其它 JavaScript 套件暴露(export)的项目,将它们都加上 TypeScript 的类型定义,这些定义都会写在扩展名为 .d.ts 的文件中。我们可以透过在 npmjs.com 搜索 JavaScript 的套件名称,如果有看到该套件有 DT 标示,就代表这个套件在 DefinitelyTyped 上有类型定义,于是我们可以使用 npm i @types/<套件名称> 来安装该套件的类型定义到我们的 TypeScript 程序项目中。
Node.js 本身的常数、函数、对象在 DefinitelyTyped 中也有类型定义,可以运行以下指令来安装:
注意这边是把 @types/node 套件存在 package.json 设置档的 dependencies 字段之中,但如果我们确定我们制作的 TypeScript 程序不会(不适合)被当作函数库来引入,或者说对外并没有与 Node.js 所提供的函数、对象等有所关联的话,将 @types/node 套件存入 devDependencies 字段之中会是比较好的作法。所以事实上,以这个猜数字游戏的项目来说,应该要使用 npm i -D @types/node 指令来安装 @types/node 套件才是比较适当的作法。
不管如何,将 @types/node 套件安装好之后,不需要特别设置 tsc,TypeScript 预设就会从 node_modules 目录中,引用 @types 目录底下的所有 .d.ts 文件。此时在我们的程序项目根目录中运行 npm run build 指令,会发现程序编译失败了。
这是因为我们重复声明了 require 和 process,所以要把 index.ts 文件的最上面的两行 declare 叙述移除掉,才可以成功通过编译。
TypeScript 的编辑器 /IDE (Integrated Development Environment)
有了 tsconfig.json 设置档和 DefinitelyTyped 提供的 .d.ts 文件后,笔者强烈建议使用 Visual Studio Code 等编辑器或是 IDE 来开发 TypeScript 程序,因为它们可以根据 tsconfig.json 设置档的内容和 .d.ts 文件来实时显示 TypeScript 代码有什么问题。
除此之外我们还可以安装 eslint 来协助找出 TypeScript 代码的问题并统一样式。不过这部份并不在本系列文章的讨论范围之内。
严格模式
既然用了 IDE 来撰写 TypeScript,就可以尽量让代码写得更严谨一些。我们可以修改 tsconfig.json 设置档,让 tsc 能用严格的方式来编译 TypeScript 程序。修改方式如下:
{
"compilerOptions": {
...
"strict": true
...
}
...
}
激活 tsc 的 --strict 参数后,在定义函数参数时都必须要明确指定类型,无法直接像以前那样直接被当成任意类型(any)了。
所以我们的猜数字程序要稍微修改一下。
const isBrowser: boolean = typeof window === "object";
function showMessage(text: string): void {
if (isBrowser) {
alert(text);
} else {
console.log(text);
}
}
async function showMessageAndInputText(text: string): Promise<string> {
if (isBrowser) {
return prompt(text);
} else {
console.log(text);
const readline = require("node:readline");
const rl = readline.createInterface({ input: process.stdin });
const lineResolver: Promise<string> = new Promise<string>(resolve => {
rl.on("line", (line: string) => resolve(line));
});
const line: string = await lineResolver;
rl.close();
return line;
}
}
async function main(): Promise<void> {
showMessage("Guess the number!");
const secretNumber: number = Math.floor(Math.random() * 100 + 1);
showMessage(`The secret number is: ${secretNumber}`);
while (true) {
const line: string = await showMessageAndInputText("Please input your guess.");
const guess: number = parseInt(line);
if (isNaN(guess)) {
showMessage("Please type a number!");
} else {
showMessage(`You guessed: ${guess}`);
if (guess < secretNumber) {
showMessage("Too small!");
} else if (guess > secretNumber) {
showMessage("Too big!");
} else {
showMessage("You win!");
break;
}
}
}
}
main();
除了函数参数的类型要明确定义外,原先 undefined 和 null 可以是所有类型的值,但在严格模式下,它们就必须属于另外的类型。例如:
function a(): string {
return null;
}
以上程序在 TypeScript 的严格模式下就要写成:
function a(): string | null {
return null;
}
利用 | 字符来隔开其它可能的类型。null 的类型为 null;undefined 的类型为 undefined。
在我们的猜数字程序中有用到 window 对象的 prompt 方法,这个方法的回传值类型为 string | null。所以我们的程序要修改成以下这样才能通过编译:
const isBrowser: boolean = typeof window === "object";
function showMessage(text: string): void {
if (isBrowser) {
alert(text);
} else {
console.log(text);
}
}
async function showMessageAndInputText(text: string): Promise<string | null> {
if (isBrowser) {
return prompt(text);
} else {
console.log(text);
const readline = require("node:readline");
const rl = readline.createInterface({ input: process.stdin });
const lineResolver: Promise<string> = new Promise<string>(resolve => {
rl.on("line", (line: string) => resolve(line));
});
const line: string = await lineResolver;
rl.close();
return line;
}
}
async function main(): Promise<void> {
showMessage("Guess the number!");
const secretNumber: number = Math.floor(Math.random() * 100 + 1);
showMessage(`The secret number is: ${secretNumber}`);
while (true) {
const line: string | null = await showMessageAndInputText("Please input your guess.");
if (line === null) {
continue;
}
const guess: number = parseInt(line);
if (isNaN(guess)) {
showMessage("Please type a number!");
} else {
showMessage(`You guessed: ${guess}`);
if (guess < secretNumber) {
showMessage("Too small!");
} else if (guess > secretNumber) {
showMessage("Too big!");
} else {
showMessage("You win!");
break;
}
}
}
}
main();
注意程序第 41 行的地方,line 变量的类型为 string | null,但是 parseInt 函数第一个参数的类型必须是 string。那么为什么以上程序还可以通过编译呢?这就是 TypeScript 厉害的地方啦!它可以去检查 line 变量在运行的过程中,有没有透过流程控制来限缩 line 变量的类型范围。由于程序第 43 行到第 45 行,使用了 if 语法来判断 line 变量的值是否在数值和类型上相等于(即 === 操作符)null,如果是的话就利用 continue 叙述直接进行下一次循环的运行。因此在程序第 46 行之后,line 变量的类型只有可能是 string。而因为 TypeScript 在编译时也能够得出这样的结论,所以程序第 47 行是可以通过编译的!
还有一些在激活严格模式时会有差异的地方,只不过我们这边的猜数字程序没有用到,会在之后的章节遇到时再介绍一下。
总结
在这一章节中,我们创建了 Node.js 项目来撰写 TypeScript 程序,学会了如何用 npm 来安装套件,并且透过安装 DefinitelyTyped 提供的套件来扩充 TypeScript,使其能支持 Node.js 和其它的 JavaScript 套件。此外,我们还用了严格模式来撰写 TypeScript 程序。在接下来的章节中,将会对变量、数据类型、函数、程序流程进行更深入的探讨。
下一章:TypeScript 编程语言的基础概念。





