如何在JSDoc中实现TypeScript式的keyof实例类型标注？

TypeScript中的实现方式 #

const a1 = new Car('Audi A1', 4, Power.solar);
const a380 = new Plane('Airbus A380', 800, 4);

function showProperty<T>(thing: T, prop: keyof T) {
    console.log(`${String(prop)}:`, thing[prop]);
}

showProperty(a1, 'power');
showProperty(a380, 'engines');

JSDoc的正确实现方式 #

要在JSDoc中实现相同的类型约束，需要借助泛型声明和keyof操作符，具体步骤如下：

1. 为类添加JSDoc类型定义 #

首先给Car和Plane类补充类型标注，让TypeScript能识别它们的实例属性：

/**
 * 汽车类
 * @class
 * @param {string} name - 汽车名称
 * @param {number} seats - 座位数
 * @param {string} power - 动力类型
 */
class Car {
  constructor(name, seats, power) {
    this.name = name;
    this.seats = seats;
    this.power = power;
  }
}

/**
 * 飞机类
 * @class
 * @param {string} name - 飞机名称
 * @param {number} capacity - 载客量
 * @param {number} engines - 引擎数量
 */
class Plane {
  constructor(name, capacity, engines) {
    this.name = name;
    this.capacity = capacity;
    this.engines = engines;
  }
}

2. 为函数添加泛型JSDoc标注 #

修改showProperty函数的JSDoc，通过泛型动态匹配实例类型，再用keyof约束属性名：

const a1 = new Car('Audi A1', 4, 'petrol');
const a380 = new Plane('Airbus A380', 800, 4);

/**
 * 展示对象的指定属性
 * @template T
 * @param {T} thing - 目标对象
 * @param {keyof T} prop - 对象的合法属性名
 */
function showProperty(thing, prop) {
    console.log(`${String(prop)}:`, thing[prop]);
}

showProperty(a1, 'power'); // 此处会提示合法属性：name、seats、power
showProperty(a380, 'engines'); // 此处会提示合法属性：name、capacity、engines

关键说明 #

• @template T：声明泛型参数T，让函数可以适配任意类型的对象实例。
• keyof T：表示取类型T的所有属性名组成的联合类型，TypeScript会根据传入的thing实例，自动校验prop是否为该实例的合法属性名，给出准确的代码提示和类型检查。

原写法中使用了未定义的Thing类型，无法动态适配不同实例，而泛型+keyof的组合能完美实现和TypeScript原生写法一致的效果。

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