在 Vue 3 项目里，很多人在封装表单组件时都会用 `v-model` 来传递值，但自定义组件上的 `v-model` 和原生表单元素上的行为并不完全一样。特别是从 Vue 2 迁移过来，或者在组合式 API 里混用 `defineModel` 和手动 `emit` 时，经常会遇到“父组件值改了子组件没更新”“子组件输入父组件不同步”“多个 v-model 绑定时命名混乱”等问题。这些问题通常源于对 `v-model` 编译结果、`modelValue` 命名规则以及 `update:` 事件触发机制理解不透彻。下面从实际代码出发，梳理自定义组件上 `v-model` 的正确写法，以及一些容易踩坑的细节。

## 先看最基础的用法

Vue 3 里，父组件写 `<MyInput v-model="name" />`，编译后等价于：

```html
<MyInput :model-value="name" @update:model-value="name = $event" />
```

子组件需要声明 `modelValue` prop，并在需要更新时触发 `update:modelValue` 事件。

```vue

<script setup>
const props = defineProps({
 modelValue: String
})

const emit = defineEmits(['update:modelValue'])

function onInput(e) {
 emit('update:modelValue', e.target.value)
}
</script>

<template>
 <input :value="modelValue" @input="onInput" />
</template>
```

这样父子同步没问题。但实际开发中，子组件内部往往还要做一层本地状态，比如输入防抖、格式化，这时候直接绑 `modelValue` 就会出问题。

## 本地状态和 v-model 的冲突

假设一个金额输入框，子组件要限制只能输入数字，并且去掉逗号。如果直接：

```vue
<input :value="modelValue" @input="emit('update:modelValue', e.target.value)" />
```

父组件传进来的值会立刻被覆盖，但用户输入中间态（比如只输入了 `-` 或 `1.`）也会被同步到父组件，导致父组件校验直接失败。更合理的做法是维护一个内部 `innerValue`，只在输入合法或失焦时再 emit。

```vue
<script setup>
import { ref, watch } from 'vue'

const props = defineProps({
 modelValue: [String, Number]
})
const emit = defineEmits(['update:modelValue'])

const innerValue = ref(props.modelValue)

watch(() => props.modelValue, (val) => {
 if (val !== innerValue.value) {
 innerValue.value = val
 }
})

function handleInput(e) {
 innerValue.value = e.target.value
}

function handleBlur() {
 const num = Number(innerValue.value)
 if (!Number.isNaN(num)) {
 emit('update:modelValue', num)
 } else {
 innerValue.value = props.modelValue
 }
}
</script>

<template>
 <input
 :value="innerValue"
 @input="handleInput"
 @blur="handleBlur"
 />
</template>
```

这里 `watch` 里加了一层判断，避免父组件更新时把用户正在输入的内容冲掉。

## 多个 v-model 的命名参数

Vue 3 支持多个 `v-model`，比如一个用户信息组件同时绑定姓名和年龄：

```html
<UserForm v-model:name="name" v-model:age="age" />
```

子组件对应：

```vue
<script setup>
defineProps(['name', 'age'])
defineEmits(['update:name', 'update:age'])
</script>

<template>
 <input
 :value="name"
 @input="$emit('update:name', $event.target.value)"
 />
 <input
 :value="age"
 @input="$emit('update:age', $event.target.value)"
 />
</template>
```

这里容易写错的地方是事件名。`v-model:name` 对应的事件是 `update:name`，大小写必须一致。如果写成了 `update:Name`，父组件不会更新，而且 Vue 不会报错，只有 devtools 里能看到事件名不匹配。

## 使用 defineModel 简化代码

Vue 3.4 开始提供了 `defineModel` 宏，可以少写很多样板代码：

```vue
<script setup>
const modelValue = defineModel()
</script>

<template>
 <input v-model="modelValue" />
</template>
```

多个 v-model 也可以：

```vue
<script setup>
const name = defineModel('name')
const age = defineModel('age')
</script>
```

但 `defineModel` 默认要求父组件必须传对应的 prop，否则会警告。如果希望可选，可以传 `{ required: false }`。另外 `defineModel` 返回的是 ref，直接 `modelValue.value = xxx` 就会触发 emit，不需要手动写 `emit`。

## 一个容易忽略的循环更新问题

看下面这个场景：父组件用 `v-model` 绑定一个对象，子组件在 `watch` 里修改这个对象的属性，然后 emit 新对象。如果父组件在 `update:modelValue` 里又改了别的字段，可能触发子组件再次 watch，形成循环。比如：

