Vue 3 中用 TypeScript 接口定义复杂 Props 的核心是“写清楚、收得住、用得稳”：先用 interface 明确定义嵌套结构，再通过 defineProps 泛型引用，必要时用 withDefaults 提供安全默认值，并可选 PropType 实现运行时校验。
Vue 3 中用 TypeScript 接口定义复杂 Props，核心是把结构“写清楚、收得住、用得稳”——接口描述形状，defineProps 声明接收，必要时用 withDefaults 补默认值。
用 interface 明确定义对象结构
复杂 Props 往往是嵌套对象或数组，直接写内联类型易出错、难复用。推荐先建接口，把字段、可选性、联合类型都列明白：
- 基础示例：用户资料含 ID、姓名、权限列表（字符串字面量联合）
interface UserProfile {
id: number;
name: string;
permissions: ('read' | 'write' | 'delete')[];
avatarUrl?: string; // 可选字段
}
这样后续所有用到该结构的地方都能复用，IDE 也能精准推导属性和类型错误。
立即学习“前端免费学习笔记（深入）”；
Vue Composition Analyzer
下载
分析 Vue 3 Composition API 使用情况——审计响应式模式、可组合函数设计、ref 与 reactive 的选择、计算属性、watcher 使用及组件……
在 defineProps 中引用接口类型
声明 Props 时直接传入接口作为泛型参数，TypeScript 会自动校验传入数据是否符合结构：
- 简单写法（推荐用于纯 TS 项目）：
defineProps<{ profile: UserProfile; theme?: 'light' | 'dark' }>() - 更清晰的写法（尤其含多个复杂字段时）：
defineProps<{ user: UserProfile; config: AppConfig; tags: string[] }>()
注意：此时不支持运行时校验（如 required: true），但编译期类型检查已足够强。若需运行时保障，可搭配 PropType（见下一点）。
需要运行时校验？用 PropType + interface
当组件要被 JS 项目调用，或你坚持保留 Vue 的运行时 props 校验逻辑时，可用 PropType 搭配接口断言：
import { PropType } from 'vue'user: { type: Object as PropType<UserProfile>, required: true }- 数组同理：
items: { type: Array as PropType<Product[]>, default: () => [] }
这种方式兼顾了 TypeScript 类型安全与 Vue 运行时的 required、default、validator 等能力。
带默认值的复杂对象必须用 withDefaults
接口定义的是“形状”，但对象/数组的默认值不能直接写死（比如 {} 或 []），否则会污染所有实例。必须用工厂函数返回新副本：
- 错误写法：
config: { type: Object as PropType<AppConfig>, default: {} }❌ - 正确写法：
config: { type: Object as PropType<AppConfig>, default: () => ({ timeout: 5000, retries: 3 }) }✅ - 配合
withDefaults更简洁：const props = withDefaults(defineProps<{ options: Option[]; color: string }>(), { options: () => [{ label: '默认项', value: 'default' }], color: 'blue' })
