17370845950

在JavaScript中可通过JSDoc使用联合类型注解，如string|number表示多类型支持，结合@param、@typedef等标签提升代码可读性与编辑器提示，适用于函数参数、返回值等场景。

在JavaScript中，虽然原生不支持类型注解，但在使用JSDoc配合现代编辑器（如VS Code）或TypeScript时，可以通过注解方式为变量、函数参数等添加联合类型说明，提升代码可读性和开发体验。下面介绍JS中如何正确书写和使用联合类型的JSDoc注解。

什么是联合类型注解

联合类型表示一个值可以是多种类型中的一种。在JSDoc中，使用 | 符号连接多个类型，形成联合类型。这种方式常用于函数参数、返回值或变量声明的类型标注。

例如，一个参数可以是字符串或数字：

常见联合类型写法与技巧

掌握几种典型的联合类型写法，有助于更准确地描述API行为。

• 基础类型联合：string、number、boolean等组合使用
/** * @param {string|number|boolean} input */ function processInput(input) { ... }
• 对象类型联合：不同结构的对象可以共存
/** * @param {{type: 'success', data: any} | {type: 'error', message: string}} result */ function handleResult(result) { if (result.type === 'success') { // 处理成功逻辑 } else { // 处理错误逻辑 } }
• 包含 null 和 undefined：显式允许空值
/** * @param {string|null|undefined} name */ function greet(name) { if (name) { console.log('Hello, ' + name); } else { console.log('Hello, anonymous'); } }

提高类型提示准确性的小技巧

合理使用类型别名和条件判断，可以让编辑器提供更精准的智能提示。

• 使用 @typedef 定义复杂联合类型：提升可维护性
/** * @typedef {Object} SuccessResult * @property {'success'} type * @property {any} data */

/**

• @typedef {Object} ErrorResult
• @property {'error'} type
• @property {string} message */

/**

• @param {SuccessResult|ErrorResult} result */ function handleResult(result) { ... }

尽管JS没有编译期类型检查，但通过判断字段（如 type 标志）可以实现类似TypeScript的类型收窄效果。

基本上就这些。只要规范书写JSDoc中的联合类型注解，就能在不使用TypeScript的情况下获得不错的类型提示和文档支持，尤其适合渐进式迁移或轻量项目。关键是保持一致性，并配合良好的运行时校验逻辑。