TypeScript 与 JavaScript 互操作：类型声明文件

为什么需要类型声明文件

当你在一个 TypeScript 项目中使用第三方 JavaScript 库时，TypeScript 编译器无法自动理解这些库提供的 API。没有类型信息，IDE 无法提供代码补全，调用函数时得不到参数提示，更糟糕的是——类型错误要到运行时才会暴露。

类型声明文件（以 .d.ts 为后缀）就是来解决这个问题的。它告诉 TypeScript：「这个 JavaScript 模块导出什么、函数接受什么参数、返回值是什么类型」。本质上，类型声明文件只包含类型信息，不包含任何实际运行代码。

// JavaScript 库 (实际运行时执行的代码)
function greet(name) {
  return "Hello, " + name;
}

// 类型声明文件 (仅供 TypeScript 编译器参考)
declare function greet(name: string): string;

当 TypeScript 找到这个声明后，它就知道 greet 函数需要一个字符串参数，返回值也是字符串。之后你在调用 greet(123) 时，TypeScript 会立即报错，因为类型不匹配。

类型声明文件的核心语法

变量声明

使用 declare 关键字告诉 TypeScript 某个变量已经存在。

// 声明全局变量
declare const API_BASE_URL: string;
declare const MAX_CONNECTIONS: number;

// 声明全局对象及其属性
declare const config: {
  readonly theme: string;
  debugMode: boolean;
};

readonly 修饰符表示该属性是只读的，尝试赋值会导致编译错误。

函数声明

函数声明需要明确参数类型和返回值类型。

// 普通函数
declare function fetchData<T>(url: string): Promise<T>;

// 函数重载：同一个函数名，不同参数组合
declare function format(value: string): string;
declare function format(value: number, precision: number): string;

函数重载在声明文件中很常见。TypeScript 编译器会从上到下匹配，第一个匹配的签名会被使用。

类声明

declare class User {
  constructor(name: string, age: number);

  name: string;
  age: number;

  getProfile(): string;
  static createAnonymous(): User;
}

静态方法和属性使用 static 关键字修饰。

模块声明

对于 CommonJS 或 ES Module 导出的模块：

// 默认导出
declare export default function hello(name: string): string;

// 命名导出
declare export function goodbye(name: string): string;
declare export const version: string;

// 命名空间导出
declare export namespace Utils {
  function random(min: number, max: number): number;
  const PI: number;
}

枚举和类型别名

// 枚举
declare enum LogLevel {
  DEBUG = 0,
  INFO = 1,
  WARN = 2,
  ERROR = 3
}

// 类型别名
declare type UserID = string | number;
declare type Callback = (data: unknown) => void;

创建类型声明文件

步骤 1：确定声明文件的位置

TypeScript 会自动查找以下位置的 .d.ts 文件：

如果你的项目没有专门的类型目录，在项目根目录创建一个 types 文件夹是最简单的做法。

步骤 2：编写声明内容

假设你有一个 JavaScript 工具库 math-utils.js：

// math-utils.js
function add(a, b) {
  return a + b;
}

function multiply(a, b) {
  return a * b;
}

const PI = 3.14159;

module.exports = { add, multiply, PI };

对应的类型声明文件 math-utils.d.ts：

declare module 'math-utils' {
  export function add(a: number, b: number): number;
  export function multiply(a: number, b: number): number;
  export const PI: number;
}

declare module '模块名' 是声明第三方模块的标准写法。模块名必须与实际导入时使用的字符串完全一致。

步骤 3：在 tsconfig.json 中配置

如果你的类型声明文件不在默认查找路径内，需要在 tsconfig.json 中指定：

{
  "compilerOptions": {
    "typeRoots": ["./types", "./node_modules/@types"],
    "types": ["node"]  // 明确指定需要哪些 @types 包
  }
}

typeRoots 指定 TypeScript 查找类型声明文件的根目录。types 数组则明确列出哪些 @types 包需要包含，默认为全部。

实战：为一个复杂库编写声明

假设你正在为图表库 simple-chart 编写类型声明。这个库提供以下功能：

// 创建图表实例
const chart = simpleChart.create('#container', {
  type: 'line',
  width: 800,
  height: 600,
  data: [10, 25, 30, 50],
  options: {
    animate: true,
    colors: ['#ff0000', '#00ff00']
  }
});

// 绑定事件
chart.on('data-point-click', (point) => {
  console.log(point.x, point.y);
});

// 导出图表
chart.exportToPNG('my-chart.png');

对应的类型声明文件：

declare module 'simple-chart' {
  interface ChartOptions {
    type: 'line' | 'bar' | 'pie';
    width: number;
    height: number;
    data: number[];
    options?: {
      animate?: boolean;
      colors?: string[];
      title?: string;
    };
  }

  interface DataPoint {
    index: number;
    x: number;
    y: number;
    value: number;
  }

  interface ChartEventHandlers {
    'data-point-click': (point: DataPoint) => void;
    'data-hover': (point: DataPoint) => void;
    'render-complete': () => void;
  }

