Vue3 Composition API自定义TS插件：WebStorm类型提示异常求助

我在WebStorm中使用Vue3 Composition API开发带TypeScript类型增强的自定义i18n插件时遇到问题：功能在运行时正常，但<template>标签中调用$translation会出现警告，<script setup>标签中直接调用该方法则报错。以下是项目配置与代码详情：

项目配置与代码详情 #

1. tsconfig.config.json配置 #

{
  "extends": "@vue/tsconfig/tsconfig.node.json",
  "include": ["vite.config.*", "vitest.config.*", "cypress.config.*", "playwright.config.*", "src/i18n.d.ts"],
  "compilerOptions": {
    "composite": true,
    "types": ["node"]
  }
}

2. package.json配置 #

{
  "name": "my-app",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "dev": "vite",
    "build": "run-p type-check build-only",
    "preview": "vite preview",
    "build-only": "vite build",
    "type-check": "vue-tsc --noEmit",
    "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix --ignore-path .gitignore"
  },
  "dependencies": {
    "pinia": "^2.0.28",
    "vue": "^3.2.45",
    "vue-router": "^4.1.6"
  },
  "devDependencies": {
    "@rushstack/eslint-patch": "^1.1.4",
    "@types/node": "^18.11.12",
    "@vitejs/plugin-vue": "^4.0.0",
    "@vue/eslint-config-typescript": "^11.0.0",
    "@vue/tsconfig": "^0.1.3",
    "eslint": "^8.22.0",
    "eslint-plugin-vue": "^9.3.0",
    "npm-run-all": "^4.1.5",
    "typescript": "~4.7.4",
    "vite": "^4.0.0",
    "vite-plugin-checker": "^0.5.5",
    "vue-tsc": "^1.0.12"
  }
}

3. 项目结构 #

4. 自定义i18n插件代码（src/plugins/i18n.ts） #

import type {App} from "vue";

export default {
    install(app: App, options: any) {
        app.config.globalProperties.$translation = (key: string) =>  {
                const keys = key.split('.');
                return keys.reduce((o: any, i) => {
                    if (o) return o[i]
                }, options);
            }
        }
    }

5. 类型增强文件（src/i18n.d.ts） #

export{}

declare module 'vue' {
    interface ComponentCustomProperties {
        $translation: (key: string) => string;
    }
}

6. main.ts中的插件注册 #

import { createApp } from 'vue'
import { createPinia } from 'pinia'

import App from './App.vue'
import router from './router'
import PrimeVue from 'primevue/config';

import 'primevue/resources/themes/saga-blue/theme.css'      //theme
import 'primevue/resources/primevue.min.css'                 //core css
import 'primeicons/primeicons.css'                           //icons

import './assets/main.css'
import i18n from "@/plugins/i18n"
import pl from "@/plugins/pl.json"

const app = createApp(App)

app.use(createPinia())
app.use(router)
app.use(PrimeVue)
app.use(i18n, pl)
app.mount('#app')

7. 测试用语言包（src/plugins/pl.json） #

{
  "some": {
    "key": "test"
  }
}

8. 组件使用代码（src/views/Home.vue） #

<template>
  <div>
    <input v-color="'red'" />
    {{$translation('some.key')}}
  </div>
</template>
<script setup lang="ts">

import {onMounted} from "vue";

const vColor = {
  mounted: (el: HTMLElement, bind: { value: string}) => {
    el.style.color = bind.value;
  }
}

const test = $translation('some.key');

onMounted(() => {
  console.log(test)
})

</script>

具体异常 #

• <template>中调用{{$translation('some.key')}}出现警告（提示“无法解析名称 $translation”），但运行时正常显示内容；
• <script setup>中直接声明const test = $translation('some.key')报错（提示“找不到名称 '$translation'”）。

解决步骤 #

1. 修正主TypeScript配置的文件引用 #

当前i18n.d.ts仅被tsconfig.config.json（Node环境配置）包含，主项目的tsconfig.json需要添加该文件的引用。修改主tsconfig.json的include数组：

{
  "extends": "@vue/tsconfig/tsconfig.web.json",
  "include": ["env.d.ts", "src/**/*", "src/**/*.vue", "src/i18n.d.ts"],
  // 其他配置...
}

2. 在<script setup>中正确获取全局属性 #

Vue3的<script setup>语法无法直接访问globalProperties上的属性，需通过getCurrentInstance()获取：

<script setup lang="ts">
import {onMounted, getCurrentInstance} from "vue";

const vColor = {
  mounted: (el: HTMLElement, bind: { value: string}) => {
    el.style.color = bind.value;
  }
}

// 获取组件实例并提取$translation方法
const instance = getCurrentInstance();
const $translation = instance?.proxy?.$translation as (key: string) => string;

onMounted(() => {
  if ($translation) {
    const test = $translation('some.key');
    console.log(test);
  }
})
</script>

3. 重启IDE并验证 #

修改配置后重启WebStorm，执行npm run type-check确认类型检查通过，此时模板和脚本中的类型提示应该正常。

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