v-model 的功能：实现数据的双向绑定
在原生元素上使用 v-model
<input v-model="searchText" />
- 修改输入框中的内容会触发变量 searchText 同步修改
- 修改 searchText 的值，也会触发输入框中内容同步修改
<!-- 选项式 API --> <template> <input v-model="searchText" /> <p>searchText的值为:{{ searchText }}</p> <button @click="changeSearchText">将 searchText 修改为 “日出”</button> </template> <script> export default { data() { return { searchText: "搜索的关键字", }; }, methods: { changeSearchText() { this.searchText = "日出"; }, }, }; </script>
<!-- 组合式 API vue3.4+ --> <script setup> let searchText = defineModel({ default: "搜索的关键字" }); let changeSearchText = () => { searchText.value = "日出"; }; </script> <template> <input v-model="searchText" /> <p>searchText的值为:{{ searchText }}</p> <button @click="changeSearchText">将 searchText 修改为 “日出”</button> </template>
在子组件上使用 v-model
<CustomInput v-model="searchText" />
相当于以下方式的简写
<CustomInput :modelValue="searchText" @update:modelValue="searchText= $event" />
- 给子组件传入了名为
modelValue的 prop - 父组件监听了子组件的自定义事件
update:modelValue
子组件使用 value 和 input 事件实现 v-model
CustomInput.vue
<!-- 选项式 API --> <script> export default { props: ['modelValue'], emits: ['update:modelValue'] } </script> <template> <input :value="modelValue" @input="$emit('update:modelValue', $event.target.value)" /> </template>
子组件使用 computed 实现 v-model
CustomInput.vue
<!-- 选项式 API --> <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>
【推荐】子组件使用 defineModel() 宏实现 v-model
CustomInput.vue
<!-- 组合式 API vue3.4+ --> <script setup> const model = defineModel() </script> <template> <input v-model="model"> </template>
defineModel() 返回的值是一个 ref
- 它的 .value 和父组件的 v-model 的值同步
- 当它被子组件变更时，会触发父组件绑定的值一起更新
给 v-model 添加参数
可以自定义传给子组件的 prop名称和监听的自定义事件名，用法如下：
<MyComponent v-model:title="bookTitle" />
- 给子组件传入了名为
title的 prop - 父组件监听了子组件的自定义事件
update:title
即 v-model 这种无参数的写法，其实是 v-model:modelValue 的简写。
或者可以理解为 modelValue 是 v-model 的默认参数。
子组件的具体实现方法如下：
MyComponent.vue
<!-- 选项式 API --> <script> export default { props: ['title'], emits: ['update:title'] } </script> <template> <input type="text" :value="title" @input="$emit('update:title', $event.target.value)" /> </template>
<!-- 组合式 API vue3.4+ --> <script setup> const title = defineModel('title') </script> <template> <input type="text" v-model="title" /> </template>
v-model 的参数，需作为 defineModel() 的第一个参数，以字符串的类型传入。
绑定多个 v-model
vue2 中，每个标签/组件只能绑定一个 v-model
但 vue3 中，因 v-model 可以添加参数，支持绑定多个 v-model
<UserName v-model:first-name="first" v-model:last-name="last" />
UserName.vue
<!-- 选项式 API --> <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>
<!-- 组合式 API vue3.4+ --> <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>
v-model 的内置修饰符
.lazy
延迟触发数据的更新
- v-model 默认会在每次 input 事件后更新数据 (IME 拼字阶段的状态例外)
- .lazy 会将数据更新延迟到每次 change 事件后
<!-- 在 "change" 事件后同步更新而不是 "input" 事件--> <input v-model.lazy="msg" />
.number
将用户输入自动转换为数字
<input v-model.number="age" />
- 如果值无法被 parseFloat() 处理，那么将返回原始值
- 输入框有 type=“number” 时会自动启用 .number 修饰符
.trim
自动去除用户输入内容中两端的空格
<input v-model.trim="msg" />
自定义 v-model 的修饰符
v-model 无参数时
以.capitalize 为例：自动将第一个字母转为大写
<MyComponent v-model.capitalize="myText" />
具体实现详见注释
MyComponent.vue
<!-- 选项式 API --> <script> export default { props: { modelValue: String, // 新增了名 modelModifiers 的 prop，用于获取自定义的修饰符 modelModifiers: { default: () => ({}) } }, emits: ['update:modelValue'], methods: { emitValue(e) { // 获取到原始值 let value = e.target.value // 判断 modelModifiers 中是否存在自定义的 capitalize 修饰符 if (this.modelModifiers.capitalize) { // 当存在自定义的 capitalize 修饰符时，将第一个字母转为大写 value = value.charAt(0).toUpperCase() + value.slice(1) } // 触发自定义事件，将按修饰符定义处理过的值，传给父组件 this.$emit('update:modelValue', value) } } } </script> <template> <input type="text" :value="modelValue" @input="emitValue" /> </template>
<!-- 组合式 API vue3.4+ --> <script setup> const [model, modifiers] = defineModel({ // 在set选项中，添加自定义修饰符的处理逻辑 set(value) { // 判断 modifiers 中是否存在自定义的 capitalize 修饰符 if (modifiers.capitalize) { // 当存在自定义的 capitalize 修饰符时，将第一个字母转为大写 return value.charAt(0).toUpperCase() + value.slice(1) } // 返回按修饰符定义处理过的值 return value } }) </script> <template> <input type="text" v-model="model" /> </template>
v-model 有参数时
传递修饰符的 prop 名将变为 参数名 + "Modifiers"，详见下例：
<MyComponent v-model:title.capitalize="myText">
MyComponent.vue
<!-- 选项式 API --> props: ['title', 'titleModifiers'], emits: ['update:title'],
<!-- 组合式 API vue3.4+ --> <script setup> const [title, titleModifiers] = defineModel({ // 在set选项中，添加自定义修饰符的处理逻辑 set(value) { // 判断 modifiers 中是否存在自定义的 capitalize 修饰符 if (titleModifiers.capitalize) { // 当存在自定义的 capitalize 修饰符时，将第一个字母转为大写 return value.charAt(0).toUpperCase() + value.slice(1) } // 返回按修饰符定义处理过的值 return value } }) </script> <template> <input type="text" v-model="title" /> </template>
绑定多个带参数且自定义不同修饰符的 v-model 时
<UserName v-model:first-name.capitalize="first" v-model:last-name.uppercase="last" />
// 选项式 API props: { firstName: String, lastName: String, firstNameModifiers: { default: () => ({}) }, lastNameModifiers: { default: () => ({}) } }, emits: ['update:firstName', 'update:lastName'],
// 组合式 API vue3.4+ const [firstName, firstNameModifiers] = defineModel({ // 在set选项中，添加自定义修饰符的处理逻辑 set(value) { if (firstNameModifiers.capitalize) { // 当存在自定义的 capitalize 修饰符时，将第一个字母转为大写 return value.charAt(0).toUpperCase() + value.slice(1) } // 返回按修饰符定义处理过的值 return value } }) const [lastName, lastNameModifiers] = defineModel({ // 在set选项中，添加自定义修饰符的处理逻辑 set(value) { if (lastNameModifiers.uppercase) { // 当存在自定义的 uppercase 修饰符时，所有字母大写 return value.toUpperCase() } // 返回按修饰符定义处理过的值 return value } })
