Vue3中v-model双向绑定的避坑指南(2026最新)

<template>
  <div class="form-demo">
    <!-- 文本输入 -->
    <input v-model="username" placeholder="账号" />
    <!-- 密码 -->
    <input v-model="password" type="password" placeholder="密码" />
    <!-- 多行文本 -->
    <textarea v-model="bio" placeholder="个人简介"></textarea>
    <!-- 复选框（布尔值） -->
    <label>
      <input type="checkbox" v-model="agree" />
      同意用户协议
    </label>
    <!-- 实时预览 -->
    <div class="preview">
      账号：{{ username }}
      密码：{{ password }}
      简介：{{ bio }}
      已同意：{{ agree ? '✅' : '❌' }}
    </div>
  </div>
</template>
<script setup>
import { ref } from 'vue'
const username = ref('')
const password = ref('')
const bio = ref('')
const agree = ref(false)
</script>

<template>
  <div class="my-input">
    <span>自定义：</span>
    <input
      :value="modelValue"
      @input="$emit('update:modelValue', $event.target.value)"
      placeholder="请输入..."
    />
  </div>
</template>
<script setup>
// 必须叫 modelValue！
const props = defineProps(['modelValue'])
// 必须 emit update:modelValue！
const emit = defineEmits(['update:modelValue'])
</script>

<template>
  <MyInput v-model="customText" />
  <p>输入内容：{{ customText }}</p>
</template>

<script setup>
import { ref } from 'vue'
import MyInput from './MyInput.vue'

const customText = ref('')
</script>

<template>
  <UserForm 
    v-model:name="user.name"
    v-model:age="user.age"
    v-model:email="user.email"
  />
  <pre>{{ user }}</pre>
</template>

<script setup>
import { reactive } from 'vue'
import UserForm from './UserForm.vue'

const user = reactive({
  name: '',
  age: 0,
  email: ''
})
</script>

<template>
  <div>
    <input v-model="nameProxy" placeholder="姓名" />
    <input v-model.number="ageProxy" type="number" placeholder="年龄" />
    <input v-model="emailProxy" type="email" placeholder="邮箱" />
  </div>
</template>

<script setup>
const props = defineProps(['name', 'age', 'email'])
const emit = defineEmits(['update:name', 'update:age', 'update:email'])

// 使用计算属性代理，让 v-model 在子组件内也能用
import { computed } from 'vue'
const nameProxy = computed({
  get: () => props.name,
  set: (val) => emit('update:name', val)
})
const ageProxy = computed({
  get: () => props.age,
  set: (val) => emit('update:age', val)
})
const emailProxy = computed({
  get: () => props.email,
  set: (val) => emit('update:email', val)
})
</script>

// 错误 
let text = '' // 普通变量
// v-model="text" → 修改无效！
// 正确 
const text = ref('') // 响应式

// 错误（Vue2 写法）
defineProps(['value'])
defineEmits(['input'])
// 正确（Vue3 标准）
defineProps(['modelValue'])
defineEmits(['update:modelValue'])

<!-- 错误  -->
<input v-model="msg" :value="defaultValue" />
<!-- 正确  -->
<input v-model="msg" />
<!-- 或初始化时：const msg = ref(defaultValue) -->

// MyInput.vue (TypeScript 版)
<script setup lang="ts">
interface Props {
  modelValue: string
}
const props = defineProps<Props>()
const emit = defineEmits<{
  (e: 'update:modelValue', value: string): void
}>()
</script>