Vue3 中 PropType 的使用指南

Vue3中的PropType是TypeScript类型工具，用于精确定义组件props的类型，特别适用于复杂类型。

---

文章介绍了基本用法（简单类型、对象、数组、函数定义）、高级用法（联合类型、嵌套对象、函数类型）以及最佳实践（分离类型定义、泛型组件、组合式API配合）。

---

重点注意事项包括：PropType仅提供TS类型检查、默认值需用工厂函数、required属性的类型匹配以及自定义验证器的使用。

---

通过PropType可显著提升Vue3组件的类型安全性，是TS项目的必备工具。

---

在 Vue 3 中，PropType 是一个 TypeScript 类型工具，用于为组件的 props 提供更精确的类型定义。

---

它特别适用于定义复杂类型（如对象、数组、函数等）的 props。

---

基本用法

1. 简单类型定义

import { defineComponent, PropType } from 'vue'

export default defineComponent({
  props: {
    // 基本类型
    title: String,
    count: Number,
    isActive: Boolean,
    
    // 使用 PropType 定义复杂类型
    user: Object as PropType<{ name: string; age: number }>,
    
    // 数组类型
    tags: Array as PropType<string[]>,
    
    // 函数类型
    onSubmit: Function as PropType<(data: any) => void>,
  }
})

2. 接口/类型别名使用

import { defineComponent, PropType } from 'vue'

// 定义接口
interface User {
  id: number
  name: string
  email: string
}

// 定义类型
type Status = 'active' | 'inactive' | 'pending'

export default defineComponent({
  props: {
    // 使用接口
    user: {
      type: Object as PropType<User>,
      required: true
    },
    
    // 使用类型别名
    status: {
      type: String as PropType<Status>,
      default: 'pending'
    },
    
    // 嵌套对象
    config: {
      type: Object as PropType<{
        color: string
        size: 'sm' | 'md' | 'lg'
        enabled: boolean
      }>,
      default: () => ({})
    }
  }
})

高级用法

1. 联合类型

props: {
  value: {
    type: [String, Number, Boolean] as PropType<string | number | boolean>,
    required: true
  }
}

2. 数组和对象组合

interface Product {
  id: number
  name: string
  price: number
}

props: {
  // 对象数组
  products: {
    type: Array as PropType<Product[]>,
    default: () => []
  },
  
  // 复杂嵌套对象
  metadata: {
    type: Object as PropType<{
      pagination: {
        page: number
        limit: number
        total: number
      }
      filters: Record<string, any>
    }>,
    default: () => ({})
  }
}

3. 函数类型

props: {
  // 函数返回值
  getData: {
    type: Function as PropType<() => Promise<any[]>>,
    required: true
  },
  
  // 带参数的函数
  onSuccess: {
    type: Function as PropType<(result: any) => void>,
    default: () => {}
  },
  
  // 事件处理器
  onChange: {
    type: Function as PropType<(event: Event) => void>
  }
}

使用 withDefaults

Vue 3 提供了 withDefaults 来处理带默认值的 props 类型：

import { defineComponent, PropType, withDefaults } from 'vue'

interface Props {
  message?: string
  count?: number
  items?: string[]
}

export default defineComponent({
  props: withDefaults(defineProps<Props>(), {
    message: 'Hello',
    count: 0,
    items: () => []
  })
})

最佳实践

1. 分离类型定义

// types/user.ts
export interface User {
  id: number
  name: string
  role: 'admin' | 'user'
}

// UserProfile.vue
import { User } from '@/types/user'

props: {
  user: {
    type: Object as PropType<User>,
    required: true
  }
}

2. 使用泛型组件

import { defineComponent, PropType } from 'vue'

export default defineComponent({
  props: {
    items: {
      type: Array as PropType<any[]>,
      default: () => []
    },
    itemKey: {
      type: String,
      default: 'id'
    }
  },
  setup(props) {
    // props.items 的类型是 any[]
  }
})

3. 配合组合式 API

import { defineComponent, PropType, computed } from 'vue'

interface User {
  id: number
  name: string
}

export default defineComponent({
  props: {
    users: {
      type: Array as PropType<User[]>,
      default: () => []
    }
  },
  setup(props) {
    // TypeScript 能正确推断 props.users 的类型
    const userNames = computed(() => 
      props.users.map(user => user.name)
    )
    
    return { userNames }
  }
})

---

注意事项

1. 运行时类型检查 ：PropType 只提供 TypeScript 类型检查，运行时 Vue 仍会使用基本的构造函数（如 Object、Array）进行验证。

2. 默认值函数：对象和数组的默认值应使用工厂函数：

   default: () => []  // ✅ 正确
   default: []        // ❌ 错误（会共享引用）

3. required 属性 ：使用 required: true 时，确保 TypeScript 类型也标记为非可选：

   props: {
     user: {
       type: Object as PropType<User>,  // User 应该没有 ? 可选标记
       required: true
     }
   }

4. 自定义验证器：

   props: {
     score: {
       type: Number as PropType<number>,
       validator: (value: number) => {
         return value >= 0 && value <= 100
       }
     }
   }

---

使用 PropType 可以大大提高 Vue 3 组件的类型安全性，特别是在使用 TypeScript 的项目中。