Vue 3 双向数据绑定

双向数据绑定在前端最早用在 KO、AngularJS 这些 MVVM 框架中，它是 Vue 从诞生就一直有的特性。使用 v-model 可以在组件上实现双向绑定，方便表单应用的开发。相比 Vue 2，Vue 3 的双向绑定功能得到了增强，具体表现在以下几个方面：

• 支持 v-model 的参数
• 支持多个 v-model 绑定
• 支持自定义 v-model 修饰符

v-model 的参数

在 Vue 2 中，默认情况下，v-model 在组件上都是使用 value 作为 prop，并以 input 作为对应的事件。对于单选框、复选框等类型的单个输入控件，可以通过设置 model 选项的 prop 为 checked， event 为 change。无论设不设置 model 选项，这些名称都是固定不变的。

在 Vue 3 中，默认情况下，v-model 在组件上都是使用 modelValue 作为 prop，并以 update:modelValue 作为对应的事件。

<!-- CustomInput.vue -->
<script setup lang="ts">
  defineProps<{ modelValue?: string }>()
  const emit = defineEmits<{ (e: 'update:modelValue', vlaue: string): void }>()
</script>

<template>
  <input
    :value="modelValue"
    @input="emit('update:modelValue', ($event.target as HTMLInputElement).value)"
  />
</template>

这样我们就自定义了一个支持 v-model 的 Vue 3 组件。在宿主组件中使用时与 Vue 2 中相同：

<!-- App.vue -->
<script lang="ts" setup>
import { ref } from 'vue'
import CustomInput from './components/CustomInput.vue'

const message = ref('hello')
</script>
<template>
  <CustomInput `v-model`="message" />
  <p>{{ message }}</p>
</template>

不同的是，在 Vue 3 中，prop 和事件的名称时可变的：

<script setup lang="ts">
defineProps<{ title?: string }>()
const emit = defineEmits<{ (e: 'update:title', vlaue: string): void }>()
</script>

<template>
  <input
    :value="modelValue"
    @input="emit('update:title', ($event.target as HTMLInputElement).value)"
  />
</template>

上述示例中，我们为自定义组件设置了 title prop 和 update:title 事件。因此，使用时，我们要给 v-model 指定一个参数来更改这些名称，如下面示例中的参数 title:

<template>
  <CustomInput `v-model`:title="message" />
  <p>{{ message }}</p>
</template>

默认的 v-model 参数为 modelValue，为了简便，一般在使用是会省去该参数。

注意：双向绑定 prop 和事件名也不是任意的，规则是：事件名 = update: + prop 名，这和为组件 prop 自定义 .sync 修饰符时需要遵从的模式类似。

为 v-model 参数指定参数与事件名不仅表达了绑定的意图，更重要的意义在于，它使绑定多个 v-model成为可能。

绑定多个 v-model

在 Vue 2 中，只能绑定一个 v-model，但可以通过 .sync 修饰符“双向绑定”多个 prop。Vue 3 借鉴并简化了 .sync 修饰符模式，直接支持多个 v-model 绑定。

// ...
import { computed } from 'vue'

const props = withDefaults(
  defineProps<{
    modelValue?: string
    percent?: number
    modelModifiers?: {
      capitalize: boolean
    }
  }>(),
  {
    modelValue: '',
    percent: 0
  }
)

const emit = defineEmits<{
  (e: 'update:modelValue', value: string): void
  (e: 'update:percent', value: number): void
}>()

const changeValue = (event: Event) => {
  let value = (event.target as HTMLInputElement).value
  emit('update:modelValue', value)
}

const current = computed({
  get() {
    return Math.round(props.percent * 100)
  },
  set(value: number) {
    emit('update:percent', value / 100)
  }
})

上述示例中，我们自定义了两个 v-model: modelValue 和 percent。

如你所见，上述示例在组件内实现 v-model 的方式是使用一个可写的 computed 属性。get 方法需返回 percent prop，而 set 方法需触发相应的 update:percent 事件。

组件上的每一个 v-model 都会同步不同的 prop，而无需额外的选项：

<Form
  v-model="name"
  v-model:percent.number="percent"
/>

有了多个 v-model 绑定，可以不用再为表单中的每个字段都自定义一个支持 v-model 的组件，现在可以只自定义一个表单组件，每个字段绑定一个 v-model。

自定义 v-model 修饰符

在 Vue 2 中，我们可以在 v-model 上使用一些内置的修饰符，例如 .trim，.number 和 .lazy。在 Vue 3 中，我们可以继续使用这些修饰符，而且还可以自定义修饰符。帅吧✌️

1. 首先声明 modelModifiers prop，它的默认值是一个空对象：

modelModifiers?: {
  capitalize: boolean
}

注意这里组件的 modelModifiers prop 包含了 capitalize 且其值为 true，它在模板中的 v-model 绑定时会用到。

2. 可以检查 modelModifiers 对象的键，并编写一个处理函数：每次 <input> 元素触发 input 事件时将值的首字母大写：

   if (props.modelModifiers?.capitalize) {
     value = value.charAt(0).toUpperCase() + value.slice(1)
   }

3. 使用时直接在 v-model 后面加 .capitalize：

<Form
  v-model.capitalize="name"
  v-model:percent.number="percent"
/>

对于又有参数又有修饰符的 v-model 绑定，生成的 prop 名将是：参数名 + 修饰符名。

测试 v-model

基本套路是通过 props 渲染选项传入 prop 初始值，然后断言这些初始值是否正确。接下来更改组件值，断言是否派发了相应 update 事件：

import { render, fireEvent } from '@testing-library/vue'
import Form from './Form.vue'

test('v-model', async () => {
  const { emitted, getByRole, rerender } = render(Form, {
    props: {
      modelValue: '',
      modelModifiers: {
        capitalize: true
      }
    }
  })
  const nameInput = getByRole('textbox')
  expect(nameInput).toHaveValue('')
  await fireEvent.update(nameInput, 'something')
  expect(emitted()['update:modelValue'][0]).toEqual(['Something'])

  await rerender({
    percent: 0
  })
  const percentInput = getByRole('spinbutton')
  expect(percentInput).toHaveValue(0)

  await fireEvent.update(percentInput, '24')
  expect(emitted()['update:percent'][0]).toEqual([0.24])
})

Vue Testing Library v6.1 新增了 rerender 渲染器方法， 类似 Vue Test Utils 中的 setProps 包裹器方法，我们可以在单个测试用例中动态更改 props 渲染选项。

参考链接

• 组件 v-model
• 自定义组件的 v-model
• .sync 修饰符
• Vue 双向数据绑定
• 自定义富文本的 v-model
• 访问 codesandbox 查看项目代码