如何在React中结合Stencil生成的Web Components类型，兼容ref、key属性且不丢失组件自身类型检查

嘿，我太懂你这种不想用any凑活、想要完整类型检查的心情了！其实咱们可以通过**类型交叉（Type Intersection）**来完美解决这个问题——既能保留Stencil生成组件的原生类型，又能兼容React的ref、key这些特殊属性，完全不用妥协。

问题根源回顾 #

你之前的写法要么只能兼容组件自身类型、但React会报ref/key的错；要么换成React.DetailedHTMLProps后又丢了组件的自定义属性类型。核心问题就是没把两种类型合并起来，而类型交叉就是干这个的！

正确的类型定义写法 #

假设你的Stencil库已经生成了组件的类型（比如Avatar属性类型、HTMLAvatarElement组件实例类型），只需要在global.d.ts里用&把Stencil组件类型和React的通用HTML属性类型交叉起来：

// 先导入Stencil生成的组件类型（如果你的d.ts是全局的也可以不用这步）
import type { Avatar, HTMLAvatarElement } from '@your-stencil-library/components';

declare module "react" {
  namespace JSX {
    interface IntrinsicElements {
      // 交叉合并React通用属性和Stencil组件的自定义属性
      "avatar": React.DetailedHTMLProps<
        React.HTMLAttributes<HTMLAvatarElement>, 
        HTMLAvatarElement
      > & Avatar;
    }
  }
}

为什么这能解决问题？ #

• React.DetailedHTMLProps<React.HTMLAttributes<HTMLAvatarElement>, HTMLAvatarElement>：帮你兼容React的通用属性，包括ref、key、className、style，还有各种原生DOM事件（比如onClick），同时ref会被正确类型化为HTMLAvatarElement的引用。
• & Avatar：把Stencil组件的自定义属性（比如你提到的name）合并进去，保留完整的类型提示和检查，不会丢失组件自身的类型信息。

实际使用示例 #

现在你用组件的时候，既能享受React属性的支持，又不会丢组件的类型检查：

import { useRef } from 'react';

function UserProfile() {
  // ref会被正确类型化为Stencil组件的实例
  const avatarRef = useRef<HTMLAvatarElement>(null);

  return (
    <avatar 
      name="James"  {/* 这里有完整的类型检查 */}
      ref={avatarRef} {/* React不再报错，且ref类型正确 */}
      key="user-avatar" {/* key属性正常兼容 */}
      className="rounded-full border-2" {/* 通用HTML属性也能用 */}
      onAvatarClick={(e) => console.log('Avatar clicked:', e.detail)} {/* 自定义事件也有类型提示 */}
    />
  );
}

额外提示 #

如果你的Stencil组件有自定义事件，比如onAvatarClick，确保Stencil生成的Avatar类型里已经包含了这些事件的定义——通常Stencil会自动生成对应的事件处理函数类型，直接交叉就能用，不用额外配置。

这样一来，你完全不用 resort to :any，就能实现完整的类型安全，同时兼容React的所有通用属性啦！

备注：内容来源于stack exchange，提问作者James Wilkinson