概览
就变化内容而言,此部分属于高阶内容:
- 非兼容:用于自定义组件时,
v-model的
prop 和事件默认名称已更改:- prop:
value
->modelValue
; - event:
input
->update:modelValue
;
- prop:
- 非兼容:
v-bind
的.sync
修饰符和组件的model
选项已移除,可用v-model
作为代替; - 新增:现在可以在同一个组件上使用多个
v-model
进行双向绑定; - 新增:现在可以自定义
v-model
修饰符。
在 Vue 2.2 中,我们引入了 model
组件选项,允许组件自定义用于 v-model
的 prop 和事件。但是,这仍然只允许在组件上使用一个 model
。
在 Vue 3 中,双向数据绑定的 API 已经标准化,减少了开发者在使用 v-model
指令时的混淆并且在使用 v-model
指令时可以更加灵活。
2.x 语法
在 2.x 中,在组件上使用 v-model
相当于绑定 value
prop 和 input
事件:
<ChildComponent v-model="pageTitle" /><!-- 是以下的简写: --><ChildComponent :value="pageTitle" @input="pageTitle = $event" />
如果要将属性或事件名称更改为其他名称,则需要在 ChildComponent
组件中添加 model
选项:
<!-- ParentComponent.vue --><ChildComponent v-model="pageTitle" />
// ChildComponent.vueexport default {model: {prop: 'title',event: 'change'},props: {// 这将允许 `value` 属性用于其他用途value: String,// 使用 `title` 代替 `value` 作为 model 的 proptitle: {type: String,default: 'Default title'}}
}
所以,在这个例子中 v-model
是以下的简写:
<ChildComponent :title="pageTitle" @change="pageTitle = $event" />
使用 v-bind.sync
在某些情况下,我们可能需要对某一个 prop 进行“双向绑定”(除了前面用 v-model
绑定 prop 的情况)。为此,我们建议使用 update:myPropName
抛出事件。例如,对于在上一个示例中带有 title
prop 的 ChildComponent
,我们可以通过下面的方式将分配新 value 的意图传达给父级:
this.$emit('update:title', newValue)
如果需要的话,父级可以监听该事件并更新本地 data property。例如:
<ChildComponent :title="pageTitle" @update:title="pageTitle = $event" />
为了方便起见,我们可以使用 .sync
修饰符来缩写,如下所示:
<ChildComponent :title.sync="pageTitle" />
3.x 语法
在 3.x 中,自定义组件上的 v-model
相当于传递了 modelValue
prop 并接收抛出的 update:modelValue
事件:
<ChildComponent v-model="pageTitle" /><!-- 是以下的简写: --><ChildComponent:modelValue="pageTitle"@update:modelValue="pageTitle = $event"
/>
v-model
参数
若需要更改 model
名称,作为组件内 model
选项的替代,现在我们可以将一个 argument 传递给 v-model
:
<ChildComponent v-model:title="pageTitle" /><!-- 是以下的简写: --><ChildComponent :title="pageTitle" @update:title="pageTitle = $event" />
这也可以作为 .sync
修饰符的替代,而且允许我们在自定义组件上使用多个 v-model
。
<ChildComponent v-model:title="pageTitle" v-model:content="pageContent" /><!-- 是以下的简写: --><ChildComponent:title="pageTitle"@update:title="pageTitle = $event":content="pageContent"@update:content="pageContent = $event"
/>
v-model
修饰符
除了像 .trim
这样的 2.x 硬编码的 v-model
修饰符外,现在 3.x 还支持自定义修饰符:
<div id="app"><my-component v-model.capitalize="myText"></my-component>{{ myText }}
</div>
让我们创建一个示例自定义修饰符 capitalize
,它将 v-model
绑定提供的字符串的第一个字母大写。
app.component('my-component', {props: {modelValue: String,modelModifiers: {default: () => ({})}},emits: ['update:modelValue'],template: `<input type="text":value="modelValue"@input="$emit('update:modelValue', $event.target.value)">`,created() {console.log(this.modelModifiers) // { capitalize: true }}
})
添加到组件 v-model
的修饰符将通过 modelModifiers
prop 提供给组件。在下面的示例中,我们创建了一个组件,其中包含默认为空对象的 modelModifiers
prop。
请注意,当组件的 created
生命周期钩子触发时,modelModifiers
prop 会包含 capitalize
,且其值为 true
——因为 capitalize
被设置在了写为 v-model.capitalize="myText"
的 v-model
绑定上。
现在我们已经设置了 prop,我们可以检查 modelModifiers
对象键并编写一个处理器来更改发出的值。在下面的代码中,每当 <input/>
元素触发 input
事件时,我们都将字符串大写。
<div id="app"><my-component v-model.capitalize="myText"></my-component>{{ myText }}
</div>
const app = Vue.createApp({data() {return {myText: ''}}
})app.component('my-component', {props: {modelValue: String,modelModifiers: {default: () => ({})}},emits: ['update:modelValue'],methods: {emitValue(e) {let value = e.target.valueif (this.modelModifiers.capitalize) {value = value.charAt(0).toUpperCase() + value.slice(1)}this.$emit('update:modelValue', value)}},template: `<inputtype="text":value="modelValue"@input="emitValue">`
})app.mount('#app')
对于带参数的 v-model
绑定,生成的 prop 名称将为 arg + "Modifiers"
:
<my-component v-model:description.capitalize="myText"></my-component>
app.component('my-component', {props: ['description', 'descriptionModifiers'],emits: ['update:description'],template: `<input type="text":value="description"@input="$emit('update:description', $event.target.value)">`,created() {console.log(this.descriptionModifiers) // { capitalize: true }}
})
迁移策略
我们推荐:
-
检查你的代码库中所有使用
.sync
的部分并将其替换为v-model
:
<ChildComponent :title.sync="pageTitle" /><!-- 替换为 --><ChildComponent v-model:title="pageTitle" />
-
对于所有不带参数的
v-model
,请确保分别将 prop 和 event 命名更改为modelValue
和update:modelValue
<ChildComponent v-model="pageTitle" />
// ChildComponent.vueexport default {props: {modelValue: String // 以前是`value:String`},emits: ['update:modelValue'],methods: {changePageTitle(title) {// 以前是 `this.$emit('input', title)`this.$emit('update:modelValue', title) }}
}