编写高质量的 TypeScript 声明文件是确保 TypeScript 正确理解和利用 JavaScript 库或代码的关键步骤。下面我将展示如何书写这些不同类型的声明文件，并附上适当的 API 文档和示例。
1. 全局变量
假设要声明一个全局变量 MY_GLOBAL，它是一个字符串类型。
TypeScript 声明文件
// global.d.ts
// 通过 `declare var` 声明全局变量
declare var MY_GLOBAL: string;
API 文档
// global.d.ts
/**
* 全局变量 MY_GLOBAL 的描述
*/
declare var MY_GLOBAL: string;
示例
// Usage example
console.log(MY_GLOBAL.toUpperCase()); // 使用全局变量
2. 全局函数
假设要声明一个全局函数 globalFunction，它接受一个字符串参数并返回一个字符串。
TypeScript 声明文件
// global.d.ts
// 通过 `declare function` 声明全局函数
declare function globalFunction(input: string): string;
API 文档
// global.d.ts
/**
* 全局函数 globalFunction 的描述
* @param input 输入字符串
* @returns 返回转换后的字符串
*/
declare function globalFunction(input: string): string;
示例
// Usage example
const result = globalFunction("hello"); // 调用全局函数
console.log(result);
3. 带属性的对象
假设要声明一个对象 MyObject，它有一个属性 name 和一个方法 greet。
TypeScript 声明文件
// myObject.d.ts
// 通过 `declare namespace` 声明对象和方法
declare namespace MyObject {
let name: string;
function greet(): void;
}
API 文档
// myObject.d.ts
/**
* 对象 MyObject 的描述
*/
declare namespace MyObject {
/**
* 属性：名字
*/
let name: string;
/**
* 方法：问候
*/
function greet(): void;
}
示例
// Usage example
MyObject.name = "Alice"; // 设置属性
MyObject.greet(); // 调用方法
4. 函数重载
假设要声明一个函数 calculate，它根据传入参数的类型不同有不同的行为。
TypeScript 声明文件
// calculate.d.ts
// 通过函数重载声明多种函数签名
declare function calculate(x: number, y: number): number;
declare function calculate(x: string, y: string): string;
API 文档
// calculate.d.ts
/**
* 函数 calculate 的描述
* @param x 第一个参数
* @param y 第二个参数
* @returns 计算结果
*/
declare function calculate(x: number, y: number): number;
declare function calculate(x: string, y: string): string;
示例
// Usage example
const result1 = calculate(10, 5); // 调用第一个重载
const result2 = calculate("hello", "world"); // 调用第二个重载
console.log(result1, result2);
5. 可重用类型（接口）
假设要声明一个接口 Person，描述一个人的基本信息。
TypeScript 声明文件
// person.d.ts
// 通过 `interface` 声明接口
interface Person {
name: string;
age: number;
greet(): void;
}
API 文档
// person.d.ts
/**
* 接口 Person 描述一个人的基本信息
*/
interface Person {
/**
* 姓名
*/
name: string;
/**
* 年龄
*/
age: number;
/**
* 问候方法
*/
greet(): void;
}
示例
// Usage example
const person: Person = {
name: "Alice",
age: 30,
greet() {
console.log(`Hello, my name is ${this.name}.`);
}
};
person.greet(); // 调用接口方法
6. 可重用类型（类型别名）
假设要声明一个类型别名 Coordinates，用于描述坐标的类型。
TypeScript 声明文件
// coordinates.d.ts
// 通过 `type` 声明类型别名
type Coordinates = {
x: number;
y: number;
};
API 文档
// coordinates.d.ts
/**
* 类型别名 Coordinates 描述一个坐标点
*/
type Coordinates = {
/**
* x 坐标
*/
x: number;
/**
* y 坐标
*/
y: number;
};
示例
// Usage example
function printCoordinates(coords: Coordinates) {
console.log(`Coordinates: (${coords.x}, ${coords.y})`);
}
const point: Coordinates = { x: 10, y: 20 };
printCoordinates(point); // 使用类型别名作为参数类型
7. 组织类型
假设要声明一个类 Animal，它有一个构造函数和一些实例方法。
TypeScript 声明文件
// animal.d.ts
// 通过 `declare class` 声明类
declare class Animal {
constructor(name: string);
name: string;
eat(food: string): void;
}
API 文档
// animal.d.ts
/**
* 类 Animal 描述一个动物
*/
declare class Animal {
/**
* 构造函数，创建一个动物实例
* @param name 动物的名字
*/
constructor(name: string);
/**
* 属性：名字
*/
name: string;
/**
* 方法：吃东西
* @param food 食物的名字
*/
eat(food: string): void;
}
示例
// Usage example
const cat = new Animal("Kitty");
cat.eat("fish"); // 调用实例方法
console.log(cat.name); // 访问属性
总结
编写高质量的 TypeScript 声明文件需要结合清晰的 API 文档和实际示例，确保用户可以轻松理解和正确使用你的库。通过合理的组织和描述，可以提升代码的可读性、可维护性，以及 TypeScript 的类型推断和类型安全检查效果。