Vue 3 中通过泛型接口 + defineProps<T> 实现强类型、高复用 Props，支持自动推导结构、默认值与事件类型，类型安全边界在调用侧而非定义侧。
在 Vue 3 中结合 TypeScript 泛型接口定义 Props，核心是让 defineProps 接收一个泛型类型参数，使组件能根据传入的具体类型自动推导 props 结构、默认值行为和校验逻辑，从而实现真正高复用、强类型、零运行时冗余的组件设计。
用泛型接口 + defineProps<T> 声明可复用 Props 类型
不直接写死具体类型，而是定义一个泛型接口描述“具备哪些能力”的 props 结构。例如封装一个通用列表渲染器：
interface ListProps<T> {
data: T[];
keyField?: keyof T | ((item: T) => string | number);
renderItem: (item: T, index: number) => VNode;
emptyText?: string;
}
然后在组件中这样使用：
const props = defineProps<ListProps<User>>();
此时 props.data 自动为 User[]，keyField 可安全取 User 的任意键（如 'id' 或 'name'），renderItem 的 item 参数也精准是 User 类型 —— 所有类型信息全程保留在编译期，无断言、无 any。
立即学习“前端免费学习笔记（深入）”；
配合 withDefaults 实现泛型默认值与类型守恒
泛型 props 配合 withDefaults 时，必须确保默认值不破坏泛型约束。推荐写法是先声明泛型接口，再用 withDefaults 包裹它：
const props = withDefaults(
defineProps<ListProps<T>>(),
{
emptyText: '暂无数据',
keyField: 'id' as keyof T | ((item: T) => string | number),
}
) as ListProps<T> & { emptyText: string; keyField: keyof T | ((item: T) => string | number) };
更稳妥的做法是把默认值逻辑下沉到泛型接口内部（适用于 Vue 3.4+）：
interface ListProps<T> {
data: T[];
keyField?: keyof T | ((item: T) => string | number);
renderItem: (item: T, index: number) => VNode;
emptyText?: string;
}
const props = defineProps<ListProps<User>>(); // 类型推导仍完整
const defaults = {
emptyText: '暂无数据',
keyField: 'id' as const,
} as const;
// 使用时通过 computed 或逻辑判断 fallback，默认值不参与泛型推导即可保持干净
用泛型 Props 支持多态事件与响应式联动
泛型不只是约束输入，还可约束输出。比如给列表加点击回调，让父组件接收精确的子项类型：
interface ListProps<T> {
data: T[];
onItemClick?: (item: T, index: number) => void;
// ...其他字段
}
const emit = defineEmits<{
(e: 'item-click', item: T, index: number): void;
}>();
// 子组件内触发时，emit('item-click', item, i) 的 item 类型就是 T，父组件监听时也能获得完整类型提示
这样父子通信链路全程类型闭环，无需额外 cast，也不依赖运行时 key 字符串匹配。
避免常见陷阱：泛型不能出现在顶层 props 默认值或 required 校验中
Vue 的 defineProps 编译阶段不支持泛型表达式作为默认值或 required 判断依据。以下写法 ❌ 会报错或失去类型：
-
data?: T[]—— 应改为data: T[]（必填）或用data?: T[] | undefined显式标注可选 -
required: true写在泛型字段上 —— Vue 不识别泛型条件，required 应基于具体调用时的类型实参来决定 - 在
withDefaults中对泛型字段写keyField: 'id' as keyof T—— 编译器无法确认'id'是否属于所有T，应改用keyField?: keyof T并由使用者保障
本质是：泛型约束发生在组件**被使用时**（即父组件传入 User 或 Product），而非定义时。所以所有类型安全边界要落在调用侧和接口契约上，而非定义侧硬编码。
