Vue.js

外观

本页内容

组件 v-model ​

基本用法 ​

v-model 可以用于组件上以实现双向绑定。

从 Vue 3.4 开始，推荐的做法是使用 defineModel() 宏

vue
<!-- 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 绑定一个值

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

defineModel() 返回的值是一个 ref。它可以像任何其他 ref 一样被访问和修改，不同之处在于它充当父值和局部值之间的双向绑定

  • 它的 .value 与父组件绑定的 v-model 值同步；
  • 当它被子组件修改时，也会更新父组件绑定的值。

这意味着您还可以使用 v-model 将此 ref 绑定到原生输入元素，使包装原生输入元素同时提供相同的 v-model 使用方式变得简单

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

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

在 playground 中尝试

内部原理 ​

defineModel 是一个便利宏。编译器将其扩展为以下内容

  • 一个名为 modelValue 的 prop，该 prop 的值与局部 ref 的值同步；
  • 一个名为 update:modelValue 的事件，当局部 ref 的值被修改时发出。

这是在 3.4 之前实现上述相同子组件的方式

vue
<!-- 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="foo" 将被编译为

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

如你所见，这要冗长得多。然而，了解底层发生的事情是有帮助的。

因为 defineModel 声明了一个 prop，所以你可以通过将其传递给 defineModel 来声明底层 prop 的选项

js
// making the v-model required
const model = defineModel({ required: true })

// providing a default value
const model = defineModel({ default: 0 })

警告

如果您为 defineModel prop 提供了默认值，并且父组件没有为该 prop 提供任何值，这可能会导致父组件和子组件之间的解同步。在下面的示例中，父组件的 myRef 是未定义的，但子组件的 model 是 1

js
// child component:
const model = defineModel({ default: 1 })

// parent component:
const myRef = ref()
html
<Child v-model="myRef"></Child>

首先，让我们回顾一下在原生元素上如何使用 v-model。

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

在底层，模板编译器将 v-model 扩展为更冗长的等效代码。所以上面的代码与以下代码相同

template
<input
  :value="searchText"
  @input="searchText = $event.target.value"
/>

在组件上使用时，v-model 将扩展为以下内容

template
<CustomInput
  :model-value="searchText"
  @update:model-value="newValue => searchText = newValue"
/>

不过，为了真正实现这个功能，<CustomInput> 组件必须做两件事

  1. 将原生 <input> 元素的 value 属性绑定到 modelValue prop
  2. 当原生 input 事件被触发时，发出一个带有新值的 update:modelValue 自定义事件

这就是它在实际中的应用

vue
<!-- CustomInput.vue -->
<script>
export default {
  props: ['modelValue'],
  emits: ['update:modelValue']
}
</script>

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

现在 v-model 应该可以与这个组件完美地工作

template
<CustomInput v-model="searchText" />

在 playground 中尝试

在组件内实现 v-model 的另一种方法是使用具有获取器和设置器的可写 computed 属性。获取器方法应返回 modelValue 属性，设置器方法应发出相应的事件

vue
<!-- CustomInput.vue -->
<script>
export default {
  props: ['modelValue'],
  emits: ['update:modelValue'],
  computed: {
    value: {
      get() {
        return this.modelValue
      },
      set(value) {
        this.$emit('update:modelValue', value)
      }
    }
  }
}
</script>

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

v-model 参数 ​

组件上的 v-model 也可以接受一个参数

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

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

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

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

在 playground 中尝试

如果还需要 prop 选项，它们应放在模型名称之后传递

js
const title = defineModel('title', { required: true })
3.4 之前的使用方法
vue
<!-- MyComponent.vue -->
<script setup>
defineProps({
  title: {
    required: true
  }
})
defineEmits(['update:title'])
</script>

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

在 playground 中尝试

在这种情况下，子组件应期望一个 title prop 并发出一个 update:title 事件来更新父值，而不是默认的 modelValue prop 和 update:modelValue 事件

vue
<!-- MyComponent.vue -->
<script>
export default {
  props: ['title'],
  emits: ['update:title']
}
</script>

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

