如何为Pinia中的代理对象正确实现TypeScript类型定义

问题场景 #

我使用Vue3（setup组合式API）、TypeScript和Pinia（选项式API）开发时，给Pinia状态里的复杂元素定义类型遇到了以下问题：

• 字符串这类原始类型能正常识别，类型标注无报错
• 对象数组、第三方库对象（比如Openlayers的Map）被Pinia包装成Proxy后，手动标注类型会触发不兼容报错；去掉标注又会丢失类型提示

示例代码与错误信息 #

基础场景代码（state.ts）

interface myObject {
  id: number
  name: string
}
interface State {
  myFavColor: string
  objList: myObject[]
}

export const useMyStore = defineStore("myStore", {
  state: (): State => ({
    myFavColor: "orange",
    objList: objService.fetchObjList(),
  }),
  getters: {
    gimmeMyFavColor: (state): string => state.myFavColor,
    gimmeObjList: (state): myObject[] => state.objList
  },
  actions: {},
});

组件使用代码（myComp.vue）

<script setup>
// 原始类型正常
const myFavCol: string = useMyStore.gimmeMyFavColor
console.log('myFavCol', myFavCol, typeof myFavCol)
// -> 'myFavCol', orange, string

// 对象数组触发类型错误
const myObjList: myObject[] = useMyStore.gimmeObjList
console.log('myObjList', myObjList, typeof myObjList)
// -> 'myObjList', [...], Proxy(Array)
</script>

Openlayers Map对象场景代码（mapStore.ts）

import type { Map } from "ol";
import { defineStore } from "pinia";

interface State {
  map: Map | null;
}

export const useMapStore = defineStore("mapStore", {
  state: (): State => ({
    map: null,
  }),
  getters: {
    storedMap: (state): Map | null => state.map
  }
});

对应IDE错误

Type '{ on: MapEventHandler<EventsKey>; once: MapEventHandler<EventsKey>; un: MapEventHandler<void>; resizeObserver_: { ...; }; ... 67 more ...; dispose: () => void; } | null' is not assignable to type 'Map | null'.
  Type '{ on: MapEventHandler<EventsKey>; once: MapEventHandler<EventsKey>; un: MapEventHandler<void>; resizeObserver_: { ...; }; ... 67 more ...; dispose: () => void; }' is missing the following properties from type 'Map': renderComplete_, loaded_, boundHandleBrowserEvent_, maxTilesLoading_, and 51 more.ts(2322)

解决方案 #

1. 优先让TypeScript自动推导Getter类型 #

Pinia的选项式API中，Getter的返回类型完全可以不用手动标注，TypeScript会根据State的定义自动推导包含Proxy包装的响应式类型，既保留响应式，又不会有类型不兼容问题。

修改后的mapStore示例：

import type { Map } from "ol";
import { defineStore } from "pinia";

interface State {
  map: Map | null;
}

export const useMapStore = defineStore("mapStore", {
  state: (): State => ({
    map: null,
  }),
  getters: {
    // 去掉手动类型标注，TS自动推导正确类型
    storedMap: (state) => state.map
  }
});

2. 组件使用的正确姿势 #

组件中必须先实例化Store，再访问实例上的Getter，而不是直接调用Store类的静态属性：

<script setup>
import { useMyStore } from './state.ts';
// 先实例化Store
const store = useMyStore();

// 直接访问实例的getter，TS自动识别类型
const myFavCol = store.gimmeMyFavColor;
const myObjList = store.gimmeObjList;

// Openlayers Map对象的使用
import { useMapStore } from './mapStore.ts';
const mapStore = useMapStore();
const map = mapStore.storedMap;
// 类型自动识别为响应式的Map | null，可直接调用方法
if (map) {
  map.getView(); // 有正确的类型提示
}
</script>

3. 若需手动标注类型的处理方式 #

如果一定要手动标注Getter返回类型，可以利用Pinia提供的StoreState工具类型，或者通过ReturnType推导响应式状态类型：

import type { Map } from "ol";
import { defineStore, StoreState } from "pinia";

interface State {
  map: Map | null;
}

export const useMapStore = defineStore("mapStore", {
  state: (): State => ({
    map: null,
  }),
  getters: {
    // 使用StoreState获取已处理响应式的状态类型
    storedMap: (state: StoreState<typeof useMapStore>): StoreState<typeof useMapStore>["map"] => state.map
  }
});

问题根源 #

Pinia会对状态中的对象/数组进行Proxy响应式包装，而你手动标注的myObject[]或Map是原始类型，TypeScript无法识别Proxy与原始类型的兼容性，因此触发报错。Pinia内部已处理了响应式类型的推导逻辑，去掉手动标注即可让TS正确识别包装后的类型。

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