Vue3+TypeScript扩展第三方组件 如何保留原有Prop类型并新增自定义Props

问题核心成因 #

• 原有封装丢失类型的本质，是没有把PrimeVue Button的原始Props类型和自定义组件的Props做显式关联，直接通过$attrs透传时，TS无法感知透传参数和原组件Props的约束关系，最终所有透传参数都会被默认为任意类型，自然不会触发类型校验报错。
• 第三方组件为原生JS实现、附带外部Button.d.ts的情况不会干扰类型合并流程，只要该声明文件是符合TS模块规范的，就可以正常提取完整的组件类型。

类型合并的完整实现步骤 #

1. 提取原组件的完整类型 #

通过Vue内置的ComponentProps工具类型，从PrimeVue Button的导出值上直接提取所有官方声明的Props、插槽、事件类型：

import { Button } from 'primevue/button'
import type { ComponentProps } from 'vue'

// 完整保留原Button的所有类型定义，和直接使用原组件的校验逻辑完全一致
// *这一步完全可以读取外部d.ts里声明的类型，不受原组件是JS实现的影响*
type OriginalButtonProps = ComponentProps<typeof Button>

2. 合并自定义Props类型 #

根据实际封装逻辑处理原组件的类型：如果存在被组件内部逻辑接管的Props（比如示例里的label，是内部通过myProp计算生成后传给原组件的），就用Omit工具类型将这部分属性从原类型中剔除，避免出现内外绑定冲突，再叠加自定义的Props类型：

type BaseButtonProps = Omit<OriginalButtonProps, 'label'> & {
  // 新增自定义Props类型
  myProp?: string
}

3. 替换原有JS写法的组件定义 #

改用TS泛型模式的defineProps替代原来的运行时props对象写法，直接关联合并好的类型，Vue会自动把类型校验逻辑绑定到组件上：

<script setup lang="ts">
import { computed } from 'vue'
import { Button } from 'primevue/button'
import type { ComponentProps } from 'vue'

type OriginalButtonProps = ComponentProps<typeof Button>
type BaseButtonProps = Omit<OriginalButtonProps, 'label'> & {
  myProp?: string
}

// 绑定合并后的类型
const props = defineProps<BaseButtonProps>()

const myComputedLabel = computed(() => {
  return `Hello ${props.myProp}`
})
</script>

<template>
  <Button v-bind="$attrs" :label="myComputedLabel">
    <template v-for="(_, slot) of $slots" v-slot:[slot]="scope">
      <slot :name="slot" v-bind="scope"/>
    </template>
  </Button>
</template>

效果验证 #

完成上述改造后，IDE会完全复刻原组件的类型校验逻辑：

• 给BaseButton传入原Button要求的属性时，会触发和原组件一致的类型提示，比如原组件要求label为字符串，传入数字会正常标记类型错误
• 自定义的myProp属性也会同步生效类型校验，传入非字符串值会触发报错
• 插槽、事件的类型提示和原组件保持一致

注意事项 #

• 不要同时混用运行时props定义和TS泛型props定义，否则会出现类型合并失效的问题，实现严格类型校验时统一用泛型写法即可
• Vue3项目建议使用Volar插件替代Vetur，Vetur本身对Vue3+TS的组件类型识别支持不完善，即便类型逻辑正确也可能出现类型不提示、不报错的异常
• 如果需要保留原组件label属性的外部传入能力，只需要把类型合并中的Omit<OriginalButtonProps, 'label'>改为直接引用OriginalButtonProps即可，不需要额外调整模板逻辑

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