Vue / 系统课时
v-model 组件契约
v-model 组件契约
业务组件里的 v-model 不只是语法糖,而是一份父子组件之间的读写契约。本节用 Vue 3 + TypeScript 实现默认模型、多个命名模型和自定义修饰符,并明确哪些数据应该双向绑定、哪些应该继续使用普通 Props 与事件。
学习目标
- 理解
v-model对应的 Prop 与update:*事件契约 - 使用
defineModel实现默认模型和多个命名模型 - 为组件模型设计修饰符,并避免失控的双向状态
看清 v-model 的真实契约
父组件写下 v-model="name" 时,组件真正承担的是两件事:接收当前值,并在用户修改后通知父组件更新。默认模型对应 modelValue 与 update:modelValue;命名模型 v-model:role 则对应 role 与 update:role。
defineModel 把这组 Prop 与事件声明压缩成一个可读写的 Ref。子组件读取它得到父组件传入的值,修改它时 Vue 会向父组件发出对应的 update:* 事件,最终仍由父组件拥有状态。

实现默认模型与命名模型
下面的组件同时维护姓名和角色。姓名使用默认 v-model,角色使用命名模型 v-model:role。这是片段示例,依赖一个已启用 Vue 3、TypeScript 和 <script setup> 的项目。
<!-- ProfileEditor.vue -->
<script setup lang="ts">
const name = defineModel<string>({ required: true })
const role = defineModel<string>('role', { required: true })
</script>
<template>
<label>
姓名
<input v-model="name" />
</label>
<label>
角色
<select v-model="role">
<option value="developer">Developer</option>
<option value="reviewer">Reviewer</option>
</select>
</label>
</template>预期结果:组件分别把输入框和下拉框的修改写回默认模型与 role 模型;它本身不创建第二份业务状态。
默认模型:modelValue <-> update:modelValue
命名模型:role <-> update:role父组件可以把两个状态分别绑定到同一个子组件。这个示例同样是项目内片段,ProfileEditor.vue 需要与父组件处于可导入位置。
<script setup lang="ts">
import { ref } from 'vue'
import ProfileEditor from './ProfileEditor.vue'
const name = ref('Alice')
const role = ref('developer')
</script>
<template>
<ProfileEditor v-model="name" v-model:role="role" />
<p>{{ name }} / {{ role }}</p>
</template>预期结果:初始页面显示 Alice / developer;修改姓名或角色后,下方文本立即反映父组件中的最新状态。
Alice / developer多值绑定适合多个字段都具有独立、明确的双向语义。不要为了减少事件数量,把整个复杂对象都塞进一个 v-model 后在子组件内随意修改,否则字段来源、校验责任和更新粒度都会变得模糊。
用修饰符约束写回值
组件修饰符适合处理与输入契约直接相关的轻量转换,例如去除首尾空格或统一首字母格式。defineModel 可以同时取得模型 Ref 和修饰符集合,并通过 set 在写回父组件前转换值。
<!-- NormalizedNameInput.vue -->
<script setup lang="ts">
const [name, modifiers] = defineModel<string, 'trim' | 'capitalize'>({
required: true,
set(value) {
let next = value
if (modifiers.trim) {
next = next.trim()
}
if (modifiers.capitalize && next.length > 0) {
next = next[0].toUpperCase() + next.slice(1)
}
return next
}
})
</script>
<template>
<input v-model="name" />
</template>预期结果:父组件使用 v-model.trim.capitalize="name" 后,用户输入首尾带空格的 alice,写回父状态时得到 Alice。
输入: alice
父组件状态:Alice修饰符应该保持确定、同步且容易解释。如果转换需要远程请求、复杂校验或可能失败的业务流程,更适合显式触发事件或调用方法,而不是把副作用隐藏在模型 setter 中。
划清双向绑定的边界
适合 v-model 的数据通常具有“父组件拥有、子组件可编辑、修改后立即回传”三个特征,例如输入值、开关状态、分页页码或受控弹窗的显示状态。只读配置、权限、请求状态等信息通常继续使用普通 Props。
一个组件拥有多个模型时,应让每个名字表达独立业务含义,例如 v-model:startDate 与 v-model:endDate,而不是 v-model:value1、v-model:value2。类型也应直接反映契约,避免为了兼容所有调用方而退化成 any。
把 v-model 当成组件 API 设计后,判断标准就很简单:默认模型表达组件最核心的可编辑值,命名模型拆分真正独立的双向状态,修饰符只承担轻量且可预测的写回转换。