使用JSDoc可为JavaScript数组参数添加类型注解，提升代码可读性和工具支持。1. 基础数组类型用{number[]}或{Array<number>}；2. 多维数组通过叠加[]表示，如二维数组{number[][]}；3. 对象数组可用{Object[]}或指定结构如{ {id: number, name: string}[] }；4. 混合类型使用联合类型，如{(string|number)[]}；5. 可选参数在参数名外加方括号[b]，并可标注为{number[] | null}等可能为空的类型。配合VS Code或TypeScript时，能实现良好的类型检查与智能提示，有助于团队协作和维护。
在JavaScript中使用注解（通常是通过JSDoc）可以为函数参数、返回值等添加类型信息，提升代码可读性和维护性。虽然JavaScript是动态类型语言，但通过JSDoc可以在开发阶段提供类型检查支持，尤其配合TypeScript或现代编辑器（如VS Code）时效果更佳。
数组类型的基本注解语法
使用@param标签标注函数参数时，可以通过方括号[]或Array<T>语法来指定数组类型。
以下是最常见的两种写法：
- 基础数组类型：@param {number[]} numbers - 数字数组
-
泛型数组写法：@param {Array
} names - 字符串数组
示例代码：
/**
* 计算数字数组的总和
* @param {number[]} numbers - 要求和的数字数组
* @returns {number} 总和
*/
function sum(numbers) {
return numbers.reduce((acc, num) => acc + num, 0);
}
标注多维数组
对于二维或更高维度的数组，可在类型后叠加[]。
- @param {number[][]} matrix - 二维数字数组
- @param {string[][][]} cube - 三维字符串数组
示例：
wechat-article-extraction-mp-weixin-qq-com news-webpage-cleaning blog-post-parsing metadata-extraction-title-author-date multiple-output-formats-markdown-json-plain-text batch-processing-support
下载
基于三引擎设计，从微信文章、新闻和博客网页提取干净内容，支持标题作者日期元数据，多格式和批量处理。
/**
* 获取二维数组中的最大值
* @param {number[][]} matrix - 二维数字数组
* @returns {number} 最大值
*/
function maxInMatrix(matrix) {
return Math.max(...matrix.flat());
}
标注混合类型或对象数组
当数组包含对象或其他复杂类型时，可以结合{}或自定义类型名进行注解。
- @param {Object[]} users - 对象数组
- @param {{id: number, name: string}[]} users - 具体结构的对象数组
- @param {(string|number)[]} values - 混合类型的数组
示例：
/**
* 打印用户列表
* @param {{id: number, name: string}[]} users - 用户对象数组
*/
function printUsers(users) {
users.forEach(user => {
console.log(`${user.id}: ${user.name}`);
});
}
可选参数与默认值的注解
如果数组参数是可选的，使用方括号[]包裹参数名，并标明类型为可为空。
/**
* 合并两个数组
* @param {number[]} a - 第一个数组
* @param {number[]} [b] - 可选的第二个数组
* @returns {number[]} 合并后的数组
*/
function concatArrays(a, b) {
return b ? a.concat(b) : a;
}
也可以标注为可能为 null 或 undefined：
@param {number[] | null} list基本上就这些常用方式。合理使用JSDoc注解数组类型，能让团队协作更顺畅，也能让工具自动补全和提示更准确。不复杂但容易忽略细节，建议在关键函数上坚持使用。
