TypeScript中<T extends HTMLElement>与<HTMLElement>泛型的差异及报错原因

一、为什么直接用<HTMLElement>会触发addEventListener不存在的错误？ #

你大概率是把泛型参数名写成了HTMLElement，而非直接指定DOM元素类型。比如代码可能是这样的：

function useScroll<HTMLElement>() {
  const element = useRef<HTMLElement | null>(null);
  // ...
  element.current.addEventListener("wheel", handleWheel); // 触发报错
}

这里的<HTMLElement>是自定义的泛型变量名，它会覆盖全局的HTMLElement类型。此时element.current的类型是你自定义的泛型变量（无任何约束）加上null，TypeScript完全不知道这个变量有addEventListener方法——哪怕用NonNullable去掉了null，这个自定义泛型变量本身也没有任何属性方法，自然会报错。

如果想直接指定元素类型为DOM的HTMLElement，正确写法是不声明泛型参数，直接给ref指定类型：

function useScroll() {
  const element = useRef<HTMLElement | null>(null);
  // 先判断非空再调用方法
  element.current?.addEventListener("wheel", handleWheel);
}

这种写法不会报错，因为原生HTMLElement类型本身就包含addEventListener方法。

二、T extends HTMLElement泛型和直接用HTMLElement的区别 #

1. 类型精确性差异

   • 用<T extends HTMLElement>时，Hook可以适配具体的DOM子元素类型（比如HTMLDivElement、HTMLInputElement、HTMLCanvasElement）。调用时TypeScript会自动推断出T的具体类型，返回的ref也会保留该类型，你能直接访问元素特有的属性方法：

     const inputRef = useScroll<HTMLInputElement>();
     inputRef.current?.value; // 无需断言，直接访问input的value属性
     

   • 直接用HTMLElement时，ref的类型是通用的DOM元素类型，只能访问所有元素共有的属性方法，无法直接获取子元素特有属性（比如input的value、canvas的getContext），必须手动类型断言才能访问。

2. 灵活性差异

   • 泛型约束<T extends HTMLElement>让Hook更通用，能适配各种不同的DOM元素，调用方可以根据需求指定具体类型。
   • 直接用HTMLElement的Hook只能处理通用DOM元素，灵活性差，适合不需要访问元素特有属性的场景。

3. 类型推断能力差异

   • 如果Hook通过参数接收元素ref，用<T extends HTMLElement>可以让TypeScript自动推断T的类型，无需手动指定：

     function useScroll<T extends HTMLElement>(ref: React.RefObject<T>) {
       // ...
     }
     const divRef = useRef<HTMLDivElement>(null);
     useScroll(divRef); // TypeScript自动推断T为HTMLDivElement
     

   • 直接用HTMLElement的话，不管传入什么类型的ref，都会被限制为通用HTMLElement，丢失具体类型信息。

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