Vue3 v-model：组件通信的语法糖

本文是 Vue3 系列第十四篇，将深入探讨 Vue3 中 v-model 的实现原理和在组件上的应用。v-model 是 Vue 中一个非常重要的指令，它简化了表单输入元素和组件之间的双向数据绑定。理解 v-model 的底层实现，不仅能够帮助我们更好地使用 UI 组件库，还能让我们在自定义组件时实现类似的双向绑定功能。

一、v-model 的重要性

UI 组件库大量使用 v-model

在现代前端开发中，我们经常会使用各种 UI 组件库，比如 Element Plus、Ant Design Vue、Vuetify 等。这些组件库的许多组件都支持 v-model，例如：

<!-- Element Plus 的输入框 -->
<el-input v-model="inputValue" />

<!-- Ant Design Vue 的选择器 -->
<a-select v-model="selectedValue" />

<!-- Vuetify 的开关 -->
<v-switch v-model="isActive" />

这些组件库之所以大量使用 v-model，是因为它提供了一种简洁、直观的方式来处理组件的双向数据绑定。用户不需要关心具体的属性名和事件名，只需要一个 v-model 指令就能实现数据的同步更新。

面试中的重要性

虽然在日常工作中，我们可能只是简单地使用 v-model，但在面试中，面试官经常会深入考察 v-model 的实现原理。这是因为理解 v-model 的底层机制，能够体现一个开发者对 Vue 响应式系统和组件通信机制的深入理解。

理解 v-model 的原理，不仅有助于我们更好地使用现有的 UI 组件库，还能让我们在需要自定义复杂组件时，实现类似的双向绑定功能。这是一种非常重要的能力，能够显著提高我们的开发效率和代码质量。

剖析 v-model 的实现方式

要理解 v-model，我们需要知道它实际上是一个语法糖。所谓语法糖，就是一种简化代码的写法，它在底层会被转换为更复杂的代码。理解这种转换过程，就是理解 v-model 本质的关键。

二、v-model 用在 HTML 标签上

基本的 v-model 使用

让我们从一个最简单的例子开始：在一个普通的输入框上使用 v-model。

<template>
  <div>
    <input type="text" v-model="username" />
    <p>你输入的用户名是：{{ username }}</p>
  </div>
</template>

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

const username = ref('')
</script>

这个例子展示了一个非常典型的 v-model 用法。我们在 input 元素上使用 v-model="username"，将输入框的值与 username 这个响应式变量绑定在一起。当用户在输入框中输入内容时，username 的值会自动更新；当 username 的值在代码中被修改时，输入框的显示内容也会自动更新。

v-model 的等价写法

实际上，v-model="username" 这行代码在底层会被转换为更复杂的形式。让我们来看看它的等价写法：

<template>
  <div>
    <input 
      type="text" 
      :value="username" 
      @input="username = ($event.target as HTMLInputElement).value"
    />
    <p>你输入的用户名是：{{ username }}</p>
  </div>
</template>

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

const username = ref('')
</script>

这两段代码的效果是完全一样的。让我们来仔细分析一下这个等价写法：

1. :value="username"：这是属性绑定，它将输入框的 value 属性绑定到 username 变量上。当 username 的值发生变化时，输入框的显示内容会自动更新。

2. @input="username = ($event.target as HTMLInputElement).value"：这是事件监听，它监听输入框的 input 事件。当用户在输入框中输入内容时，这个事件会被触发，然后执行赋值语句，将输入框的当前值赋给 username 变量。

这里的关键是 $event 变量。在 Vue 的事件处理中，$event 代表了事件对象。对于原生的 DOM 事件，$event 就是浏览器原生的事件对象。所以 $event.target 就是触发事件的元素（这里是 input 元素），$event.target.value 就是输入框的当前值。

注意这里的类型断言 as HTMLInputElement。这是因为 TypeScript 不知道 $event.target 的具体类型，我们需要明确告诉它这是一个 HTMLInputElement 类型的元素，这样我们才能访问其 value 属性。

理解 v-model 的双向绑定

通过这个例子，我们可以清楚地看到 v-model 实现双向绑定的原理：

1. 数据到视图的绑定 ：通过 :value="username" 实现。当数据变化时，视图自动更新。

2. 视图到数据的绑定 ：通过 @input="username = $event.target.value" 实现。当用户操作视图时，数据自动更新。

这两者结合在一起，就实现了双向数据绑定：数据变化影响视图，视图变化也影响数据。

三、v-model 用在组件上

直接使用 v-model 的问题

现在，让我们尝试在一个自定义组件上使用 v-model。假设我们有一个自定义的输入框组件 TestInput：

<!-- TestInput.vue -->
<template>
  <div>
    <input type="text" />
  </div>
</template>

在父组件中，我们尝试像使用原生 input 一样使用 v-model：.

<!-- Parent.vue -->
<template>
  <div>
    <TestInput v-model="username" />
    <p>你输入的用户名是：{{ username }}</p>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import TestInput from './TestInput.vue'

