本文介绍使用 JSDoc 的 @typedef 标签定义递归对象形状的规范方法，支持任意深度嵌套结构（如树形人员数据或带缩进的富文本节点），无需额外类声明即可实现类型自引用与 IDE 智能提示。
本文介绍使用 jsdoc 的 `@typedef` 标签定义递归对象形状的规范方法，支持任意深度嵌套结构（如树形人员数据或带缩进的富文本节点），无需额外类声明即可实现类型自引用与 ide 智能提示。
在 JavaScript 项目中使用 JSDoc 进行类型注解时，处理递归结构（例如具有 children 数组且每个子项自身符合相同结构的对象）是一个常见但易出错的需求。直接在 @param 中内联书写递归引用（如 { children: person[] }）会导致解析失败，因为 JSDoc 不支持未声明标识符的前向引用。
✅ 正确做法是借助 @typedef 显式声明命名类型，并在定义中引用自身，从而形成合法的递归类型：
/**
* @typedef Person
* @type {object}
* @property {string} firstName
* @property {string} lastName
* @property {Person[]} [children] - 可选的子节点数组，每个元素均为 Person 类型
*/
/**
* 处理嵌套人员数据的函数
* @param {Person} person - 根级人员对象，支持无限层级 children 嵌套
*/
function processPerson(person) {
console.log(`${person.firstName} ${person.lastName}`);
if (Array.isArray(person.children)) {
person.children.forEach(processPerson); // 递归调用
}
}你也可以采用更紧凑的内联 @typedef 写法（适用于简单结构）：
dmap-jsapi-skill
下载
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
/**
* @typedef {{firstName: string, lastName: string, children?: Person[]}} Person
*/
/**
* @param {Person} person
*/⚠️ 注意事项：
- 类型名（如
Person）需先定义、后引用，确保@typedef出现在所有使用它的@param/@returns之前； - 推荐使用
@property形式定义，语义更清晰、支持更多元信息（如可选标记[children]、描述文字），也更利于生成文档； - 当前主流工具链（VS Code、WebStorm、JSDoc CLI、TypeScript 5.0+ 的 JSDoc 支持）均能正确识别此类递归
@typedef，提供跳转、补全与错误检查； - 若项目同时使用 TypeScript，该 JSDoc 类型可与
.d.ts文件共存，但注意避免命名冲突——JSDoc 中的@typedef不会自动导出为 TS 类型（参见 TypeScript #46011），如需跨语言复用，建议以.d.ts为主，JSDoc 为辅。
总结：@typedef 是 JSDoc 中定义递归对象形状的标准、轻量且兼容性良好的方案。它既保持了纯 JavaScript 项目的简洁性，又为开发者提供了接近静态类型的开发体验。
