使用JSDoc+@ts-check转换HTML元素类型报错，非TypeScript环境求解决

你遇到的错误是因为document.getElementById()的返回类型是HTMLElement | null，直接将其断言为HTMLInputElement会触发类型不兼容检查——@ts-check依赖的TypeScript类型检查器会认为元素可能不存在或者类型不匹配。以下是几种无需TypeScript环境的解决方案：

1. 直接使用JSDoc类型断言（适用于确定元素一定存在的场景） #

在获取元素的表达式上添加JSDoc类型断言，明确告诉检查器该元素的类型：

// @ts-check

// 直接在表达式上断言类型
const { list } = /** @type {HTMLInputElement} */ (document.getElementById(someInput));

注意：这种写法跳过了空值和类型检查，如果实际运行时元素不存在或类型不符，会引发错误，仅适合你能确保元素一定存在的场景。

2. 结合非空断言（简化版的存在确认） #

如果确定元素存在，但不想写完整的断言，可以用TypeScript的非空断言运算符!配合JSDoc：

// @ts-check

/** @type {HTMLInputElement | null} */
const inputElement = document.getElementById(someInput);
// ! 表示断言元素不为null
const { list } = inputElement!;

3. 添加类型守卫（最安全的方案） #

通过运行时检查缩小类型范围，既满足@ts-check的错误检查要求，又避免运行时风险：

// @ts-check

const element = document.getElementById(someInput);
// 检查元素是否为HTMLInputElement实例
if (element instanceof HTMLInputElement) {
  const { list } = element;
  // 此处list的类型会被正确推断，可安全使用
}

这种方法会让@ts-check自动认可类型缩小，同时提供运行时的安全保障，推荐优先使用。

为什么原写法会报错？ #

你之前的写法是先声明变量类型为HTMLInputElement，再赋值document.getElementById()的结果，但该方法返回的HTMLElement | null无法直接兼容更具体的HTMLInputElement类型——TypeScript的类型检查器会严格校验这种类型不匹配的情况，这也是@ts-check的核心作用之一。

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