TypeScript中如何为React组件实现支持任意HTML元素的as prop

实现效果：组件的属性类型完全跟随as传入的元素类型动态推导，既保留组件自身自定义属性的类型校验，也能准确匹配对应HTML原生元素的全部合法属性规则。

基础实现步骤 #

1. 引入React内置类型工具 #

不需要手动枚举所有HTML元素的属性类型，直接复用React提供的内置工具即可完成属性提取：

• ElementType：覆盖所有合法的可渲染元素类型，包括原生HTML标签、自定义React组件
• ComponentPropsWithoutRef：自动提取对应元素/组件的全部原生属性类型，无需手动维护

2. 定义多态Props的泛型结构 #

import React from 'react';
import type { ElementType, ComponentPropsWithoutRef } from 'react';

// 泛型C对应as prop传入的元素类型，设置默认值为常见的'div'兜底
type PolymorphicComponentProps<C extends ElementType> = {
  as?: C;
  // 在这里定义你组件的所有自定义Props，比如示例中的myProps
  myCustomProp?: string;
} 
// 交叉合并对应元素的原生属性，同时排除和自定义Props重名的字段，避免类型冲突
& Omit<ComponentPropsWithoutRef<C>, keyof PolymorphicComponentProps<C>>;

这里的Omit操作是关键：原生元素自带的属性可能和组件自定义Props重名，直接做类型交叉会导致校验逻辑混乱，提前排除重名字段可以保证类型逻辑的一致性。

3. 组件函数的泛型对齐 #

很多类型推导失效的问题，根源是泛型没有正确声明在组件函数上，导致TS无法根据传入的as值反向推导属性类型。正确的声明方式如下：

// 泛型直接写在组件函数的参数定义前，开启TS的动态推导能力
const Component = <C extends ElementType = 'div'>(props: PolymorphicComponentProps<C>) => {
  // 从props中取出as值，设置默认渲染标签为泛型的默认值'div'
  const { as: Tag = 'div', myCustomProp, ...nativeProps } = props;
  return <Tag {...nativeProps} data-my-prop={myCustomProp} />;
};

实际使用的类型校验效果 #

完全匹配预期的使用场景，自动完成类型校验：

• 传入as='div'时，组件会自动加载div的全部原生属性类型：

// 合法的div属性（id、onClick等）会有完整类型提示，非法属性（比如button专属的type）会直接触发类型报错
<Component 
  as='div' 
  myCustomProp="demo" 
  id="container" 
  onClick={() => {}} 
/>

• 传入as='button'时，组件会自动切换为button的原生属性集：

// 自动支持button专属属性（type、disabled等）的类型校验
<Component 
  as='button' 
  myCustomProp="demo" 
  type="submit" 
  disabled={false} 
  onClick={() => {}} 
/>

进阶适配：支持ref透传 #

如果需要把ref透传到最终渲染的原生元素上，只需要把Props里的属性提取工具替换成ComponentPropsWithRef，同时处理好forwardRef和泛型的兼容问题即可：

import type { ComponentPropsWithRef } from 'react';

type PolymorphicComponentPropsWithRef<C extends ElementType> = {
  as?: C;
  myCustomProp?: string;
} & Omit<ComponentPropsWithRef<C>, keyof PolymorphicComponentPropsWithRef<C>>;

const Component = React.forwardRef(
  <C extends ElementType = 'div'>(
    props: PolymorphicComponentPropsWithRef<C>,
    ref: PolymorphicComponentPropsWithRef<C>['ref']
  ) => {
    const { as: Tag = 'div', ...rest } = props;
    return <Tag {...rest} ref={ref} />;
  }
) as <C extends ElementType = 'div'>(props: PolymorphicComponentPropsWithRef<C>) => JSX.Element;

常见踩坑提醒 #

• 不要把as的类型写为string，否则TS会完全丢失对as值的推导能力，所有属性都会退化为任意类型
• 不要省略Omit重名字段的步骤，否则自定义Props和原生Props的同名属性会出现类型冲突，导致校验失效
• 必须把泛型声明在组件函数的参数位置，只写在Props定义上是无法触发动态推导的

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