组件 v-model

基本用法

v-model可以在组件上使用实现双向绑定

从 Vue 3.4开始,推荐子组件中实现方式市使用defineModel()宏:

<!-- Child.vue -->
<script setup>
  const model = defineModel()

  function update() {
    model.value++
  }
</script>

<template>
  <div>Parent bound v-model is: {{ model }}</div>
  <button @click="update">Increment</button>
</template>

父组件中可以用v-model绑定一个值

<!-- Parent.vue -->
<Child v-model="countModel" />

defineModel() 返回的值是一个 ref。它可以像其他 ref 一样被访问以及修改，不过它能起到在父组件和当前变量之间的双向绑定的作用：

• 它的 .value 和父组件的 v-model 的值同步；
• 当它被子组件变更了，会触发父组件绑定的值一起更新。

这意味着你也可以用 v-model 把这个 ref 绑定到一个原生 input 元素上，在提供相同的 v-model 用法的同时轻松包装原生 input 元素：

<script setup>
  const model = defineModel()
</script>

<template>
  <input v-model="model" />
</template>

底层机制

defineModel是一个便利宏,编译器将其展开为一下内容 :

• 一个名为modelValue的prop,本地ref的值与其相同
• 一个名为update:modelValue的emit方法,在本地ref的值发生变更时触发

在 3.4 版本之前,一般会按照如下方式实现上述相同的子组件

<!-- Child.vue -->
<script setup>
  const props = defineProps(['modelValue'])
  const emit = defineEmits(['update:modelValue'])
</script>

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

然后,父组件中的v-model将会被编译为 :

<!-- Parent.vue -->
<Child :modelValue="foo" @update:modelValue="$event => (foo = $event)" />

因为defineModel声明了一个prop,可以通过给defineModel传递选项来声明底层的prop的选项

// 使 v-model 必填
const model = defineModel({ required: true })

// 提供一个默认值
const model = defineModel({ default: 0 })

注意
如果为defineModel prop 设置了一个default值,但父组件没有为该prop提供任何值,会导致父子组件之间不同步

v-model 参数

<MyComponent v-model:title="bookTitle" />

对应的在子组件中,我们可以通过将字符串作为第一个参数传递给defineModel来支持相应的参数

<!-- MyComponent.vue -->
<script setup>
  const title = defineModel('title')
</script>

<template>
  <input type="text" v-model="title" />
</template>

如果需要额外的选项配置,可以在model名称之后传递

const title = defineModel('title', { required: true })

多个 v-mdoel 绑定

子组件可以定义多个defineModel来支持多个v-model绑定

<UserName v-model:first-name="first" v-model:last-name="last" />

子组件中

<script setup>
  const firstName = defineModel('firstName')
  const lastName = defineModel('lastName')
</script>

<template>
  <input type="text" v-model="firstName" />
  <input type="text" v-model="lastName" />
</template>

3.4 之前的用法

<script setup>
  defineProps({
    firstName: String,
    lastName: String,
  })

  defineEmits(['update:firstName', 'update:lastName'])
</script>

<template>
  <input type="text" :value="firstName" @input="$emit('update:firstName', $event.target.value)" />
  <input type="text" :value="lastName" @input="$emit('update:lastName', $event.target.value)" />
</template>

处理 v-model 修饰符

v-model有一些内置的修饰符,比如 .trim、.number、.lazy等,这些修饰符也可以在子组件中使用.
也可以自定义一个修饰符来实现特有的逻辑,比如:自定义一个capitalize将v-model百年规定的字符第一个字母转为大写

<!-- Parent.vue -->
<Child v-model.capitalize="myText" />

子组件中,通过对defineModel解构,可以访问到添加的修饰符

<script setup>
  const [model, modifiers] = defineModel()

  console.log(modifiers) // { capitalize: true }
</script>

<template>
  <input type="text" v-model="model" />
</template>

为了能够基于修饰符选择性的调节值的读取和写入方式,可以给defineModel传入get和set两个选项.

<script setup>
  const [model, modifiers] = defineModel({
    set(value) {
      if (modifiers.capitalize) {
        return value.charAt(0).toUpperCase() + value.slice(1)
      }
      return value
    },
  })
</script>

<template>
  <input type="text" v-model="model" />
</template>

3.4 之前自定义修饰符的方法

<script setup>
  const props = defineProps({
    modelValue: String,
    modelModifiers: { default: () => ({}) },
  })

  const emit = defineEmits(['update:modelValue'])

  function emitValue(e) {
    let value = e.target.value
    if (props.modelModifiers.capitalize) {
      value = value.charAt(0).toUpperCase() + value.slice(1)
    }
    emit('update:modelValue', value)
  }
</script>

<template>
  <input type="text" :value="props.modelValue" @input="emitValue" />
</template>

带参数的修饰符

<UserName v-model:first-name.capitalize="first" v-model:last-name.uppercase="last" />

<script setup>
  const [firstName, firstNameModifiers] = defineModel('firstName')
  const [lastName, lastNameModifiers] = defineModel('lastName')

  console.log(firstNameModifiers) // { capitalize: true }
  console.log(lastNameModifiers) // { uppercase: true }
</script>

3.4 之前的写法

<script setup>
  const props = defineProps({
    firstName: String,
    lastName: String,
    firstNameModifiers: { default: () => ({}) },
    lastNameModifiers: { default: () => ({}) },
  })
  defineEmits(['update:firstName', 'update:lastName'])

  console.log(props.firstNameModifiers) // { capitalize: true }
  console.log(props.lastNameModifiers) // { uppercase: true }
</script>