如何用JSDoc指定泛型函数输出类型及解决VSCode类型提示问题

当然有办法！你完全不用为了满足VSCode的类型提示额外创建变量，用JSDoc的类型断言语法就能直接搞定这个问题。

方法1：换行式类型断言 #

把document.querySelectorAll的调用结果用JSDoc标注成你需要的泛型类型，后续的forEach就能正确识别元素类型了：

/** @type {NodeListOf<HTMLElement>} */
(document.querySelectorAll('.thing')).forEach(el => {
  el.style.color = 'red'; // 现在VSCode会正确识别el是HTMLElement，不会再报错
});

这里的括号一定要包裹整个函数调用，确保类型断言作用在返回结果上，而不是只作用在document对象上。

方法2：紧凑的单行写法 #

如果不想额外换行，也可以把类型注释和调用写在同一行，用@returns直接指定返回的泛型类型：

(/** @returns {NodeListOf<HTMLElement>} */ document.querySelectorAll('.thing')).forEach(el => {
  el.style.color = 'red';
});

原理说明 #

document.querySelectorAll本身是一个泛型方法，VSCode的类型系统（基于TypeScript）默认会推断它返回NodeListOf<Element>——而Element类型确实没有style属性。通过JSDoc的类型断言，我们手动覆盖了默认的类型推断，告诉类型系统我们期望这个调用返回NodeListOf<HTMLElement>，这样forEach里的el就会被识别为具体的HTMLElement，自然就能正常访问style属性了。

这种写法虽然比TypeScript的<HTMLElement>语法稍微繁琐一点，但完全能达到同样的类型提示效果，而且不需要把代码改成TypeScript。

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