在React TypeScript中，何时更适合使用HTMLAttributes而非ComponentProps？

我知道在为React组件做类型定义时，通常更推荐使用ComponentProps而非HTMLAttributes，但我不确定哪些特定场景下HTMLAttributes会更合适。

下面是我当前的简化实现：

import { type HTMLAttributes, type ReactElement } from "react";

type PressableProps = HTMLAttributes<HTMLElement> & {
  "aria-pressed": boolean;
};

type WrapperProps = {
  children: ReactElement<PressableProps>;
};

function PressableEffect({ children }: WrapperProps) {
  // ... 包含事件处理的实现逻辑
  return cloneElement(children, {
    ...children.props,
    "aria-pressed": true,
    onPointerDown: handlePointerDown,
  });
}

如果换成ComponentProps的话，代码会是这样：

import { type ComponentProps, type ReactElement } from "react";

type PressableProps = ComponentProps<any> & {
  "aria-pressed": boolean;
};

核心区别与适用场景 #

先把两者的本质差异说清楚：

• HTMLAttributes<T>是React提供的、专门针对原生HTML元素属性的类型集合，它只包含对应HTML元素的标准属性（比如id、className、onClick这类），是一个固定、清晰的属性列表。
• ComponentProps<typeof Component>则是用来提取任意React组件（包括原生HTML元素、自定义组件）的props类型的工具类型，它会精准获取目标组件对外暴露的所有props。

下面这些场景下，HTMLAttributes会是更合适的选择：

1. 定义「仅接收原生HTML属性+自定义属性」的组件

如果你的组件最终是渲染一个原生HTML元素（比如div、button），并且只需要让它支持该元素的标准HTML属性，同时添加少量自定义属性，HTMLAttributes能让你的类型定义更清晰。

比如写一个自定义按钮组件，只需要支持button的标准属性加上自己的variant属性：

import { HTMLAttributes } from 'react';

type CustomButtonProps = HTMLAttributes<HTMLButtonElement> & {
  variant: 'primary' | 'secondary';
};

function CustomButton({ variant, ...rest }: CustomButtonProps) {
  const btnClass = variant === 'primary' ? 'btn-primary' : 'btn-secondary';
  return <button className={btnClass} {...rest} />;
}

这种写法能明确告诉其他开发者：这个组件的基础属性和原生button完全一致，不会混入其他奇怪的props。

2. 需要传递通用HTML属性给多种类型的子组件

比如你写的PressableEffect这类包装组件，它需要接收任意能渲染成HTML元素的子组件，并且要给子组件传递通用的HTML/ARIA属性（比如aria-pressed、onPointerDown）。这时候用HTMLAttributes<HTMLElement>作为基础类型，能确保你传递的属性是所有HTML元素都支持的，不会因为子组件是div、span还是button而出现类型不兼容的问题。

3. 避免ComponentProps泛型参数的模糊性

你示例里用ComponentProps<any>其实是不推荐的，因为any直接丢失了类型检查的意义。如果用ComponentProps，你得明确指定目标组件的类型，比如ComponentProps<'button'>来获取button的props类型，但如果你要支持多种HTML元素，HTMLAttributes<HTMLElement>会更通用，不需要逐个指定元素类型。

补充：什么时候用ComponentProps更合适？ #

反过来，这两种情况优先选ComponentProps：

• 需要提取某个自定义组件的props类型时（比如ComponentProps<typeof CustomButton>）
• 精准匹配某个特定原生HTML元素的所有专属props时（比如ComponentProps<'input'>会包含value、type等input专属属性，虽然HTMLAttributes<HTMLInputElement>也包含，但ComponentProps写法更简洁）

备注：内容来源于stack exchange，提问作者Amanda Ferrari