React+TS使用useRef时LegacyRef<HTMLDivElement>类型不匹配

报错根源 #

你遇到的LegacyRef<HTMLDivElement> | undefined类型不匹配报错，是useRef重载匹配规则、TypeScript严格类型兼容规则共同作用的结果：

• 写法const node = useRef<HTMLElement | null>(null)：传入泛型参数HTMLElement | null时，会匹配useRef的第一个重载，返回可变的MutableRefObject<HTMLElement | null>。该对象的current是可写的、范围宽泛的通用HTMLElement类型，而div元素的ref属性要求接收适配HTMLDivElement的引用；在严格模式下，TS认为可写的通用DOM类型引用无法保证仅接收div元素实例，因此触发类型不匹配。
• 写法const node: RefObject<HTMLElement> = useRef(null)：不带泛型参数的useRef(null)会默认推导返回MutableRefObject<null>，本身和手动标注的RefObject<HTMLElement>结构不匹配，绑定DOM元素时同样会触发校验报错。

通用适配解法 #

无需绑定单一固定DOM元素类型，只要调整useRef的泛型传参方式，触发返回只读引用的重载即可：

const node = useRef<HTMLElement>(null);

这种写法的能力完全覆盖你的需求：

• 触发useRef的第二个重载，返回只读的RefObject<HTMLElement>，current为readonly HTMLElement | null类型。因为是只读属性，TS会放开可写属性的逆变校验，无论后续把这个ref绑定到<div>、<form>、<input>、<section>等任意HTMLElement子类的DOM元素上，都会通过协变规则自动完成类型校验，不会报类型不匹配错误。
• 不需要每次更换绑定元素时，都修改ref的类型定义（比如不用单独换成HTMLDivElement、HTMLFormElement这类固定元素类型），真正实现跨DOM元素的通用复用。
• 可以直接在业务逻辑中调用node.current.contains()这类所有HTMLElement都支持的通用DOM API，和原有逻辑完全兼容。

特殊场景兼容 #

如果业务中需要手动修改node.current的值（而非完全依赖React绑定DOM时自动给current赋值），可以在保持通用性的前提下，通过轻量类型断言完成适配：

const node = useRef<HTMLElement | null>(null);
return <div ref={node as React.RefObject<HTMLDivElement>}></div>

这种写法不会引入固定元素类型的强耦合，依然支持跨场景复用同一个ref实例。

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