Vue3 Option API结合TypeScript：如何扩展this实例？

一、扩展组件实例添加非状态成员 #

1. Options API 场景 #

要让TypeScript识别自定义的实例属性，需要扩展ComponentCustomProperties全局接口，在项目类型声明文件中添加如下代码：

// 示例：src/vue.d.ts
declare module '@vue/runtime-core' {
  interface ComponentCustomProperties {
    // 根据实际第三方组件类型声明，这里用SomeExternalComponent作为示例
    component: SomeExternalComponent
  }
}

// 确保TypeScript识别该声明
export {}

之后在组件钩子中赋值时，TypeScript会自动识别this.component，无需添加//@ts-ignore：

<script lang="ts">
import { defineComponent } from 'vue'
import SomeExternalComponent from 'some-external-library'

export default defineComponent({
  mounted() {
    this.component = new SomeExternalComponent(this.$el)
  },
  beforeUnmount() {
    this.component?.destroy()
  }
})
</script>

2. Composition API 场景 #

Composition API中无需扩展全局接口，直接用shallowRef（避免深度响应式转换浪费性能）存储第三方组件实例即可，TypeScript会自动推导类型：

<script setup lang="ts">
import { shallowRef, onMounted, onBeforeUnmount } from 'vue'
import SomeExternalComponent from 'some-external-library'

const component = shallowRef<SomeExternalComponent | null>(null)

onMounted(() => {
  component.value = new SomeExternalComponent(document.getElementById('target-el'))
})

onBeforeUnmount(() => {
  component.value?.destroy()
})
</script>

二、定义不暴露的私有实例方法 #

1. Options API 场景 #

• 闭包隔离方式：在setup函数内定义私有方法，利用闭包特性限制访问范围，仅在setup内部及关联钩子中可用：

<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    // 私有方法，不返回则不会暴露到组件实例
    const onMyEvent = (event: Event) => {
      console.log('处理私有事件:', event)
    }

    // 仅返回需要公开的成员
    return {}
  }
})
</script>

• TypeScript类型限制：如果要在methods中定义，可使用private修饰符，TypeScript层面会禁止外部访问（注意：运行时仍可通过实例访问，仅做类型检查限制）：

<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  methods: {
    private onMyEvent(event: Event) {
      console.log('私有方法执行:', event)
    },
    publicTrigger() {
      // 组件内部可正常调用私有方法
      this.onMyEvent(new Event('test'))
    }
  }
})
</script>

2. Composition API 场景 #

在<script setup>中直接定义的函数默认是私有，不会暴露到组件实例上，仅能在当前组件内部使用：

<script setup lang="ts">
// 私有方法，仅当前组件内部可访问
const onMyEvent = (event: Event) => {
  console.log('处理事件:', event)
}
</script>

<template>
  <div @click="onMyEvent">点击触发私有方法</div>
</template>

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