Typescript 类型声明 All-in-one

• 定义类型别名： type MyType = string
• 对类型进行并集（union type）或交集运算

• 进行 OOP 继承和组合： implements 和 extends
• 多次声明同一个 interface 以合并类型

无关优劣，只看语义，我的个人习惯如下：

• 当你需要直接定义一个对象的形状时，选 interface
• 当你很明确地知道自己是在玩弄类型时，选 type

• declare namespace Obj {} 声明一个全局命名空间

  • 用于传统命名空场景，即避免命名冲突，如声明接口类型等
  • 声明全局变量类型（点分法类型），如 jQuery 的类型

// jquery.d.ts
declare namespace $ {
    interface JQuery {
        // 定义 jQuery 方法
        html(content: string): this; // 设置或获取 HTML 内容
        css(property: string, value?: string): this; // 设置或获取 CSS 属性
        on(event: string, handler: (event: Event) => void): this; // 绑定事件处理程序
        // 其他 jQuery 方法...
    }

    // 定义全局 jQuery 函数
    function (selector: string): JQuery;
}

• declare function fn(): Type 声明或重载函数类型

  • 声明全局函数类型
  • 一种另类的函数重载方法：多次声明同名函数的类型签名
• declare var foo: number 声明全局变量类型

• declare class MyClass {} 声明全局 class 的类型

  • 与 class 的区别： declare class 只提供类型定义，不提供具体实现
• declare module 'example-package' {} 在全局范围内补充声明某个模块的类型定义

• declare interface 和 declare type 重新声明已有的类型或接口，表明其存在或修改定义

  • 与直接使用 type 和 interface 的区别：

    • declare 通常用于声明已有的接口或类型，直接使用往往会定义一个新的
    • 在 d.ts 中是否使用 declare 往往没有区别

查找模块类型定义 import a from "a" 的来源，合并所有定义

• 全局模块定义： declare module "a"
• 相对/绝对路径：依次寻找 a.ts , a.d.ts 中的类型定义

• 包引用：

  • 入口文件（包名 alias）：查找包 package.json 中的 types 定义
  • 同名 @types 包下的类型声明
  • 直接引用内部文件：查找对应文件的 .d.ts 文件

导入 CJS 模块时，Typescript 提供了多种语法支持，具体由 tsconfig.json 中的 esModuleInterop 属性开关决定

• 关闭时：严格检验 ESM 模块规范，对于 CommonJS 模块必须使用以下语法

  • import a = require('a') ：NodeJS CJS 引用语法（不推荐）
  • import * as fs from "fs" ：命名空间导出语法，将整个模块作为一个对象引入（对于 ESM 模块也使用此语法）

• 开启后：允许使用 ESM 格式导入 CommonJS 模块，开启后 TS 编译器会对 CJS 模块做一些预处理以支持 ESM 导入

  • 默认导出模式： import React from "react"

那么， esModuleInterop 做了什么工作呢？其实非常简单。

下面的例子中 tsc 的 target 都是 commonjs

• ESM 模块和 CJS 模块在引用时的区别在于是从 default 中取值还是直接从对象中取值，参考下面的代码（未开启 esModuleInterop）

// 编译前
import fs from 'fs';
import * as fsBak from 'fs';

fs.copyFile('', '', () => {});
fsBak.copyFile('', '', () => {});

// 编译后：CJS
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const fs_1 = require("fs");
const fsBak = require("fs");
fs_1.default.copyFile('', '', () => { });
fsBak.copyFile('', '', () => { });

• 问题在于 CJS 中没有 default 导出，那么就在运行时加上一段代码来手动添加即可，这就是 esModuleInterop 属性开启后 tsc 完成的工作。开启后，对 CJS 的命名空间导入和默认导入行为都有改变，即将整个导出对象赋值给 default 属性

  • 对于命名空间导入 import * as React from 'react' ，会生成 __importStar 辅助函数，为 CJS 引入对象添加 default 属性，ESM 对象则不做处理，具体示例如下：

  // 编译前
  import * as fsBak from 'fs';
  
  fsBak.copyFile('', '', () => {});
  
  // 编译后
  "use strict";
  var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function (o, v) {
    Object.defineProperty(o, "default", { enumerable: true, value: v });
  }) : function (o, v) {
    o["default"] = v;
  });
  var __importStar = (this && this.__importStar) || function (mod) {
    if (mod && mod.__esModule) return mod;
    var result = {};
    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
    __setModuleDefault(result, mod);
    return result;
  };
  Object.defineProperty(exports, "__esModule", { value: true });
  const fsBak = __importStar(require("fs"));
  fsBak.copyFile('', '', () => { });

  • 对于默认导入 import React from 'react ，会生成 __importDefault 辅助函数，将 CJS 导出整个赋值给 default 属性，ESM 则不做处理，与上面的区别在于返回对象是仅包含 default 属性的新对象

  // 编译前
  import fs from 'fs';
  
  fs.copyFile('', '', () => {});
  
  // 编译后
  "use strict";
  var __importDefault = (this && this.__importDefault) || function (mod) {
    return (mod && mod.__esModule) ? mod : { "default": mod };
  };
  Object.defineProperty(exports, "__esModule", { value: true });
  const fs_1 = __importDefault(require("fs"));
  fs_1.default.copyFile('', '', () => { });