一个简单的JavaScript工具函数编写声明文件实例

当然。为一个简单的JavaScript工具函数编写声明文件，关键在于准确地描述函数签名（参数类型和返回值类型）。下面将通过一个完整的实例来演示。

📦 实例背景

假设有一个简单的JavaScript工具库文件 string-utils.js，它包含两个函数：

1. truncate(str, length)：将字符串截断到指定长度，并添加“…”后缀。
2. capitalize(str)：将字符串的首字母大写。

// string-utils.js (原始的JavaScript文件)
function truncate(str, length) {
    if (str.length > length) {
        return str.substring(0, length) + '...';
    }
    return str;
}

function capitalize(str) {
    if (!str) return '';
    return str.charAt(0).toUpperCase() + str.slice(1);
}

// 假设它以CommonJS方式导出（这是最常见的情况）
module.exports = {
    truncate: truncate,
    capitalize: capitalize
};

📝 编写声明文件 (string-utils.d.ts)

需要创建一个同名的声明文件 string-utils.d.ts。根据原JS文件的导出方式，有几种写法：

方式一：匹配CommonJS导出（最常用）

如果原文件使用 module.exports 导出，声明文件应使用 export = 语法。

// string-utils.d.ts
/**
 * 将字符串截断到指定长度，如果超出则添加“...”
 * @param str - 原始字符串
 * @param length - 需要截断到的长度
 * @returns 处理后的字符串
 */
declare function truncate(str: string, length: number): string;

/**
 * 将字符串的首字母大写
 * @param str - 原始字符串
 */
declare function capitalize(str: string): string;

// 声明导出的成员，与JS文件中的module.exports对应
export = {
    truncate,
    capitalize
};

方式二：使用ES模块导出（如果JS文件使用export）

如果原文件使用ES6的 export 语法，声明文件也应使用ES模块语法。

// string-utils.d.ts
// 使用具名导出（Named Exports）
export function truncate(str: string, length: number): string;
export function capitalize(str: string): string;

// 或者如果默认导出一个对象
// export default { truncate, capitalize };

🔧 在TypeScript中使用

将 string-utils.js 和 string-utils.d.ts 放在同一目录下。现在，你可以在TypeScript文件中导入并使用它，并获得完整的类型检查和智能提示。

// app.ts
import stringUtils = require('./string-utils'); // CommonJS方式导入
// 或使用ES模块导入: import * as stringUtils from './string-utils';

const longText = '这是一段非常长的文本内容，需要进行截断处理。';

// 使用函数，享受类型提示！
const truncated = stringUtils.truncate(longText, 10);
console.log(truncated); // 输出：这是一段非常长的...

const capitalized = stringUtils.capitalize('hello world');
console.log(capitalized); // 输出：Hello world

// TypeScript会在编译时捕获以下类型错误：
// stringUtils.truncate(123, 10); // 错误：参数“123”的类型不能赋给类型“string”
// stringUtils.capitalize(); // 错误：应有 1 个参数，但获得 0 个

🎯 高级场景与关键点

1. 可选参数和默认值：

   // 如果length是可选的，且有默认值80
   declare function truncate(str: string, length?: number): string;
   // 或更精确地描述默认值（在JSDoc中说明，类型系统不直接表示默认值）
   

2. 函数重载：
   如果函数有多种调用方式，可以使用重载。

   // 重载：可以接受一个字符串数组
   declare function capitalize(str: string): string;
   declare function capitalize(strs: string[]): string[];
   // 实现签名（在声明文件中通常省略具体实现）
   

3. 声明全局函数（适用于通过

💡 验证声明文件

编写完成后，一个简单的验证方法是：在同一个目录下创建一个临时的 .ts 文件，尝试导入并使用这些函数。如果IDE（如VSCode）能提供准确的自动完成，并且 tsc 编译器没有报类型错误，那么声明文件基本就是正确的。

📚 总结

为JavaScript工具函数编写声明文件的核心步骤是：

1. 分析：确定原JS文件中函数的参数个数、类型和返回值。
2. 翻译：用TypeScript的类型语法（: string, : number 等）逐个定义函数签名。
3. 导出：根据原文件的模块系统（CommonJS或ES Module），使用对应的导出语法（export = 或 export）。
4. 放置：将 .d.ts 文件放在与 .js 文件相同的目录下，TypeScript编译器会自动发现它。

通过这个简单的例子，可以将同样的模式应用到更复杂的函数、对象、类甚至整个库上。