在 playground 中尝试

多个 v-model 绑定 ​

通过利用之前学习过的针对特定属性和事件进行定位的能力，例如使用 v-model 参数，我们现在可以在单个组件实例上创建多个 v-model 绑定。

每个 v-model 都将同步到不同的属性，无需在组件中添加额外选项。

template
<UserName
  v-model:first-name="first"
  v-model:last-name="last"
/>
vue
<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>

在 playground 中尝试

3.4 之前的使用方法
vue
<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>

在 playground 中尝试

vue
<script>
export default {
  props: {
    firstName: String,
    lastName: String
  },
  emits: ['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>

在 playground 中尝试

处理 v-model 修饰符

在我们学习关于表单输入绑定时，我们看到了 v-model 有内置的修饰符 - .trim、.number 和 .lazy。在某些情况下，你可能还希望你的自定义输入组件的 v-model 支持自定义修饰符。

让我们创建一个示例自定义修饰符，名为 capitalize，它可以首字母大写由 v-model 绑定提供的字符串。

template
<MyComponent v-model.capitalize="myText" />

添加到组件 v-model 的修饰符可以通过解构 defineModel() 返回值来访问，如下所示

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

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

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

为了根据修饰符有条件地调整读取/写入值的方式，我们可以将 get 和 set 选项传递给 defineModel()。这两个选项接收模型引用的 get / set 时的值，并应返回一个转换后的值。这就是我们如何使用 set 选项来实现 capitalize 修饰符的示例。

vue
<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>

在 playground 中尝试

3.4 之前的使用方法
vue
<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>

在 playground 中尝试

添加到组件 v-model 的修饰符将通过 modelModifiers 属性提供给组件。在下面的示例中，我们创建了一个包含默认为空对象的 modelModifiers 属性的组件。

vue
<script>
export default {
  props: {
    modelValue: String,
    modelModifiers: {
      default: () => ({})
    }
  },
  emits: ['update:modelValue'],
  created() {
    console.log(this.modelModifiers) // { capitalize: true }
  }
}
</script>

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

注意组件的 modelModifiers 属性包含 capitalize，其值为 true - 由于它在 v-model 绑定 v-model.capitalize="myText" 上被设置。

现在我们已经设置了属性，我们可以检查 modelModifiers 对象的键，并编写一个处理程序来更改发出的值。在下面的代码中，我们将首字母大写字符串，每当 <input /> 元素触发 input 事件时。

vue
<script>
export default {
  props: {
    modelValue: String,
    modelModifiers: {
      default: () => ({})
    }
  },
  emits: ['update:modelValue'],
  methods: {
    emitValue(e) {
      let value = e.target.value
      if (this.modelModifiers.capitalize) {
        value = value.charAt(0).toUpperCase() + value.slice(1)
      }
      this.$emit('update:modelValue', value)
    }
  }
}
</script>

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

在 playground 中尝试

v-model 具有参数的修饰符

对于同时具有参数和修饰符的 v-model 绑定，生成的属性名将是 arg + "Modifiers"。例如

template
<MyComponent v-model:title.capitalize="myText">

相应的声明应该是

js
export default {
  props: ['title', 'titleModifiers'],
  emits: ['update:title'],
  created() {
    console.log(this.titleModifiers) // { capitalize: true }
  }
}

下面是使用多个 v-model 和不同参数修饰符的另一个示例

template
<UserName
  v-model:first-name.capitalize="first"
  v-model:last-name.uppercase="last"
/>
vue
<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 之前的使用方法
vue
<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>
vue
<script>
export default {
  props: {
    firstName: String,
    lastName: String,
    firstNameModifiers: {
      default: () => ({})
    },
    lastNameModifiers: {
      default: () => ({})
    }
  },
  emits: ['update:firstName', 'update:lastName'],
  created() {
    console.log(this.firstNameModifiers) // { capitalize: true }
    console.log(this.lastNameModifiers) // { uppercase: true }
  }
}
</script>

在 GitHub 上编辑此页面