const username = ref('')
</script>

你会发现，这样做没有任何效果。当你在输入框中输入内容时，username 的值不会更新；当你修改 username 的值时，输入框的显示内容也不会更新。

这是为什么呢？因为 Vue 不知道如何处理组件上的 v-model。对于原生 HTML 元素，Vue 知道如何将其转换为对应的属性和事件绑定。但对于自定义组件，Vue 需要我们的明确指示。

拆解 v-model 的本质

那么，UI 组件库是如何让它们的组件支持 v-model 的呢？答案在于 v-model 在组件上的本质。

在 Vue 3 中，当我们在组件上使用 v-model="username" 时，它实际上会被转换为：

<TestInput 
  :modelValue="username" 
  @update:modelValue="username = $event" 
/>

让我们来详细解释这个转换：

1. :modelValue="username"：这是一个 prop 绑定。它向子组件传递一个名为 modelValue 的 prop，值为 username。

2. @update:modelValue="username = $event"：这是一个事件监听。它监听子组件触发的 update:modelValue 事件，当事件触发时，将事件携带的数据赋给 username。

这里的 modelValue 和 update:modelValue 是 Vue 3 中的默认约定。在 Vue 2 中，v-model 在组件上的实现略有不同，使用的是 value 属性和 input 事件。Vue 3 改为 modelValue 和 update:modelValue，主要是为了支持多个 v-model 绑定，我们后面会详细讨论。

让组件支持 v-model

既然知道了 v-model 在组件上的本质，我们就可以让我们的 TestInput 组件支持 v-model 了。我们需要做两件事：

1. 接收 modelValue prop

2. 在适当的时候触发 update:modelValue 事件

让我们修改 TestInput 组件：

<!-- TestInput.vue -->
<template>
  <div>
    <input 
      type="text" 
      :value="modelValue" 
      @input="$emit('update:modelValue', ($event.target as HTMLInputElement).value)"
    />
  </div>
</template>

<script setup>
// 接收 modelValue prop
defineProps(['modelValue'])

// 定义 update:modelValue 事件
defineEmits(['update:modelValue'])
</script>

现在，我们的 TestInput 组件已经支持 v-model 了。让我们分析一下这段代码：

1. :value="modelValue"：将输入框的 value 属性绑定到从父组件接收到的 modelValue prop 上。这样，当父组件传递的 modelValue 发生变化时，输入框的显示内容会自动更新。

2. @input="$emit('update:modelValue', $event.target.value)"：监听输入框的 input 事件，当用户输入时，触发 update:modelValue 事件，并将输入框的当前值作为参数传递。

3. defineProps(['modelValue'])：声明接收一个名为 modelValue 的 prop。

4. defineEmits(['update:modelValue'])：声明可以触发一个名为 update:modelValue 的事件。

这样，当用户在输入框中输入内容时，会触发 input 事件，然后组件会触发 update:modelValue 事件，父组件监听到这个事件后，会更新 username 的值，然后新的值又会通过 modelValue prop 传递回子组件，更新输入框的显示内容。这就实现了完整的双向数据绑定。

理解属性和事件的对应关系

你可能会问，为什么一会儿是 :value 和 @input，一会儿又是 :modelValue 和 @update:modelValue 呢？这里的关键在于我们是在哪个层级上操作。

在组件内部，我们操作的是原生的 input 元素，所以我们使用 :value 和 @input。这是 HTML 标准中 input 元素的属性和事件。

在组件层面，Vue 3 约定使用 :modelValue 和 @update:modelValue 来实现 v-model。当我们使用 v-model="username" 时，Vue 会自动将其转换为这组属性和事件。

所以，完整的链条是这样的：

• 父组件使用 v-model="username"，被转换为 :modelValue="username" 和 @update:modelValue="username = $event"

• 子组件接收 modelValue prop，触发 update:modelValue 事件

• 在子组件内部，将 modelValue 绑定到 input 的 value 属性，监听 input 事件并触发 update:modelValue

回到简洁的 v-model 写法

现在，我们的 TestInput 组件已经配置好了，父组件可以改回使用简洁的 v-model 写法了：

<!-- Parent.vue -->
<template>
  <div>
    <TestInput v-model="username" />
    <p>你输入的用户名是：{{ username }}</p>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import TestInput from './TestInput.vue'

const username = ref('')
</script>

这样，我们就实现了在自定义组件上使用 v-model。你会发现，现在它的工作方式与在原生 input 上使用 v-model 完全一样。

理解 $event 的两种含义

这里有一个非常重要的细节需要注意：$event 在原生事件和自定义事件中有不同的含义。

在原生事件中，$event 是事件对象。例如，在 @input="$emit('update:modelValue', $event.target.value)" 中，$event 是原生的 input 事件对象，所以我们通过 $event.target.value 获取输入框的值。

