为何Vue使用PropType<GeographicCoordinate|null>仍触发props类型校验失败？

环境 #

• Vue.js ^3.2.13
• TypeScript
• Composition API
• Visual Studio Code

相关代码文件 #

type.ts #

export class GeographicCoordinate {
  latitude: number;
  longitude: number;
  altitude?: number;

  constructor(latitude: number, longitude: number, altitude?: number) {
    this.latitude = latitude;
    this.longitude = longitude;
    this.altitude = altitude;
  }
}

component1.vue #

import { GeographicCoordinate } from '@/interfaces/type';
const props = defineProps({
  geographicCoordinate: {
    type: Object as PropType<GeographicCoordinate | null>, 
    required: true }
});

page.vue #

<template>
  <component1
    :geographic-coordinate="clickedGeographicCoordinate" @save-event="saveEvent">
  </component1>
</template>
<script lang="ts" setup>
  import { GeographicCoordinate } from '@/interfaces/type';
  var clickedGeographicCoordinate = ref<GeographicCoordinate | null>(null);
</script>

问题现象 #

VS Code无类型错误提示，但Chrome控制台出现Vue警告：

[Vue warn]: Invalid prop: type check failed for prop "geographicCoordinate". Expected Object, got Null

问题原因 #

Vue运行时的prop校验与TypeScript编译时类型检查是两套独立机制：

1. TypeScript层面通过PropType<GeographicCoordinate | null>定义了允许null的类型，所以编辑器不会报错，但这仅作用于编译阶段。
2. Vue运行时校验中，你指定的type: Object仅接受对象类型，null不在允许范围内；同时required: true会让Vue认为prop必须是有效非空值，传入null会触发类型不匹配警告。

最佳实践 #

要让组件同时接收类实例或null作为prop值，可按以下方式调整：

方案1：直接允许null类型 #

修改component1.vue的prop定义，在类型列表中加入null，并调整required配置：

import { GeographicCoordinate } from '@/interfaces/type';
const props = defineProps({
  geographicCoordinate: {
    type: [Object, null] as PropType<GeographicCoordinate | null>,
    required: false,
    default: null
  }
});

• type: [Object, null]告知Vue运行时接受对象或null类型
• 因允许null，required需设为false，否则Vue会判定未提供有效必填prop

方案2：用自定义校验确保类实例合法性 #

如果需要严格校验传入值是GeographicCoordinate实例或null，可使用validator函数：

import { GeographicCoordinate } from '@/interfaces/type';
const props = defineProps({
  geographicCoordinate: {
    type: Object as PropType<GeographicCoordinate | null>,
    required: false,
    validator: (value: unknown) => {
      return value === null || value instanceof GeographicCoordinate;
    }
  }
});

该方案能在运行时精准校验，避免传入其他类型的对象。

补充：必填但允许为null的场景 #

若业务上需要prop"必填"（必须传入值，哪怕是null），可保留required: true并在类型中包含null：

const props = defineProps({
  geographicCoordinate: {
    type: [Object, null] as PropType<GeographicCoordinate | null>,
    required: true
  }
});

此时Vue会认为只要传入了值（包括null）就满足必填要求，同时通过类型校验。

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