如何在Vue+TS中定义全局可用的组件Ref类型缩写UnRef

问题核心原因 #

在.d.ts文件顶层写import语句时，TS会将文件识别为独立ES模块，模块内声明的类型默认是模块私有作用域，无法全局生效。 #

具体操作步骤 #

• 第一步：修改全局类型声明文件（一般是项目根目录的env.d.ts），将类型定义包裹在declare global块中，依赖类型的导入也放到块内部，最后补充空导出即可：

declare global {
  import type { UnwrapRef } from 'vue'
  import type { RefValue } from 'vue/macros'
  type UnRef<T extends abstract new (...args: any) => any> = RefValue<UnwrapRef<InstanceType<T>>>
}
// 必须补充空导出，避免TS校验报错
export {}

• 第二步：确认tsconfig.json的include配置覆盖了上述声明文件，参考配置如下：

{
  "compilerOptions": {
    // 原有其他配置保持不变即可
  },
  "include": [
    "env.d.ts",
    "src/**/*.ts",
    "src/**/*.d.ts",
    "src/**/*.tsx",
    "src/**/*.vue"
  ]
}

• 第三步：重启TS服务（VSCode中可按Ctrl+Shift+P调出命令面板，选择TypeScript: Restart TS Server），之后全项目任意文件都无需导入，可直接使用UnRef类型。

使用注意 #

如果写let formRef: UnRef<Form> = $ref()提示类型不匹配，把泛型参数改成typeof Form即可，这是TS识别.vue文件导入值的常规兼容写法：

<template>
    <Form ref="formRef" />
</template>

<script lang="ts" setup>
import Form from './Form.vue';
// 两种写法选适配本地TS环境的即可
let formRef: UnRef<typeof Form> = $ref();
</script>

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