Vue 3 defineModel 怎样让自定义组件双向绑定类型稳定

Vue 3.4+ 中，defineModel() 是自定义组件实现 v-model 的推荐入口。要让双向绑定的类型稳定，关键不是给事件再写一遍类型，而是让模型 ref、对应 prop、更新事件和父组件状态从同一个类型契约产生。最小写法是 const model = defineModel()，然后在模板中直接把它绑定到原生输入框。

官方地址：https://vuejs.org/guide/components/v-model.html

下面只讨论模型 prop、更新事件和类型推导，不展开表单校验库或状态管理方案。示例假设 Vue 3.4+、TypeScript 和 vue-tsc 可用。

先用泛型 defineModel 建立最小闭环

defineModel() 返回一个可以读写的 ref。泛型 T 同时表达组件内部看到的模型值类型和向父组件更新时携带的值类型。父组件的 ref 也写成同样的类型，调用处就形成了一个可追踪的闭环。

编译层面可以把它理解为：子组件声明 modelValue prop，并在模型被修改时触发 update:modelValue；父组件的 v-model 再把这两者接回自己的 ref。理解这个展开结果，排查类型错位会比把 defineModel 当成黑盒更容易。

把命名模型映射到具体 prop 和事件

不写名字时，模型默认叫 modelValue，父组件使用普通的 v-model。如果组件同时管理标题、数量等多个值，应把模型名显式写出来，让 prop 和事件自然映射到 title 与 update:title。

调用方对应写成 。命名模型的价值在于接口语义清楚：组件不需要让调用方猜某个匿名值到底代表标题还是数量，也不需要手动维护一组容易拼错的事件字符串。

用 required 和 default 处理可选性

required: true 表示父级必须提供这个模型；它适合编辑器、选择器这类没有合理缺省值的组件。default 则在父级没有提供值时给子组件一个初始值，但它改变的是运行时默认行为，不应被误认为父级 ref 也会同步获得该值。

官方文档特别提醒：如果父组件的 ref 是 undefined，而子组件通过 default 得到一个非空值，初始阶段可能出现父子不同步。需要父子共享同一个初始状态时，更稳妥的做法是父组件先初始化 ref，再让子组件使用 required 接收它。

用 set 转换处理输入边界

有些组件接收的是输入框产生的字符串，但对外希望更新为数字或规范化后的文本。这时不要把 model 直接声明成一个含糊的联合类型后到处断言，而是用 set 集中描述写入模型前的转换规则。转换函数的返回值就是组件向外更新的实际值。

这里要区分两层：输入事件的原始值可能是字符串，set 负责把它变成组件契约中的数字；父组件的 v-model 应接收 Ref。如果业务需要保留非法输入、错误提示或空值状态，就应把这些状态显式建模，而不是在转换函数里静默吞掉所有异常。

用 vue-tsc 固化调用方契约

编辑器提示能发现一部分问题，但组件模板的 prop、事件和泛型推导最好交给 vue-tsc 做项目级检查。重点不是让检查器替你设计 API，而是把“父级传入类型”和“子级更新类型”之间的错位尽早暴露。

{
  "scripts": {
    "typecheck": "vue-tsc --noEmit"
  }
}

严格模式下，如果 defineModel() 的组件被绑定到 Ref，调用处应尽早出现类型错误。若组件确实需要支持两种输入，请先定义清楚对外模型是联合类型，还是通过 set 把输入归一化后只向外暴露一种类型，别让类型声明和实际事件值各说一套。

一组选择规则

最终可以用三句话检查组件接口：模型名是否和调用处一致；父级 ref 是否与组件真正发出的值一致；默认值和转换逻辑是否会制造一个调用方不知道的状态。只要这三点明确，defineModel 就能把双向绑定从“字符串约定”变成可维护的类型接口。

常见问题

defineModel 需要 Vue 3.4 吗？

官方 API 文档将它标记为 Vue 3.4+ 可用。更早版本可以用 defineProps 与 defineEmits 手动实现同样的 prop/event 契约。

命名模型会改变事件名吗？

会。defineModel('title') 对应 title prop 与 update:title 更新事件，父级应使用 v-model:title。

default 能替父组件初始化 ref 吗？

不能把它当成父级初始化。子组件的默认值可能先于父级值存在，若要求单一真实来源，应由父级初始化并使用 required 模型。