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,角色使用命名模型 v-model:role。这是片段示例,依赖一个已启用 Vue 3、TypeScript 和 <script setup> 的项目。

vue
<!-- 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 模型;它本身不创建第二份业务状态。

text
默认模型:modelValue <-> update:modelValue
命名模型:role <-> update:role

父组件可以把两个状态分别绑定到同一个子组件。这个示例同样是项目内片段,ProfileEditor.vue 需要与父组件处于可导入位置。

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;修改姓名或角色后,下方文本立即反映父组件中的最新状态。

text
Alice / developer

多值绑定适合多个字段都具有独立、明确的双向语义。不要为了减少事件数量,把整个复杂对象都塞进一个 v-model 后在子组件内随意修改,否则字段来源、校验责任和更新粒度都会变得模糊。

用修饰符约束写回值

组件修饰符适合处理与输入契约直接相关的轻量转换,例如去除首尾空格或统一首字母格式。defineModel 可以同时取得模型 Ref 和修饰符集合,并通过 set 在写回父组件前转换值。

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

text
输入:  alice  
父组件状态:Alice

修饰符应该保持确定、同步且容易解释。如果转换需要远程请求、复杂校验或可能失败的业务流程,更适合显式触发事件或调用方法,而不是把副作用隐藏在模型 setter 中。

划清双向绑定的边界

适合 v-model 的数据通常具有“父组件拥有、子组件可编辑、修改后立即回传”三个特征,例如输入值、开关状态、分页页码或受控弹窗的显示状态。只读配置、权限、请求状态等信息通常继续使用普通 Props。

一个组件拥有多个模型时,应让每个名字表达独立业务含义,例如 v-model:startDate 与 v-model:endDate,而不是 v-model:value1、v-model:value2。类型也应直接反映契约,避免为了兼容所有调用方而退化成 any。

把 v-model 当成组件 API 设计后,判断标准就很简单:默认模型表达组件最核心的可编辑值,命名模型拆分真正独立的双向状态,修饰符只承担轻量且可预测的写回转换。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

v-model 组件契约

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通