Vue 教程：使用 defineModel 简化组件双向绑定的实现

快速概述

在 Vue 组件开发中，实现父子组件间的双向绑定通常需要手动声明 modelValue prop 并触发 update:modelValue 事件，代码冗长且易错。Vue 3.4 引入的 defineModel 编译宏，允许在子组件中直接声明一个可双向绑定的 ref，自动处理 prop 与事件，大幅简化实现。本教程适用于使用 Vue 3.4+ 组合式 API 的开发者，前置环境要求 Vue 版本不低于 3.4，且使用 <script setup> 语法。

核心概念与原理

defineModel 是 Vue 3.4 新增的编译宏，它会在编译阶段展开为一个名为 modelValue 的 prop 和对应的 update:modelValue 事件。在子组件中，defineModel() 返回一个 ref，该 ref 的值与父组件通过 v-model 传入的值保持同步。当子组件修改这个 ref 时，会自动触发 update:modelValue 事件，将新值传递给父组件，从而完成双向绑定。其底层机制与手动实现完全一致，但省去了显式声明 prop 和事件的样板代码。

实战步骤与代码

步骤 1：创建子组件

在 ChildComponent.vue 中使用 defineModel 声明一个双向绑定值：

<template>
  <input v-model="model" placeholder="输入内容" />
</template>
<script setup> // 声明一个名为 model 的 ref，自动绑定到父组件的 v-model const model = defineModel() </script>

这里 defineModel() 默认使用 modelValue 作为 prop 名，返回的 model 是响应式 ref，可直接在模板中使用 v-model 绑定。

步骤 2：在父组件中使用

在 ParentComponent.vue 中引入子组件并使用 v-model 绑定数据：

<template>
  <ChildComponent v-model="parentData" />
  <p>父组件数据：{{ parentData }}</p>
</template>
<script setup> import { ref } from 'vue' import ChildComponent from './ChildComponent.vue'
const parentData = ref('初始值') </script>

父组件无需额外监听事件，parentData 会随子组件输入自动更新。

步骤 3：使用自定义参数名

若需要多个双向绑定值，可传入参数指定 prop 名：

<!-- 子组件 -->
const title = defineModel('title')
const content = defineModel('content')
<!-- 父组件 --> <ChildComponent v-model:title="title" v-model:content="content" />

这允许组件支持多个 v-model 绑定，提升灵活性。

常见坑点与优化

坑点 1：Vue 版本过低

defineModel 仅在 Vue 3.4+ 中可用，若项目版本低于 3.4，编译时会报错。解决方法是升级 Vue 至最新稳定版，或使用手动 prop/事件方式。

坑点 2：不能直接解构返回值

defineModel() 返回的 ref 不应被解构为普通变量，否则会丢失响应性。应始终以 const model = defineModel() 形式使用。

优化建议

对于复杂组件，建议将 defineModel 与计算属性结合，实现数据校验或转换。例如，在 setter 中处理输入格式化，避免直接修改原始值。此外，当组件仅需单向数据流时，优先使用普通 prop，避免不必要的双向绑定，提升性能。