使用jsDoc可为javaScript复杂对象提供类型提示。1. 用@param标注嵌套对象结构，如user.id、user.profile.email；2. 用@typedef定义可复用类型，如UserProfile和User；3. 支持数组、可选属性和联合类型，如User[]、String|NULL、[total]。通过JSDoc能提升代码可读性和ide智能提示，适合大型项目协作。

在 javascript 中，虽然没有原生的“注解”（Annotation）机制像 Java 那样，但在使用 JSDoc 时，我们可以通过注释来为复杂对象结构添加类型说明，帮助开发者理解参数、返回值的结构，也能被 IDE 和 typescript 正确识别。

1. 使用 JSDoc 标注复杂对象参数

当函数接收一个包含多层嵌套的对象作为参数时，可以使用 @param 搭配对象结构描述来清晰定义其类型和字段：

/** * 更新用户信息 * @param {Object} user – 用户对象 * @param {string} user.id – 用户唯一ID * @param {string} user.name – 用户名 * @param {number} user.age – 年龄 * @param {Object} user.profile – 用户档案 * @param {string} user.profile.email – 邮箱地址 * @param {Boolean} user.profile.isActive – 是否激活 */ function updateUser(user) { // … }

这样写后，调用该函数时，IDE 就能提示 user 对象应有的结构。

2. 使用 typedef 定义可复用的复杂类型

如果某个复杂对象会被多次使用，推荐用 @typedef 提前定义类型，提高可维护性：

/** * @typedef {Object} UserProfile * @Property {string} email – 用户邮箱 * @property {boolean} isActive – 账户是否激活 * @property {string} [avatar] – 头像URL（可选） */

/**

标书对比王

标书对比王是一款标书查重工具，支持多份投标文件两两相互比对，重复内容高亮标记，可快速定位重复内容原文所在位置，并可导出比对报告。

58

查看详情

• @typedef {Object} User
• @property {string} id
• @property {string} name
• @property {number} age
• @property {UserProfile} profile */

/**

• @param {User} user – 完整用户对象 */ function saveUser(user) { // … }

使用 @typedef 后，多个函数都可以引用相同的类型定义，结构更清晰。

3. 标注数组、可选属性与联合类型

JSDoc 还支持更复杂的类型表达，比如数组、可选字段、联合类型等：

/** * @typedef {Object} ApiResponse * @property {boolean} success * @property {string | null} message – 可为字符串或 null * @property {User[]} data – 用户对象数组 * @property {number} [total] – 总数（可选） */

• ?表示可选：如 @property {number} [total]
• | 表示联合类型：如 string | null
• [] 表示数组：如 User[]

4. 标注函数返回的复杂对象

使用 @returns 或 @return 来说明返回值结构：

/** * 获取当前用户信息 * @returns {User} 返回用户对象 */ function getCurrentUser() { return fetch(‘/api/user’).then(res => res.json()); }

也可以直接内联描述返回结构：

/** * @returns {Object} * @property {string} Token – 认证令牌 * @property {number} expires – 过期时间戳 */

基本上就这些。通过合理使用 JSDoc 的注解方式，即使在纯 JS 中也能实现接近 TypeScript 的类型提示体验，尤其适合大型项目或团队协作。