【TS】 TypeScript声明文件：打通JavaScript和TypeScript的桥梁

 TypeScript 声明文件的讲解：
 
TypeScript 声明文件（Declaration File）在 TypeScript 项目中具有举足轻重的地位，它是连接 TypeScript 严格的类型系统与外部无类型或类型不明确的 JavaScript 代码的关键纽带。
 
声明文件的核心价值在于为 TypeScript 编译器提供必要的类型信息，使得在使用外部 JavaScript 库、模块或代码片段时，能够进行精确的类型检查和智能的代码提示，从而显著提高代码的质量、可维护性以及开发效率。
 
让我们通过一系列丰富多样且逐步深入的示例来透彻理解声明文件的各个方面。
 
首先，考虑一个基础但常见的 JavaScript 函数库  simpleFunctions.js  ，其中包含了以下几个简单函数：
 
 

function sum(a, b) {
  return a + b;
}

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

function divide(a, b) {
  if (b === 0) {
    throw new Error('Division by zero is not allowed.');
  }
  return a / b;
}

 
 
为了在 TypeScript 项目中有效地使用这些函数，并确保类型的安全性和准确性，我们创建一个对应的声明文件  simpleFunctions.d.ts  ：
 
 

declare function sum(a: number, b: number): number;
declare function multiply(a: number, b: number): number;
declare function divide(a: number, b: number): number;

 
 
在这个声明文件中，我们明确地指定了每个函数的参数类型均为  number  ，并且返回值类型也为  number  。这使得在 TypeScript 代码中调用这些函数时，编译器能够检查传入的参数是否符合预期的类型，如果类型不匹配，将会给出相应的错误提示。
 
接下来，我们看一个更复杂一些的情况，假设有一个 JavaScript 库  complexObjectLibrary.js  ，其中定义了一个包含多个方法和属性的对象：
 
 

function createComplexObject(name, age) {
  return {
    name: name,
    age: age,
    greet() {
      console.log(`Hello, my name is ${this.name} and I am ${this.age} years old.`);
    },
    updateAge(newAge) {
      this.age = newAge;
    }
  };
}

 
 
相应的声明文件  complexObjectLibrary.d.ts  可以这样来编写：
 
 

interface ComplexObject {
  name: string;
  age: number;
  greet(): void;
  updateAge(newAge: number): void;
}

declare function createComplexObject(name: string, age: number): ComplexObject;

 
 
在此声明文件中，我们首先定义了一个名为  ComplexObject  的接口，详细描述了对象的属性和方法的类型。然后，声明了  createComplexObject  函数，明确其参数类型以及返回值的类型为我们定义的  ComplexObject  接口。
 
再深入一步，考虑一个包含类和继承关系的 JavaScript 库  classHierarchy.js  ：
 
 

function BaseClass(property1) {
  this.property1 = property1;
}

BaseClass.prototype.baseMethod = function() {
  console.log(`Base method called with property1: ${this.property1}`);
}

function DerivedClass(property1, property2) {
  BaseClass.call(this, property1);
  this.property2 = property2;
}

DerivedClass.prototype = Object.create(BaseClass.prototype);
DerivedClass.prototype.constructor = DerivedClass;

DerivedClass.prototype.derivedMethod = function() {
  console.log(`Derived method called with property2: ${this.property2}`);
}

 
 
对应的声明文件  classHierarchy.d.ts  可能如下所示：
 

class BaseClass {
  constructor(property1: string);
  property1: string;
  baseMethod(): void;
}

class DerivedClass extends BaseClass {
  constructor(property1: string, property2: number);
  property2: number;
  derivedMethod(): void;
}
 

 
在这个声明文件中，我们清晰地定义了基类  BaseClass  和派生类  DerivedClass  的结构，包括构造函数的参数类型、实例属性的类型以及方法的返回类型。这种详细的类型定义使得在 TypeScript 中使用这些类时，能够充分利用类型系统的优势，避免潜在的类型错误。
 
现在，让我们探讨一个涉及模块和命名空间的 JavaScript 库  moduleNamespace.js  ：
 
 

(function() {
  function internalFunction() {
    // 内部实现
  }

  namespace MyNamespace {
    export function publicFunction1() {
      // 公共函数 1 的实现
    }

    export function publicFunction2() {
      // 公共函数 2 的实现
    }
  }
})();

 
 
相应的声明文件  moduleNamespace.d.ts  可以这样构建：
 
 

declare namespace MyNamespace {
  function publicFunction1(): void;
  function publicFunction2(): void;
}

 
 
通过这样的声明，我们明确了命名空间  MyNamespace  中公开可用的函数及其类型。
 
此外，如果存在与全局对象或窗口对象相关的 JavaScript 代码，例如：
 
 

window.globalSettings = {
  theme: 'light',
  fontSize: 14
};

window.performGlobalAction = function() {
  // 全局操作的实现
};

 
 
对应的声明文件可以是这样：
 
 

interface GlobalSettings {
  theme: string;
  fontSize: number;
}

declare var globalSettings: GlobalSettings;
declare function performGlobalAction(): void;

 
 
通过上述广泛而深入的示例，我们全面展示了 TypeScript 声明文件在处理各种不同结构和复杂度的 JavaScript 代码时的强大能力和灵活性。它能够为简单的函数、复杂的对象、类层次结构、模块、命名空间以及全局对象提供准确且详尽的类型定义，确保 TypeScript 项目在与外部 JavaScript 代码集成时保持高度的类型安全性和开发的便利性。