如何在 JSDoc 中标准定义递归对象类型-js教程-PHP中文网

如何在 JSDoc 中标准定义递归对象类型

本文介绍使用 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 为辅。