如何为TypeScript联合类型中的属性启用JSDoc智能提示？

• 单个类型的属性上添加JSDoc注释时，鼠标悬停能正常显示注释内容：
  

• 将类型改为复杂联合类型后，悬停属性不再显示注释：
  

• 直接引用该类型的属性时，仍能看到对应的JSDoc注释：
  

请问是否有办法为更复杂的联合类型中的属性启用JSDoc注释显示？

解决方法 #

1. 为联合类型分支单独维护属性注释 #

如果联合类型的每个分支都是明确的对象类型，可以直接在各分支的属性上添加注释，或者通过复用类型来减少重复代码：

/** 唯一标识ID */
type IdField = {
  /** 唯一标识ID */
  id: string;
};

type User = IdField & {
  /** 用户昵称 */
  nickname: string;
};

type Admin = IdField & {
  /** 管理员权限等级 */
  level: number;
};

type Account = User | Admin;

这种方式下，悬停Account类型中的id属性时，会显示对应的注释内容。

2. 通过类型守卫缩小类型范围 #

在代码中用类型守卫（比如in操作符、自定义类型谓词）把联合类型缩小到具体分支后，悬停属性就能看到对应分支的JSDoc注释：

function handleAccount(account: Account) {
  if ('nickname' in account) {
    // 此处悬停account.nickname会显示用户昵称的注释
    console.log(account.nickname);
  } else {
    // 此处悬停account.level会显示管理员权限等级的注释
    console.log(account.level);
  }
}

3. 用JSDoc的@typedef统一声明带注释的属性 #

借助JSDoc的@typedef定义包含注释的属性集合，再在联合类型中引用：

/**
 * @typedef {Object} BaseAccount
 * @property {string} id - 账号唯一标识
 */

/** @typedef {BaseAccount & {nickname: string}} User */
/** @typedef {BaseAccount & {level: number}} Admin */

type Account = User | Admin;

主流编辑器（如VS Code）能识别这类注释并在悬停时展示。

4. 升级TypeScript版本 #

部分旧版本TypeScript对联合类型的JSDoc支持存在缺陷，升级到5.x及以上的稳定版本，大概率能自动修复注释不显示的问题——新版本在类型推断和注释关联逻辑上有优化。

内容的提问来源于stack exchange，提问作者HaveSpacesuit