React forwardRef联合/泛型元素的TypeScript类型守卫问题

问题核心 #

你尝试实现一个可渲染div/button/a的React组件，但在TypeScript中无法通过类型守卫来匹配不同元素的Ref类型——这是因为React的Ref类型在运行时没有保留编译阶段的类型信息，自定义类型守卫在这里没有可依赖的运行时判断依据，正确的思路是在编译阶段通过组件Props约束Ref与元素类型的绑定。

方案一：联合类型+条件渲染的正确实现 #

通过在Props中指定元素类型（如as字段），结合类型断言安全地匹配对应元素的Ref类型：

import React, { forwardRef, Ref } from 'react';

// 定义不同元素的Props类型
type ElementProps<T extends 'div' | 'button' | 'a'> = 
  T extends 'div' ? React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement> :
  T extends 'button' ? React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement> :
  React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>;

// 组合组件Props：可选的元素类型+对应元素的原生Props
type CustomElementProps = { as?: 'div' | 'button' | 'a' } & ElementProps<'div' | 'button' | 'a'>;

const CustomElement = forwardRef<
  HTMLDivElement | HTMLButtonElement | HTMLAnchorElement,
  CustomElementProps
>(({ as = 'div', ...props }, ref) => {
  switch (as) {
    case 'button':
      // 已通过as字段确定渲染button，断言Ref类型安全
      return <button ref={ref as Ref<HTMLButtonElement>} {...props} />;
    case 'a':
      return <a ref={ref as Ref<HTMLAnchorElement>} {...props} />;
    default:
      return <div ref={ref as Ref<HTMLDivElement>} {...props} />;
  }
});

方案二：泛型实现的类型严格绑定 #

泛型方式可以让组件的Ref类型与指定元素自动关联，无需额外断言：

import React, { forwardRef, Ref } from 'react';

// 泛型Props：指定元素类型+对应元素的原生Props（排除Ref）
type GenericElementProps<T extends 'div' | 'button' | 'a'> = {
  as: T;
} & React.ComponentPropsWithoutRef<T>;

const GenericElement = forwardRef(function <T extends 'div' | 'button' | 'a'>(
  { as, ...props }: GenericElementProps<T>,
  // 根据泛型T自动推导Ref对应的元素类型
  ref: Ref<
    T extends 'div' ? HTMLDivElement :
    T extends 'button' ? HTMLButtonElement :
    HTMLAnchorElement
  >
) {
  const Component = as;
  return <Component ref={ref} {...props} />;
});

使用时TypeScript会自动约束Ref类型：

const buttonRef = React.useRef<HTMLButtonElement>(null);
<GenericElement as="button" ref={buttonRef} />; // 类型完全匹配，无报错

为什么自定义类型守卫不可行？ #

你编写的isDivRef函数无法实现，原因有两点：

1. React的Ref类型在运行时无类型信息：RefObject的current可能为null，回调Ref只是一个函数，无法从函数本身判断它期望接收的元素类型。
2. 传入的element字符串与Ref类型无运行时关联：类型守卫需要基于可判断的运行时值，但字符串标识和Ref的类型约束仅存在于编译阶段。

内容的提问来源于stack exchange，提问作者홍우지