  class Chart {
    constructor(selector: string, options: ChartOptions);

    on<K extends keyof ChartEventHandlers>(
      event: K, 
      handler: ChartEventHandlers[K]
    ): this;

    setData(data: number[]): void;
    updateOptions(options: Partial<ChartOptions>): void;
    exportToPNG(filename: string): Promise<void>;

    destroy(): void;
  }

  namespace create {
    function create(selector: string, options: ChartOptions): Chart;
  }

  export function create(selector: string, options: ChartOptions): Chart;
  export { Chart };
}

这个例子展示了几个重要技巧：

可选属性：使用 options?: { ... } 和 animate?: boolean 标记可选属性。调用方可以省略这些属性。

泛型接口：Partial<T> 是 TypeScript 内置工具类型，表示所有属性都变成可选的。

this 链式调用：方法返回 this 支持链式调用，TypeScript 正确推断类型。

命名空间与函数同名：当模块既有函数导出又有类导出时，使用命名空间组织静态成员。

发布类型声明到 npm

方法一：绑定到 package.json

在包的 package.json 中指定主类型文件：

{
  "name": "my-awesome-library",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts"
}

TypeScript 会自动读取 types 字段指向的文件。文件名通常是 index.d.ts，与 main 指向的入口文件对应。

方法二：使用 @types 包

对于不打算在源码中包含类型声明的库，可以单独发布 @types 包。包名必须与原库名一致，例如原库是 lodash，类型包就是 @types/lodash。

这种方式的优点是类型定义可以独立更新，不必同步发布主库。

方法三：利用 Bundle

如果你的源码本身就是 TypeScript 编写，直接在 tsconfig.json 中设置 declaration: true，编译器会自动生成 .d.ts 文件：

{
  "compilerOptions": {
    "declaration": true,
    "declarationDir": "./dist",
    "outDir": "./dist"
  }
}

生成的类型声明文件会随 npm 包一起发布，用户无需额外安装类型包。

常见问题与解决方案

问题 1：声明文件不生效

首先确认文件扩展名是 .d.ts 而不是 .ts。然后检查 tsconfig.json 中的配置：

{
  "compilerOptions": {
    "baseUrl": "./",
    "typeRoots": ["./types"],
    "paths": {
      "my-library": ["./types/my-library.d.ts"]
    }
  }
}

如果模块名有特殊前缀后缀，paths 配置可以显式指定声明文件位置。

问题 2：全局声明冲突

当多个声明文件定义了同名的全局变量时，会出现冲突。解决方案是使用模块封装：

// 错误：多个文件都 declare const settings: { ... } 会冲突

// 正确：使用 namespace 包裹
declare namespace MyLib {
  const settings: { debug: boolean };
}

问题 3：动态导入的类型

对于 import() 返回的 Promise 类型：

declare function loadModule<T>(modulePath: string): Promise<T>;

// 使用时
const utils = await loadModule<typeof import('./math-utils')>('./math-utils');

问题 4：处理复杂回调类型

当回调函数有多个可选参数时：

declare function handleRequest(
  callback: (error: Error | null, result?: unknown) => void
): void;

result 是可选的，放在 error 后面表示成功的场景。

高级模式：环境声明与全局增强

augment 声明

当你需要为已有的类型添加新成员时，使用三斜线指令引用原始声明：

/// <reference types="express" />

// 为 Express Request 添加自定义属性
declare namespace Express {
  interface Request {
    user?: {
      id: string;
      role: 'admin' | 'user';
    };
  }
}

三斜线指令 /// <reference types="包名" /> 用于引入 @types 包的环境声明。

global 声明

declare global 用于在模块外部扩展全局类型：

// string-extensions.d.ts
export {};

declare global {
  interface String {
    padCenter(length: number, fillChar?: string): string;
  }
}

// 现在所有 string 都有 padCenter 方法
"hello".padCenter(10, '-');  // "--hello---"

export {} 是关键，它告诉 TypeScript 这是一个模块文件，否则代码会被当作全局脚本。

最佳实践总结

编写类型声明文件时，遵循以下原则能大幅提升可用性：

精确优于宽泛：尽量使用具体的类型而非 any。string | number 比 unknown 或 any 更有价值。

文档注释：使用 /** 描述 */ 为函数、参数、返回值添加说明：

/**
 * 发起 HTTP 请求
 * @param url - 请求地址
 * @param options - 可选的请求配置
 * @returns Promise，解析为响应数据
 */
declare function fetch<T>(url: string, options?: RequestOptions): Promise<T>;

暴露复杂类型：当类型较复杂时，为接口命名并导出，方便用户引用和复用。

渐进式兼容：对于不确定的类型，可以先用 any 或 unknown，后续再细化。

类型声明文件是 TypeScript 生态系统的基石。一份准确的类型声明能让用户在完全脱离文档的情况下顺畅使用你的库，同时为 IDE 提供可靠的代码补全和类型检查能力。