如何解决Vue模板中使用$refs时出现的TS2571类型错误？

假设我们有一个自定义组件SomeComp，它暴露了open方法，模板中编写了如下代码：

<button @click="$refs.someComp.open()">Open</button>
<SomeComp ref="someComp" />

运行vue-tsc类型检查时，会触发TS2571: Object is of type 'unknown'错误，指向someComp这个ref。以下是具体解决方法：

自动推断类型（推荐，Vue 3.3+） #

Vue 3.3及以上版本的<script setup lang="ts">支持自动推断组件ref的类型，前提是子组件正确暴露方法：

1. 子组件（SomeComp.vue）：用defineExpose明确暴露需要外部访问的方法

<script setup lang="ts">
const open = () => {
  // 你的方法逻辑
};

// 必须显式暴露，TypeScript才能识别
defineExpose({
  open
});
</script>

2. 父组件：在<script setup>中声明对应的ref变量，Vue会自动推断其类型

<script setup lang="ts">
import SomeComp from './SomeComp.vue';

// Vue 3.3+ 会自动推断为 SomeComp 的实例类型（包含暴露的open方法）
const someComp = ref(null);
</script>

<template>
  <!-- 使用可选链?.避免组件未挂载时的null报错，同时通过类型检查 -->
  <button @click="someComp?.open()">Open</button>
  <SomeComp ref="someComp" />
</template>

这里不需要手动指定泛型类型，Vue会基于子组件的暴露内容自动推导。

手动声明类型（兼容旧版本Vue） #

如果使用Vue 3.3以下版本，或者需要手动控制类型，可以在ref<>中明确声明组件实例类型：

1. 方式一：基于组件本身推导类型

<script setup lang="ts">
import SomeComp from './SomeComp.vue';

// InstanceType<typeof SomeComp> 会获取组件的实例类型
const someComp = ref<InstanceType<typeof SomeComp> | null>(null);
</script>

2. 方式二：手动定义实例类型
   如果不需要依赖组件导入，也可以直接定义类型：

<script setup lang="ts">
// 定义组件实例的类型
type SomeCompInstance = {
  open: () => void;
};

const someComp = ref<SomeCompInstance | null>(null);
</script>

同样在模板中使用?.调用方法，确保类型安全。

注意事项 #

• 不要直接在模板中使用$refs.someComp调用方法，因为$refs的类型默认是unknown，TypeScript无法识别具体组件类型。
• 始终给ref变量加上| null的类型，因为组件挂载前ref的值是null，可选链?.会自动处理这种情况，避免运行时错误和类型检查报错。

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