```vue

<script setup>
const props = defineProps({ modelValue: Object })
const emit = defineEmits(['update:modelValue'])

watch(() => props.modelValue, (val) => {
 emit('update:modelValue', { ...val, touched: true })
}, { deep: true })
</script>
```

父组件每次收到 emit 后重新渲染，`modelValue` 引用变化，子组件 watch 再次触发，虽然加了 `deep` 但引用变了也会触发。解决方式是把逻辑放到具体事件里，而不是用 watch 监听整个对象。

## 最后提一下修饰符

`v-model` 支持 `.lazy`、`.number`、`.trim` 等修饰符，在自定义组件上默认不会自动生效，需要子组件自己处理 `modelModifiers` prop。比如：

```js
defineProps({
 modelValue: String,
 modelModifiers: { default: () => ({}) }
})

function onInput(e) {
 let val = e.target.value
 if (props.modelModifiers.trim) val = val.trim()
 emit('update:modelValue', val)
}
```

如果用的是多个 v-model，修饰符 prop 名会变成 `nameModifiers`、`ageModifiers`。这一点在写通用表单组件时经常被遗漏，导致父组件写了 `.trim` 但实际没生效。

自定义组件上的 `v-model` 本身不复杂，麻烦的是内部状态、事件命名和修饰符这些边界情况。把 `modelValue` 和 `update:modelValue` 的对应关系理清楚，再根据是否需要中间状态决定要不要加一层本地 ref，基本就能避开大部分同步问题。

 推荐查看天气：http://www.362tq.com/baota/zuotian.html
 推荐查看天气：http://www.362tq.com/baota/7tian.html
 推荐查看天气：http://www.362tq.com/baota/10tian.html
 推荐查看天气：http://www.362tq.com/baota/15tian.html
 推荐查看天气：http://www.362tq.com/baota/40tian.html
 推荐查看天气：http://www.362tq.com/yanchang/
 推荐查看天气：http://www.362tq.com/yanchang/zuotian.html
 推荐查看天气：http://www.362tq.com/yanchang/7tian.html
 推荐查看天气：http://www.362tq.com/yanchang/10tian.html
 推荐查看天气：http://www.362tq.com/yanchang/15tian.html
 推荐查看天气：http://www.362tq.com/yanchang/40tian.html
 推荐查看天气：http://www.362tq.com/yanchuan/
 推荐查看天气：http://www.362tq.com/yanchuan/zuotian.html
 推荐查看天气：http://www.362tq.com/yanchuan/7tian.html
 推荐查看天气：http://www.362tq.com/yanchuan/10tian.html
 推荐查看天气：http://www.362tq.com/yanchuan/15tian.html
 推荐查看天气：http://www.362tq.com/yanchuan/40tian.html
 推荐查看天气：http://www.362tq.com/zichang/
 推荐查看天气：http://www.362tq.com/zichang/zuotian.html
 推荐查看天气：http://www.362tq.com/zichang/7tian.html
 推荐查看天气：http://www.362tq.com/zichang/10tian.html
 推荐查看天气：http://www.362tq.com/zichang/15tian.html
 推荐查看天气：http://www.362tq.com/zichang/40tian.html
 推荐查看天气：http://www.362tq.com/ansai/
 推荐查看天气：http://www.362tq.com/ansai/zuotian.html
 推荐查看天气：http://www.362tq.com/ansai/7tian.html
 推荐查看天气：http://www.362tq.com/ansai/10tian.html
 推荐查看天气：http://www.362tq.com/ansai/15tian.html
 推荐查看天气：http://www.362tq.com/ansai/40tian.html
 推荐查看天气：http://www.362tq.com/zhidan/
 推荐查看天气：http://www.362tq.com/zhidan/zuotian.html
 推荐查看天气：http://www.362tq.com/zhidan/7tian.html
 推荐查看天气：http://www.362tq.com/zhidan/10tian.html
 推荐查看天气：http://www.362tq.com/zhidan/15tian.html
 推荐查看天气：http://www.362tq.com/zhidan/40tian.html
 推荐查看天气：http://www.362tq.com/wuqi/
 推荐查看天气：http://www.362tq.com/wuqi/zuotian.html
 推荐查看天气：http://www.362tq.com/wuqi/7tian.html
 推荐查看天气：http://www.362tq.com/wuqi/10tian.html
 推荐查看天气：http://www.362tq.com/wuqi/15tian.html
 推荐查看天气：http://www.362tq.com/wuqi/40tian.html
 推荐查看天气：http://www.362tq.com/ganquan/
 推荐查看天气：http://www.362tq.com/ganquan/zuotian.html
 推荐查看天气：http://www.362tq.com/ganquan/7tian.html
 推荐查看天气：http://www.362tq.com/ganquan/10tian.html
 推荐查看天气：http://www.362tq.com/ganquan/15tian.html
 推荐查看天气：http://www.362tq.com/ganquan/40tian.html
 推荐查看天气：http://www.362tq.com/fuxian/
 推荐查看天气：http://www.362tq.com/fuxian/zuotian.html
 推荐查看天气：http://www.362tq.com/fuxian/7tian.html
 推荐查看天气：http://www.362tq.com/fuxian/10tian.html
 推荐查看天气：http://www.362tq.com/fuxian/15tian.html
 推荐查看天气：http://www.362tq.com/fuxian/40tian.html
 推荐查看天气：http://www.362tq.com/luochuan/
 推荐查看天气：http://www.362tq.com/luochuan/zuotian.html
 推荐查看天气：http://www.362tq.com/luochuan/7tian.html
 推荐查看天气：http://www.362tq.com/luochuan/10tian.html
 推荐查看天气：http://www.362tq.com/luochuan/15tian.html
 推荐查看天气：http://www.362tq.com/luochuan/40tian.html
 推荐查看天气：http://www.362tq.com/yichuan/
 推荐查看天气：http://www.362tq.com/yichuan/zuotian.html
 推荐查看天气：http://www.362tq.com/yichuan/7tian.html
 推荐查看天气：http://www.362tq.com/yichuan/10tian.html
 推荐查看天气：http://www.362tq.com/yichuan/15tian.html
 推荐查看天气：http://www.362tq.com/yichuan/40tian.html
 推荐查看天气：http://www.362tq.com/huanglong/
 推荐查看天气：http://www.362tq.com/huanglong/zuotian.html
 推荐查看天气：http://www.362tq.com/huanglong/7tian.html
 推荐查看天气：http://www.362tq.com/huanglong/10tian.html
 推荐查看天气：http://www.362tq.com/huanglong/15tian.html
 推荐查看天气：http://www.362tq.com/huanglong/40tian.html
 推荐查看天气：http://www.362tq.com/huangling/
 推荐查看天气：http://www.362tq.com/huangling/zuotian.html
 推荐查看天气：http://www.362tq.com/huangling/7tian.html
 推荐查看天气：http://www.362tq.com/huangling/10tian.html
 推荐查看天气：http://www.362tq.com/huangling/15tian.html
 推荐查看天气：http://www.362tq.com/huangling/40tian.html
 推荐查看天气：http://www.362tq.com/hanzhong/
 推荐查看天气：http://www.362tq.com/hanzhong/zuotian.html
 推荐查看天气：http://www.362tq.com/hanzhong/7tian.html
 推荐查看天气：http://www.362tq.com/hanzhong/10tian.html
 推荐查看天气：http://www.362tq.com/hanzhong/15tian.html
 推荐查看天气：http://www.362tq.com/hanzhong/40tian.html
 推荐查看天气：http://www.362tq.com/hantai/
 推荐查看天气：http://www.362tq.com/hantai/zuotian.html
 推荐查看天气：http://www.362tq.com/hantai/7tian.html
 推荐查看天气：http://www.362tq.com/hantai/10tian.html
 推荐查看天气：http://www.362tq.com/hantai/15tian.html
 推荐查看天气：http://www.362tq.com/hantai/40tian.html
 推荐查看天气：http://www.362tq.com/nanzheng/
 推荐查看天气：http://www.362tq.com/nanzheng/zuotian.html
 推荐查看天气：http://www.362tq.com/nanzheng/7tian.html
 推荐查看天气：http://www.362tq.com/nanzheng/10tian.html
 推荐查看天气：http://www.362tq.com/nanzheng/15tian.html
 推荐查看天气：http://www.362tq.com/nanzheng/40tian.html
 推荐查看天气：http://www.362tq.com/chenggu/
 推荐查看天气：http://www.362tq.com/chenggu/zuotian.html
 推荐查看天气：http://www.362tq.com/chenggu/7tian.html
 推荐查看天气：http://www.362tq.com/chenggu/10tian.html
 推荐查看天气：http://www.362tq.com/chenggu/15tian.html
 推荐查看天气：http://www.362tq.com/chenggu/40tian.html
 推荐查看天气：http://www.362tq.com/yangxian/
 推荐查看天气：http://www.362tq.com/yangxian/zuotian.html
 推荐查看天气：http://www.362tq.com/yangxian/7tian.html
 推荐查看天气：http://www.362tq.com/yangxian/10tian.html
 推荐查看天气：http://www.362tq.com/yangxian/15tian.html
 推荐查看天气：http://www.362tq.com/yangxian/40tian.html
 推荐查看天气：http://www.362tq.com/xixiang/
 推荐查看天气：http://www.362tq.com/xixiang/zuotian.html
 推荐查看天气：http://www.362tq.com/xixiang/7tian.html
 推荐查看天气：http://www.362tq.com/xixiang/10tian.html
 推荐查看天气：http://www.362tq.com/xixiang/15tian.html
 推荐查看天气：http://www.362tq.com/xixiang/40tian.html
 推荐查看天气：http://www.362tq.com/mianxian/
 推荐查看天气：http://www.362tq.com/mianxian/zuotian.html
 推荐查看天气：http://www.362tq.com/mianxian/7tian.html
 推荐查看天气：http://www.362tq.com/mianxian/10tian.html
 推荐查看天气：http://www.362tq.com/mianxian/15tian.html
 推荐查看天气：http://www.362tq.com/mianxian/40tian.html
 推荐查看天气：http://www.362tq.com/ningqiang/
 推荐查看天气：http://www.362tq.com/ningqiang/zuotian.html
 推荐查看天气：http://www.362tq.com/ningqiang/7tian.html
 推荐查看天气：http://www.362tq.com/ningqiang/10tian.html
 推荐查看天气：http://www.362tq.com/ningqiang/15tian.html
 推荐查看天气：http://www.362tq.com/ningqiang/40tian.html
 推荐查看天气：http://www.362tq.com/lueyang/
 推荐查看天气：http://www.362tq.com/lueyang/zuotian.html
 推荐查看天气：http://www.362tq.com/lueyang/7tian.html
 推荐查看天气：http://www.362tq.com/lueyang/10tian.html
 推荐查看天气：http://www.362tq.com/lueyang/15tian.html
 推荐查看天气：http://www.362tq.com/lueyang/40tian.html
 推荐查看天气：http://www.362tq.com/zhenba/
 推荐查看天气：http://www.362tq.com/zhenba/zuotian.html
 推荐查看天气：http://www.362tq.com/zhenba/7tian.html
 推荐查看天气：http://www.362tq.com/zhenba/10tian.html
 推荐查看天气：http://www.362tq.com/zhenba/15tian.html
 推荐查看天气：http://www.362tq.com/zhenba/40tian.html
 推荐查看天气：http://www.362tq.com/liuba/
 推荐查看天气：http://www.362tq.com/liuba/zuotian.html
 推荐查看天气：http://www.362tq.com/liuba/7tian.html
 推荐查看天气：http://www.362tq.com/liuba/10tian.html
 推荐查看天气：http://www.362tq.com/liuba/15tian.html
 推荐查看天气：http://www.362tq.com/liuba/40tian.html
 推荐查看天气：http://www.362tq.com/fuping/
 推荐查看天气：http://www.362tq.com/fuping/zuotian.html
 推荐查看天气：http://www.362tq.com/fuping/7tian.html
 推荐查看天气：http://www.362tq.com/fuping/10tian.html
 推荐查看天气：http://www.362tq.com/fuping/15tian.html
 推荐查看天气：http://www.362tq.com/fuping/40tian.html
 推荐查看天气：http://www.362tq.com/yulinshi/
 推荐查看天气：http://www.362tq.com/yulinshi/zuotian.html
 推荐查看天气：http://www.362tq.com/yulinshi/7tian.html
 推荐查看天气：http://www.362tq.com/yulinshi/10tian.html
 推荐查看天气：http://www.362tq.com/yulinshi/15tian.html
 推荐查看天气：http://www.362tq.com/yulinshi/40tian.html
 推荐查看天气：http://www.362tq.com/yuyang/
 推荐查看天气：http://www.362tq.com/yuyang/zuotian.html
 推荐查看天气：http://www.362tq.com/yuyang/7tian.html
 推荐查看天气：http://www.362tq.com/yuyang/10tian.html
 推荐查看天气：http://www.362tq.com/yuyang/15tian.html
 推荐查看天气：http://www.362tq.com/yuyang/40tian.html
 推荐查看天气：http://www.362tq.com/shenmu/
 推荐查看天气：http://www.362tq.com/shenmu/zuotian.html
 推荐查看天气：http://www.362tq.com/shenmu/7tian.html
 推荐查看天气：http://www.362tq.com/shenmu/10tian.html
 推荐查看天气：http://www.362tq.com/shenmu/15tian.html
 推荐查看天气：http://www.362tq.com/shenmu/40tian.html
 推荐查看天气：http://www.362tq.com/fugu/
 推荐查看天气：http://www.362tq.com/fugu/zuotian.html
 推荐查看天气：http://www.362tq.com/fugu/7tian.html
 推荐查看天气：http://www.362tq.com/fugu/10tian.html
 推荐查看天气：http://www.362tq.com/fugu/15tian.html
 推荐查看天气：http://www.362tq.com/fugu/40tian.html
 推荐查看天气：http://www.362tq.com/hengshan/
 推荐查看天气：http://www.362tq.com/hengshan/zuotian.html
 推荐查看天气：http://www.362tq.com/hengshan/7tian.html
 推荐查看天气：http://www.362tq.com/hengshan/10tian.html
 推荐查看天气：http://www.362tq.com/hengshan/15tian.html
 推荐查看天气：http://www.362tq.com/hengshan/40tian.html
 推荐查看天气：http://www.362tq.com/jingbian/
 推荐查看天气：http://www.362tq.com/jingbian/zuotian.html
 推荐查看天气：http://www.362tq.com/jingbian/7tian.html
 推荐查看天气：http://www.362tq.com/jingbian/10tian.html
 推荐查看天气：http://www.362tq.com/jingbian/15tian.html
 推荐查看天气：http://www.362tq.com/jingbian/40tian.html
 推荐查看天气：http://www.362tq.com/dingbian/
 推荐查看天气：http://www.362tq.com/dingbian/zuotian.html
 推荐查看天气：http://www.362tq.com/dingbian/7tian.html
 推荐查看天气：http://www.362tq.com/dingbian/10tian.html
 推荐查看天气：http://www.362tq.com/dingbian/15tian.html
 推荐查看天气：http://www.362tq.com/dingbian/40tian.html
 推荐查看天气：http://www.362tq.com/suide/
 推荐查看天气：http://www.362tq.com/suide/zuotian.html
 推荐查看天气：http://www.362tq.com/suide/7tian.html
 推荐查看天气：http://www.362tq.com/suide/10tian.html
 推荐查看天气：http://www.362tq.com/suide/15tian.html
 推荐查看天气：http://www.362tq.com/suide/40tian.html
 推荐查看天气：http://www.362tq.com/mizhi/
 推荐查看天气：http://www.362tq.com/mizhi/zuotian.html
 推荐查看天气：http://www.362tq.com/mizhi/7tian.html

