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"
/>
UserName.vue
// 选项式 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
}
})
