TypeScript 如何写 d.ts 文件
做前端开发的朋友，肯定都遇过这样的糟心事：好不容易引入一个别人写的工具库，敲代码的时候，编辑器却疯狂标红，一会儿说“找不到这个变量类型”，一会儿提示“方法参数不对”——其实问题大概率出在缺少.d.ts文件上。这个文件就是TypeScript的“类型说明书”，专门给TypeScript编译器和编辑器当“翻译官”，让它能看懂普通JS代码的逻辑。
很多人觉得.d.ts是“高手才用的复杂文件”，其实完全不是，它的作用就是把JS里的函数、变量、类这些东西，用TypeScript能懂的“类型话”讲清楚，就像给陌生的零食写配料表一样，让吃的人一眼知道成分。
---
最基础的：给单个函数写d.ts
先从最简单的场景学起：假设你写了一个纯JS的工具函数，用来计算商品的折扣价，代码是这样的：
`javascript
// discount.js
function calculateDiscount(price, discountRate) {
return price * (1 - discountRate);
}
module.exports = calculateDiscount;
`
现在你要给这个函数写.d.ts，只需要说明：这个函数接收两个参数，第一个是数字（商品原价），第二个也是数字（折扣比例，比如0.8就是打8折），返回值还是数字。对应的.d.ts文件（名字要和JS文件对应，叫discount.d.ts）可以这么写：
`typescript
declare function calculateDiscount(price: number, discountRate: number): number;
export = calculateDiscount;
`
是不是很简单？就像给函数贴了个“参数+返回值”的小标签，TypeScript拿到这个文件，就再也不会乱飘红了。
---
进阶一点：给类写d.ts
如果你的JS代码是个带属性的类呢？比如做了一个管理购物车的类：
`javascript
// cart.js
class ShoppingCart {
constructor() {
this.items = [];
}
addItem(name, price) {
this.items.push({ name, price });
}
getTotal() {
return this.items.reduce((sum, item) => sum + item.price, 0);
}
}
module.exports = ShoppingCart;
`
对应的.d.ts就要把类的结构说清楚：类有哪些属性，哪些方法，方法的参数和返回值是什么类型：
`typescript
declare class ShoppingCart {
items: Array<{ name: string; price: number }>;
constructor();
addItem(name: string, price: number): void;
getTotal(): number;
}
export = ShoppingCart;
`
这里的Array<{ name: string; price: number }>就像给购物车的每一件商品写了“名字是字符串、价格是数字”的说明，TypeScript不仅能看懂购物车的结构，还能在你敲代码时自动补全addItem和getTotal，不用每次查文档。
---
实用小技巧：处理可选参数和默认值
日常开发里，函数参数偶尔会有可选的情况，比如刚才的折扣函数，如果你想让用户可以不传折扣比例，默认打9折，那原来的JS代码可以改成：
`javascript
function calculateDiscount(price, discountRate = 0.9) {
return price * (1 - discountRate);
}
`
对应的.d.ts里，只需要在可选参数后面加一个?就可以了，不用管默认值的具体数字：
`typescript
declare function calculateDiscount(price: number, discountRate?: number): number;
`
如果是对象参数，比如传一个配置对象，就更简单了，直接把对象里的属性标清楚，缺的就是可选，比如：
`typescript
// 比如传配置，只传price也可以
declare function calculateDiscount(config: { price: number; discountRate?: number }): number;
`
其实.d.ts的核心逻辑就是“说清楚每一个东西的类型”，不用搞复杂的语法，哪怕是新手，照着JS的结构一点点对应着写，最多十几分钟就能搞定一个小工具的类型文件。现在很多热门库都自带.d.ts，但如果是自己写的内部工具，学会写这个文件，就能让整个项目的TypeScript体验顺畅太多。