在使用JSDoc为基于function构造器的原型继承代码（如Object.create(Parent.prototype)）添加类型注解时，TypeScript语言服务无法通过@extends识别子类继承关系，导致子类实例访问父类this属性时报“属性不存在”错误。
在使用jsdoc为基于`function`构造器的原型继承代码（如`object.create(parent.prototype)`）添加类型注解时，typescript语言服务无法通过`@extends`识别子类继承关系，导致子类实例访问父类`this`属性时报“属性不存在”错误。
TypeScript 的 JSDoc 类型检查系统对现代 class 语法支持完善，但对传统原型式继承存在明显限制。以问题中的 CoolDownTween 和 CooledDownPropFadeToggleTween 为例：
/**
* @constructor CoolDownTween
*/
const CoolDownTween = function() {
this.currentFrame = 0; // ✅ 在 CoolDownTween 实例上被正确识别
this.ended = false;
};
/**
* @constructor CooledDownPropFadeToggleTween
* @extends {CoolDownTween} // ❌ 无效！@extends 不支持与 @constructor 搭配
*/
const CooledDownPropFadeToggleTween = function() {
CoolDownTween.apply(this, arguments);
};
CooledDownPropFadeToggleTween.prototype = Object.create(CoolDownTween.prototype);尽管 @extends {CoolDownTween} 在语义上清晰表达了继承意图，但 TypeScript 当前（v5.5+）不支持将 @extends 与 @constructor 修饰的函数组合使用。这是由 TypeScript 的 JSDoc 解析机制决定的：@extends 仅在 class 声明或 /** @class */ 注释标记的函数上生效，而 @constructor 本身不具备建立类型继承链的能力。
因此，当 IDE（如 Eclipse 配合 TypeScript LSP）检查 new CooledDownPropFadeToggleTween().currentFrame 时，它无法推导出该属性来自 CoolDownTween.prototype 的初始化逻辑，从而报错；而 ended 属性未报错，往往是因为类型检查器在某些上下文中进行了宽松的隐式合并（如多次赋值触发了宽泛的联合类型推断），但这属于不可靠的行为，不应依赖。
✅ 推荐解决方案：
立即学习“Java免费学习笔记（深入）”；
-
迁移到 ES6 class 语法（首选）
既符合现代标准，又获得完整 JSDoc + 类型检查支持：/** * @class CoolDownTween */ class CoolDownTween { constructor() { /** @type {number} */ this.currentFrame = 0; /** @type {boolean} */ this.ended = false; } } /** * @class CooledDownPropFadeToggleTween * @extends {CoolDownTween} */ class CooledDownPropFadeToggleTween extends CoolDownTween { /** * @param {number} stepCount * @param {number} timestamp */ nextStep(stepCount, timestamp) { if (timestamp >= 1000) this.ended = true; this.currentFrame += stepCount; } } -
若必须保留函数构造器，使用 @typedef + @type 显式声明类型关系
作为临时 workaround，可手动定义子类类型并标注其结构：/** * @typedef {Object} CooledDownPropFadeToggleTween * @property {number} currentFrame * @property {boolean} ended * @property {function(number, number): void} nextStep */ /** @type {CooledDownPropFadeToggleTween} */ const instance = new CooledDownPropFadeToggleTween();
⚠️ 注意事项：
- @augments 与 @extends 在 JSDoc 中功能等价，但同样不适用于 @constructor 函数；
- Object.assign(this, new CoolDownTween()) 等浅拷贝方式虽能绕过部分检查，但破坏原型链、影响 instanceof 和方法复用，强烈不推荐；
- 该限制是 TypeScript 的已知设计约束，相关提案 microsoft/TypeScript#38985 仍在等待社区反馈，短期内无官方支持计划。
总结：类型安全与可维护性优先时，应主动升级至 class 语法；遗留项目若暂无法重构，建议结合 @typedef 显式建模 + 单元测试保障运行时行为，避免依赖不可靠的隐式类型推断。
