Vue / 系统课时

Props 类型与默认值

Props 类型与默认值

本课解决 Vue 3 组件如何用 TypeScript 声明必填、可选和联合类型 Props,并为可选属性设置安全默认值。完成后,你可以让父组件获得准确提示,同时避免数组、对象默认值被多个组件实例共享。

学习目标

  • 使用类型参数声明必填、可选与联合类型 Props
  • 使用 withDefaults 为可选属性提供类型安全的默认值
  • 掌握数组、对象默认值和父组件传值的关键边界

设计 Props 类型

在 script setup 中,类型式声明使用 defineProps<Props>()。属性名后没有 ? 表示父组件必须传入;带 ? 表示可以省略;字符串字面量联合类型可限制允许值。

Props 应只描述组件真正需要的外部输入。不要把组件内部状态也放进 Props,否则父子职责会混在一起。对于展示组件,优先使用窄类型,让错误在编译阶段暴露。

下面的类型包含两项必填属性、三项可选属性,其中 status 只能取指定字符串:

ts
interface Props {
  userId: number
  name: string
  role?: string
  status?: 'active' | 'disabled'
  tags?: string[]
}

这是类型定义片段,需放在 Vue 单文件组件的 <script setup lang="ts"> 中。它不会直接产生页面输出,但会约束父组件传值和组件内部访问。

使用 withDefaults 设置默认值

withDefaults 与类型式 defineProps 配合,可以在父组件省略可选属性时提供默认值,并让组件内部获得更准确的类型。数组和对象应通过函数返回新值,避免多个组件实例共享同一引用。

下面创建一个可直接使用的 UserCard.vue:

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>

父组件可以只传必填项,也可以覆盖默认值:

vue
<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>

预期结果:

text
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 让父组件可省略属性,同时保证组件内部获得默认值
  • 数组和对象默认值应使用工厂函数,避免实例间共享可变数据

下一课预告

下一课将学习组件事件的类型声明,让子组件发出的事件名称和参数结构在父子组件之间保持一致。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

Props 类型与默认值

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通