使用JSDoc扩展Vue泛型Ref类型遇到的类型匹配问题

错误原因分析 #

1. @extends标签误用：@extends仅用于类声明的继承关系标注，不能用来给变量指定类型，因此触发JSDoc '@extends' is not attached to a class.ts(8022)错误。
2. 类型不匹配：你将current的类型指定为ref（创建Ref的函数类型），但current实际是ref()返回的Ref实例对象，两者类型完全不同，导致类型赋值错误。
3. 泛型引用错误：之前出现的Type 'Ref' is not generic.ts(2315)，是因为未正确在JSDoc中引用Vue的泛型Ref类型，需要完整指定泛型参数和导入路径。

解决方案 #

方案1：直接指定Ref类型 #

无需复杂模板，直接在@type中明确current的类型为Vue的Ref泛型实例：

/**
 * @type {import('vue').Ref<{ arg: number }>}
 */
export const current = ref({ arg: 1 });

方案2：自定义泛型类型复用（可选） #

如果需要在多个地方复用特定的Ref类型，可以先通过@typedef定义泛型类型：

/**
 * @template T
 * @typedef {import('vue').Ref<T>} TypedRef
 */

/**
 * @type {TypedRef<{ arg: number }>}
 */
export const current = ref({ arg: 1 });

关键说明 #

• Vue的Ref是泛型接口，必须指定泛型参数（即value的类型）才能正确使用
• 不要混淆ref函数类型和Ref实例类型：ref是创建Ref的工具函数，Ref是它返回的实例类型

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