在自定义事件中，$event 是触发事件时传递的数据。例如，在父组件的 @update:modelValue="username = $event" 中，$event 就是子组件触发事件时传递的值（输入框的当前值），所以我们可以直接将其赋给 username。

这种区别是理解 Vue 事件处理的关键。原生事件的 $event 是浏览器提供的事件对象，而自定义事件的 $event 是我们自己定义的数据。

四、v-model 的细节和高级用法

修改默认的 prop 名

在某些情况下，我们可能不想使用默认的 modelValue 作为 prop 名。例如，我们的组件可能同时需要绑定多个值，或者 modelValue 这个名称与组件的其他 prop 冲突。

Vue 3 允许我们修改 v-model 的默认 prop 名。语法是 v-model:自定义名称。例如：

<!-- Parent.vue -->
<template>
  <div>
    <TestInput v-model:title="username" />
    <p>你输入的用户名是：{{ username }}</p>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import TestInput from './TestInput.vue'

const username = ref('')
</script>

这里，我们使用 v-model:title 代替了普通的 v-model。这意味着 Vue 会使用 title 作为 prop 名，使用 update:title 作为事件名。

相应地，我们需要修改子组件：

<!-- TestInput.vue -->
<template>
  <div>
    <input 
      type="text" 
      :value="title" 
      @input="$emit('update:title', ($event.target as HTMLInputElement).value)"
    />
  </div>
</template>

<script setup>
// 接收 title prop
defineProps(['title'])

// 定义 update:title 事件
defineEmits(['update:title'])
</script>

这样，我们就将默认的 modelValue 改为了 title。这在需要多个 v-model 绑定时特别有用。

多个 v-model 绑定

在 Vue 3 中，我们可以在一个组件上使用多个 v-model 绑定。这在处理表单等复杂场景时非常有用。

假设我们有一个登录表单组件，需要同时绑定用户名和密码：

<!-- Parent.vue -->
<template>
  <div>
    <LoginForm 
      v-model:username="formData.username" 
      v-model:password="formData.password" 
    />
    <p>用户名：{{ formData.username }}</p>
    <p>密码：{{ formData.password }}</p>
  </div>
</template>

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

const formData = reactive({
  username: '',
  password: ''
})
</script>

在子组件中，我们需要分别处理这两个 v-model：

<!-- LoginForm.vue -->
<template>
  <div class="login-form">
    <div>
      <label>用户名：</label>
      <input 
        type="text" 
        :value="username" 
        @input="$emit('update:username', ($event.target as HTMLInputElement).value)"
      />
    </div>
    <div>
      <label>密码：</label>
      <input 
        type="password" 
        :value="password" 
        @input="$emit('update:password', ($event.target as HTMLInputElement).value)"
      />
    </div>
  </div>
</template>

<script setup>
// 接收多个 prop
defineProps(['username', 'password'])

// 定义多个事件
defineEmits(['update:username', 'update:password'])
</script>

这样，我们就实现了一个组件支持多个 v-model 绑定。这种方式让组件的使用更加灵活，特别是在处理复杂表单时，可以大大简化代码。

每个 v-model 绑定都是独立的：v-model:username 绑定到 username prop 和 update:username 事件，v-model:password 绑定到 password prop 和 update:password 事件。

五、总结

通过本文的学习，我们深入理解了 v-model 的实现原理和在组件上的应用。

v-model 的本质

v-model 是一个语法糖，它在不同场景下有不同的实现：

1. 在原生 HTML 元素上 ：v-model="value" 等价于 :value="value" @input="value = $event.target.value"

2. 在组件上（默认） ：v-model="value" 等价于 :modelValue="value" @update:modelValue="value = $event"

3. 在组件上（自定义 prop 名） ：v-model:propName="value" 等价于 :propName="value" @update:propName="value = $event"

实现组件支持 v-model 的步骤

要让一个组件支持 v-model，需要做两件事：

1. 接收 prop ：通过 defineProps 接收相应的 prop（默认是 modelValue，或自定义的名称）

2. 触发事件 ：在适当的时候通过 $emit 触发相应的事件（默认是 update:modelValue，或自定义的事件名）

$event 的两种含义

理解 $event 的两种含义非常重要：

1. 在原生事件中 ：$event 是原生的事件对象，可以通过 $event.target.value 等方式获取事件相关的数据

2. 在自定义事件中 ：$event 是触发事件时传递的数据，可以直接使用

v-model 的高级用法

Vue 3 中 v-model 的增强功能：

1. 自定义 prop 名 ：通过 v-model:propName 可以指定自定义的 prop 名

2. 多个 v-model：可以在一个组件上使用多个 v-model 绑定，分别处理不同的数据

理解 v-model 的底层实现，不仅有助于我们更好地使用现有的 UI 组件库，还能让我们在开发自定义组件时，提供更加友好、符合 Vue 生态的 API。这是一种非常重要的能力，能够显著提高我们的组件设计水平和代码质量。

关于 Vue3 的 v-model 有任何疑问？欢迎在评论区提出，我们会详细解答！