Vue 3 向组件传递多个属性用 v-bind 对象语法

FreeGuideOnline 最新 2026-07-05

```

相当于把 propsObject 中的每个键值对都作为独立的属性传给子组件。如果 propsObject 是 { name: 'Alice', age: 25 }，那么上面这行代码等价于：

<ChildComponent :name="'Alice'" :age="25" />

由于只需要一个 v-bind 即可完成全部传递，模板变得极其干净。

为什么要用对象语法传递多个属性？

在实际项目中，我们经常会遇到一个组件需要接收一组相互关联的配置或数据，例如：

一个 UserCard 组件需要展示头像、姓名、邮箱、角色等信息
一个表单控件需要接收 label、disabled、placeholder、rules 等多个属性
封装第三方 UI 库时，需要透传大量原生 HTML 属性

此时，将这些数据组织成一个对象，再用 v-bind 一次性传入，可以显著减少模板中的重复代码，让代码更容易阅读和维护。更重要的是，当父组件的数据源本来就是对象（例如从 API 获取的用户信息）时，这种写法几乎是零成本的适配。

基础示例：从零搭建一个用户卡片

假设我们有一个 UserCard 组件，它需要接收三个 props：name、avatar 和 bio。

子组件定义

<!-- UserCard.vue -->
<template>
  <div class="user-card">
    <img :src="avatar" :alt="name" />
    <h3>{{ name }}</h3>
    <p>{{ bio }}</p>
  </div>
</template>

<script setup>
const props = defineProps({
  name: String,
  avatar: String,
  bio: String
})
</script>

父组件使用对象语法

<script setup>
import { reactive } from 'vue'
import UserCard from './UserCard.vue'

// 这里模拟从接口获取的用户数据
const userInfo = reactive({
  name: '张三',
  avatar: 'https://example.com/avatar.jpg',
  bio: '前端开发者，热爱开源'
})
</script>

<template>
  <UserCard v-bind="userInfo" />
</template>

可以看到，父组件的模板中仅需一行 <UserCard v-bind="userInfo" /> 就完成了所有属性的传递。当 userInfo 对象中新增加字段时，只要 UserCard 组件也定义了对应的 prop，数据就会自动流入，无需修改绑定代码。这种“数据驱动绑定”的方式大大降低了耦合度。

与其它绑定方式混合使用

对象语法并不会排斥普通的 v-bind 写法。你完全可以在同一个组件标签上将两者结合起来：

<UserCard
  v-bind="userInfo"
  :role="currentRole"
  @click="handleClick"
/>

这种情况下，所有绑定会合并处理。但需要注意一个细节：如果对象中的属性名与单独绑定的属性名发生冲突，后者会覆盖前者。例如 userInfo 中已经包含 role 字段，那么 v-bind 对象里的 role 会被后面的 :role="currentRole" 覆盖。利用这一特性，你可以先用对象传入一组默认数据，再用个别绑定覆盖特殊值。

动态构建对象：与计算属性完美搭档

很多时候，传递给子组件的数据不是现成的对象，而是需要根据父组件状态动态计算出来。这时，结合计算属性是极佳的选择。

<script setup>
import { computed, ref } from 'vue'

const baseInfo = ref({ name: '李四', avatar: '' })
const isAdmin = ref(false)

const cardProps = computed(() => ({
  ...baseInfo.value,
  role: isAdmin.value ? '管理员' : '普通用户',
  disabled: !isAdmin.value
}))
</script>

<template>
  <UserCard v-bind="cardProps" />
</template>

cardProps 会根据 baseInfo 和 isAdmin 的变化自动重新生成，子组件也会即时更新。这种模式特别适合将多个响应式数据合并为统一的对象接口再传递给子组件。

注意事项与常见陷阱

属性名必须与子组件 props 匹配
v-bind 对象中的键名需要和子组件 defineProps 声明的名称完全一致。如果对象中包含子组件未声明的属性，在 Vue 3 中这些属性会默认作为 fallthrough attributes 透传到子组件的根元素上（除非子组件关闭了继承或使用了 defineOptions）。
避免意外覆盖 HTML 属性
当子组件的根元素是原生 HTML 元素时，透传的属性可能会被应用到 DOM 上，例如 class、style、id 等。如果你不想让某些属性透传，可以在子组件中使用 defineOptions({ inheritAttrs: false }) 并手动将 $attrs 绑定到指定元素。

TypeScript 中如何获得类型提示？
使用 <script setup lang="ts"> 时，defineProps 可接受类型标注。但父组件使用 v-bind 对象时，编辑器无法自动检查对象是否完整匹配 props 类型。推荐做法是：导出子组件的 props 类型，在父组件中给对象显式标注类型。

// UserCard.vue
export interface UserCardProps {
  name: string
  avatar: string
  bio?: string
}
const props = defineProps<UserCardProps>()

<!-- 父组件 -->
<script setup lang="ts">
import type { UserCardProps } from './UserCard.vue'
const userInfo: UserCardProps = { name: '王五', avatar: '...' }
</script>