在JavaScript中可通过JSDoc使用联合类型注解，如string|number表示多类型支持，结合@param、@typedef等标签提升代码可读性与编辑器提示，适用于函数参数、返回值等场景。
在JavaScript中，虽然原生不支持类型注解，但在使用JSDoc配合现代编辑器（如VS Code）或TypeScript时，可以通过注解方式为变量、函数参数等添加联合类型说明，提升代码可读性和开发体验。下面介绍JS中如何正确书写和使用联合类型的JSDoc注解。
什么是联合类型注解
联合类型表示一个值可以是多种类型中的一种。在JSDoc中，使用 | 符号连接多个类型，形成联合类型。这种方式常用于函数参数、返回值或变量声明的类型标注。
例如，一个参数可以是字符串或数字：
/**
* @param {string|number} value - 可以是字符串或数字
*/
function logValue(value) {
console.log(value
);
}
常见联合类型写法与技巧
掌握几种典型的联合类型写法，有助于更准确地描述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) { ... }
结合 typeof 进行类型缩小：运行时做类型判断
尽管JS没有编译期类型检查，但通过判断字段（如 type 标志）可以实现类似TypeScript的类型收窄效果。
避免过度联合：类型太多会降低可读性，必要时考虑使用泛型或重构
基本上就这些。只要规范书写JSDoc中的联合类型注解，就能在不使用TypeScript的情况下获得不错的类型提示和文档支持，尤其适合渐进式迁移或轻量项目。关键是保持一致性，并配合良好的运行时校验逻辑。
);
}