Vue / 系统课时
Props 类型与默认值
Props 类型与默认值
本课解决 Vue 3 组件如何用 TypeScript 声明必填、可选和联合类型 Props,并为可选属性设置安全默认值。完成后,你可以让父组件获得准确提示,同时避免数组、对象默认值被多个组件实例共享。
学习目标
- 使用类型参数声明必填、可选与联合类型 Props
- 使用
withDefaults为可选属性提供类型安全的默认值 - 掌握数组、对象默认值和父组件传值的关键边界
设计 Props 类型
在 script setup 中,类型式声明使用 defineProps<Props>()。属性名后没有 ? 表示父组件必须传入;带 ? 表示可以省略;字符串字面量联合类型可限制允许值。
Props 应只描述组件真正需要的外部输入。不要把组件内部状态也放进 Props,否则父子职责会混在一起。对于展示组件,优先使用窄类型,让错误在编译阶段暴露。
下面的类型包含两项必填属性、三项可选属性,其中 status 只能取指定字符串:
interface Props {
userId: number
name: string
role?: string
status?: 'active' | 'disabled'
tags?: string[]
}这是类型定义片段,需放在 Vue 单文件组件的 <script setup lang="ts"> 中。它不会直接产生页面输出,但会约束父组件传值和组件内部访问。
使用 withDefaults 设置默认值
withDefaults 与类型式 defineProps 配合,可以在父组件省略可选属性时提供默认值,并让组件内部获得更准确的类型。数组和对象应通过函数返回新值,避免多个组件实例共享同一引用。
下面创建一个可直接使用的 UserCard.vue:
<script setup lang="ts">
interface Props {
userId: number
name: string
role?: string
status?: 'active' | 'disabled'
tags?: string[]
}
const props = withDefaults(defineProps<Props>(), {
role: '普通成员',
status: 'active',
// 每个组件实例都获得独立数组
tags: () => []
})
const statusLabel: Record<NonNullable<Props['status']>, string> = {
active: '启用',
disabled: '停用'
}
</script>
<template>
<article>
<h2>{{ props.name }}</h2>
<p>编号:{{ props.userId }}</p>
<p>角色:{{ props.role }}</p>
<p>状态:{{ statusLabel[props.status] }}</p>
<p>标签:{{ props.tags.length ? props.tags.join('、') : '暂无' }}</p>
</article>
</template>父组件可以只传必填项,也可以覆盖默认值:
<script setup lang="ts">
import UserCard from './components/UserCard.vue'
</script>
<template>
<UserCard :user-id="1001" name="Ava" />
<UserCard
:user-id="1002"
name="Noah"
role="管理员"
status="disabled"
:tags="['财务', '审核']"
/>
</template>预期结果:
Ava
编号:1001
角色:普通成员
状态:启用
标签:暂无
Noah
编号:1002
角色:管理员
状态:停用
标签:财务、审核实际开发服务器端口和构建路径可能不同,但两个组件的页面文本应与上述结果一致。
默认值生效后的类型与边界
role、status 和 tags 在 Props 接口中仍然是可选的,因为父组件可以不传;经过 withDefaults 后,组件内部访问这些属性时已有默认值,不需要再为 undefined 编写重复分支。
默认值必须符合属性类型。例如把 status 默认值写成 'pending' 会触发类型错误,因为联合类型只允许 'active' 或 'disabled'。必填属性缺失、或父组件传入 status="pending" 时,TypeScript 与 IDE 也会提示组件契约不匹配。
defineProps 和 withDefaults 都是编译宏,不需要从 vue 导入,并且应保持在顶层。数组应写成 tags: () => [],对象应写成 options: () => ({});字符串、数字和布尔值可以直接填写默认值。
验证时先检查编辑器类型提示,再运行页面确认默认值。若模板仍提示属性可能为 undefined,通常是没有通过 withDefaults 设置默认值,或在别处重新定义了一个未收窄的变量。
本课总结
defineProps<Props>()可同时表达必填、可选和联合类型约束withDefaults让父组件可省略属性,同时保证组件内部获得默认值- 数组和对象默认值应使用工厂函数,避免实例间共享可变数据
下一课预告
下一课将学习组件事件的类型声明,让子组件发出的事件名称和参数结构在父子组件之间保持一致。