Vue 编译核心：transformModel 深度解析一、概念与背景 transformModel 是 Vue 编译器

一、概念与背景

transformModel 是 Vue 编译器中用于处理 v-model 指令的核心转换逻辑。
它的主要职责是将模板中的指令语法（如 <input v-model="foo" />）转换为底层运行时代码（如 { modelValue: foo, "onUpdate:modelValue": $event => (foo = $event) }），以实现数据的双向绑定。

在 Vue 3 的编译体系中，这个过程发生在 指令编译阶段（Directive Transform） ，即编译器在将模板抽象语法树（AST）转为渲染函数代码的中间阶段。

二、原理分解

transformModel 的总体逻辑分为五个步骤：

校验与准备阶段
- 检查 v-model 是否包含合法表达式；
- 判断表达式类型（是否为 ref、props、setup 变量等）；
- 确定指令参数（modelValue / onUpdate:modelValue）。
绑定类型判定（BindingTypes）
通过 context.bindingMetadata 获取当前绑定的上下文类型，可能的类型包括：
- SETUP_REF：已知是 ref；
- SETUP_LET：let 声明；
- SETUP_MAYBE_REF：可能是 ref；
- PROPS / PROPS_ALIASED：组件传入的 props；
- 其他普通变量。
若绑定类型为 props，编译器会直接抛出错误：
```
X_V_MODEL_ON_PROPS
```
生成赋值表达式（Assignment Expression）
核心逻辑：根据绑定类型构造 $event => (xxx = $event) 或 $event => ((xxx).value = $event) 的表达式。

生成属性与事件（Props）
构造两组属性：

modelValue: foo,
"onUpdate:modelValue": $event => (foo = $event)

并在组件中处理修饰符：

modelModifiers: { trim: true, number: true }

缓存与优化
如果 v-model 的回调函数没有依赖作用域变量，则编译器会调用：
```
context.cache(props[1].value)
```
以生成缓存版本，提高运行时性能。

三、代码与逐行讲解

核心函数签名

export const transformModel: DirectiveTransform = (dir, node, context) => { ... }

dir：当前指令的 AST 节点（如 v-model="foo"）。
node：所在元素节点（如 <input>）。
context：当前编译上下文，包含作用域、绑定信息、报错回调等。

(1) 表达式校验

if (!exp) {
  context.onError(createCompilerError(ErrorCodes.X_V_MODEL_NO_EXPRESSION, dir.loc))
  return createTransformProps()
}

解释：
如果指令未绑定表达式（如仅写 v-model），则抛出错误并返回空属性。

(2) 判断绑定类型

const bindingType = context.bindingMetadata[rawExp]

解释：
查表判断 v-model 绑定的变量属于哪一类。
此信息由 <script setup> 分析阶段注入。

(3) 处理 setup ref 的特殊情况

if (maybeRef) {
  assignmentExp = createCompoundExpression([
    `${eventArg} => ((`,
    createSimpleExpression(rawExp, false, exp.loc),
    `).value = $event)`
  ])
}

解释：
如果变量是一个 ref，则更新其 .value；
否则直接赋值（普通变量）。

(4) 构造最终 Props

const props = [
  createObjectProperty(propName, dir.exp!),
  createObjectProperty(eventName, assignmentExp)
]

结果形如：

{
  modelValue: foo,
  "onUpdate:modelValue": $event => (foo = $event)
}

(5) 处理修饰符（Modifiers）

if (dir.modifiers.length && node.tagType === ElementTypes.COMPONENT) {
  const modifiersKey = arg ? `${arg.content}Modifiers` : `modelModifiers`
  props.push(createObjectProperty(modifiersKey, ...))
}

解释：
为组件型节点添加 xxxModifiers 属性，用于实现修饰符功能（例如 .trim、.number）。

四、机制对比

功能点	Vue 2.x	Vue 3.x
双向绑定机制	通过 `value` + `input` 事件	通过 `modelValue` + `onUpdate:modelValue`
运行时处理	由模板编译器自动注入	通过 `transformModel` 生成对象结构
修饰符传递	内置语法糖处理	通过额外的 `modelModifiers` 属性传递

五、实践：自定义组件的 `v-model`

示例：

<MyInput v-model="userName" />

编译后等价于：

h(MyInput, {
  modelValue: userName,
  "onUpdate:modelValue": $event => (userName = $event)
})

若含修饰符：

<MyInput v-model.trim="inputValue" />

则对应：

{
  modelValue: inputValue,
  "onUpdate:modelValue": $event => (inputValue = $event),
  modelModifiers: { trim: true }
}

六、拓展与深入

多 v-model 支持
Vue 3 允许在一个组件中声明多个 v-model，通过自定义参数区分：
```
<MyComponent v-model:title="pageTitle" v-model:content="pageContent" />
```
与 ref 的兼容
当绑定的是一个 ref，transformModel 自动添加 .value 访问。
性能优化点
- 使用缓存机制避免重复生成函数；
- 编译期错误定位到源模板位置（dir.loc）；
- 对 props 绑定直接报错防止不可变赋值。

七、潜在问题与注意事项

问题场景	说明
`v-model` 绑定到 `props`	会触发编译错误，防止修改父级数据
`v-model` 表达式不合法	会报 `X_V_MODEL_MALFORMED_EXPRESSION`
绑定到局部变量	若为作用域变量（`v-for` 等），编译器会阻止修改
修饰符非组件场景	不会生效，仅组件级 `v-model` 支持修饰符

八、总结

transformModel 是 Vue 编译器桥接模板与响应式数据的关键逻辑之一，它将模板层的指令语法转换为 JavaScript 层可执行的赋值逻辑，并对各种场景（ref、setup、props）进行了精细化适配。
它不仅展示了 Vue 编译体系的灵活性，也体现了响应式机制与编译优化的高度整合。

本文部分内容借助 AI 辅助生成，并由作者整理审核。

Vue 编译核心：transformModel 深度解析