Vue3+TypeScript中如何添加IntrinsicElements支持自定义Web组件？

问题场景 #

我想为自定义Web组件添加类型定义，让VSCode的Volar插件能提供组件的属性和事件提示，但尝试了多种JSX全局声明的方式都无效，测试代码如下：

import type { HTMLAttributes } from 'vue';

// 无效
declare global {
    namespace JSX {
        interface IntrinsicElements {
            myelement: HTMLAttributes;
        }
    }
}

// 添加export也无效
declare global {
    export namespace JSX {
        export interface IntrinsicElements {
            myelement: HTMLAttributes;
        }
    }
}

// 不使用global也无效
export namespace JSX {
    export interface IntrinsicElements {
        myelement: HTMLAttributes;
    }
}

另外尝试使用GlobalComponents时，属性能正常提示，但事件没有效果：

declare module '@vue/runtime-core' {
    export interface GlobalComponents {
        myelement: HTMLAttributes;
    }
}

解决方案 #

要让Volar完整识别自定义Web组件的属性与事件，需要同时扩展GlobalComponents和全局DOM类型，并正确定义组件的完整类型：

1. 定义组件的完整类型（含属性与事件） #

先明确组件支持的属性和自定义事件，合并到基础HTML属性类型中：

import type { HTMLAttributes } from 'vue';

// 自定义事件类型，按需添加
interface MyElementEvents {
  // 示例：自定义事件"my-event"，携带string参数
  'onMyEvent': (value: string) => void;
}

// 合并基础HTML属性与自定义事件，得到完整的组件props类型
type MyElementProps = HTMLAttributes & MyElementEvents;

2. 扩展Vue的GlobalComponents #

在@vue/runtime-core模块中扩展GlobalComponents，指定组件的props类型：

declare module '@vue/runtime-core' {
  export interface GlobalComponents {
    // 大驼峰组件名对应模板中的短横线标签<myelement>
    MyElement: {
      props: MyElementProps;
    };
  }
}

3. 扩展全局DOM标签映射 #

让TypeScript识别自定义标签对应的DOM元素类型：

declare global {
  interface HTMLElementTagNameMap {
    'myelement': HTMLElement;
    // 如果组件有自定义实例属性/方法，可以在此扩展
    // 'myelement': HTMLElement & { customMethod: () => void };
  }
}

4. 导出空语句确保类型生效 #

最后必须添加导出语句，让TypeScript将该文件视为模块：

export {};

关键说明 #

• Vue 3的Volar插件主要依赖GlobalComponents识别组件类型，单独扩展JSX.IntrinsicElements不生效。
• 直接使用HTMLAttributes作为GlobalComponents的类型只会包含基础属性，事件需要显式定义或合并到类型中。
• 组件名遵循Vue的命名规范：GlobalComponents中用大驼峰（MyElement），模板中对应短横线命名（<myelement>），Volar会自动映射。

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