在 Vue 3 项目里，很多人在封装表单组件时都会用 v-model 来传递值，但自定义组件上的 v-model 和原生表单元素上的行为并不完全一样。特别是从 Vue 2 迁移过来，或者在组合式 API 里混用 defineModel 和手动 emit 时，经常会遇到“父组件值改了子组件没更新”“子组件输入父组件不同步”“多个 v-model 绑定时命名混乱”等问题。这些问题通常源于对 v-model 编译结果、modelValue 命名规则以及 update: 事件触发机制理解不透彻。下面从实际代码出发，梳理自定义组件上 v-model 的正确写法，以及一些容易踩坑的细节。

Vue 3 中 v-model 在自定义组件上的正确用法与常见陷阱

在 Vue 3 项目里，很多人在封装表单组件时都会用 v-model 来传递值，但自定义组件上的 v-model 和原生表单元素上的行为并不完全一样。特别是从 Vue 2 迁移过来，或者在组合式 API 里混用 defineModel 和手动 emit 时，经常会遇到“父组件值改了子组件没更新”“子组件输入父组件不同步”“多个 v-model 绑定时命名混乱”等问题。这些问题通常源于对 v-mod

前端

Vue3自定义组件v-model正确用法与踩坑指南：详解modelValue命名、update事件触发机制，通过本地状态管理避免同步冲突，支持多个v-model绑定及修饰符处理，使用defineModel简化代码并规避循环更新问题。

代码解释

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Vue 3 中 v-model 在自定义组件上的正确用法与常见陷阱-腾讯云开发者社区-腾讯云

Vue 3 中 v-model 在自定义组件上的正确用法与常见陷阱

Vue 3 中 v-model 在自定义组件上的正确用法与常见陷阱

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