Vue3 自定义 v-model 高级用法：从基础到实战

<template>
  <div>
    <h3>基础 v-model 绑定：{{ name }}</h3>
    <!-- 直接使用 v-model 绑定 -->
    <CustomInput v-model="name" />
  </div>
</template>

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

// 绑定的数据
const name = ref('')
</script>

✅ 核心要点：

1. 子组件必须接收 modelValue 属性
2. 子组件必须触发 update:modelValue 事件
3. 父组件直接用 v-model 绑定即可

三、进阶版：多 v-model 绑定（一个组件绑定多个值）

Vue3 支持一个自定义组件上使用多个 v-model，这在封装复杂表单组件（如用户信息表单、地址选择器）时非常实用。

实现原理：给每个 v-model 指定自定义参数，格式为 v-model:参数名，子组件对应接收 参数名 属性，触发 update:参数名 事件。

1. 子组件实现（UserForm.vue）

封装一个同时绑定「用户名、年龄」的表单组件：

<template>
  <div>
    <div>
      <label>用户名：</label>
      <input :value="username" @input="emit('update:username', $event.target.value)" />
    </div>
    <div>
      <label>年龄：</label>
      <input type="number" :value="age" @input="emit('update:age', $event.target.value)" />
    </div>
  </div>
</template>

<script setup>
// 接收两个自定义参数属性：username、age
const props = defineProps({
  username: String,
  age: [String, Number]
})

// 定义两个更新事件
const emit = defineEmits(['update:username', 'update:age'])
</script>

2. 父组件使用

<template>
  <div>
    <h3>多 v-model 绑定</h3>
    <p>用户名：{{ userInfo.username }}，年龄：{{ userInfo.age }}</p>
    <!-- 多个 v-model:参数名 绑定 -->
    <UserForm v-model:username="userInfo.username" v-model:age="userInfo.age" />
  </div>
</template>

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

const userInfo = ref({
  username: '',
  age: ''
})
</script>

✅ 核心要点：

1. 多 v-model 格式：v-model:自定义参数
2. 子组件属性名 = 自定义参数名
3. 子组件事件名 = update:自定义参数名

四、高级版：自定义 v-model 修饰符

Vue 原生提供了 .trim、.number、.lazy 等修饰符，Vue3 允许我们自定义修饰符，实现个性化的数据处理逻辑（如格式化输入、限制输入内容、脱敏处理等）。

核心规则

1. 修饰符名称格式：参数名 + Modifiers（默认参数 modelValue 对应 modelModifiers）
2. 子组件通过 props 接收修饰符，在触发事件前处理数据

实战：自定义 capitalize（首字母大写）+ noSpecial（无特殊字符）修饰符

1. 子组件实现（CustomInputModifiers.vue）

<template>
  <input :value="modelValue" @input="handleInput" placeholder="测试自定义修饰符" />
</template>

<script setup>
const props = defineProps({
  modelValue: String,
  // 接收默认 v-model 的修饰符：固定写法
  modelModifiers: {
    type: Object,
    default: () => ({})
  }
})

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

const handleInput = (e) => {
  let value = e.target.value
  
  // 1. 处理 capitalize 修饰符：首字母大写
  if (props.modelModifiers.capitalize) {
    value = value.charAt(0).toUpperCase() + value.slice(1)
  }
  
  // 2. 处理 noSpecial 修饰符：过滤特殊字符
  if (props.modelModifiers.noSpecial) {
    value = value.replace(/[^\u4e00-\u9fa5a-zA-Z0-9]/g, '')
  }
  
  // 触发事件，传递处理后的值
  emit('update:modelValue', value)
}
</script>

2. 父组件使用

<template>
  <div>
    <h3>自定义修饰符：{{ content }}</h3>
    <!-- 同时使用两个自定义修饰符 -->
    <CustomInputModifiers v-model.capitalize.noSpecial="content" />
  </div>
</template>

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

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

带参数的 v-model + 自定义修饰符

如果是带参数的 v-model，修饰符接收格式为：参数名 + Modifiers

<!-- 父组件 -->
<Child v-model:user.trim="user" />

<!-- 子组件 props -->
const props = defineProps({
  user: String, // 对应 user 参数的修饰符
  userModifiers: Object
})

五、实战场景：封装自定义弹窗组件（v-model 控制显隐）

日常开发中，弹窗组件是最常用的自定义 v-model 场景之一，用 v-model 控制 visible 显隐状态，比手动传 props+ 监听事件更简洁。

1. 子组件（CustomModal.vue）

<template>
  <!-- 弹窗蒙层 -->
  <div v-if="modelValue" @click="close">
    <!-- 弹窗内容 -->
    <div @click.stop>
      <slot>默认弹窗内容</slot>
      <button @click="close">关闭</button>
    </div>
  </div>
</template>

<script setup>
const props = defineProps({
  // 控制显隐的 v-model 属性
  modelValue: Boolean
})

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

// 关闭弹窗：触发更新事件
const close = () => {
  emit('update:modelValue', false)
}
</script>

<style scoped>
.modal-mask {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background: rgba(0, 0, 0, 0.5);
  display: flex;
  align-items: center;
  justify-content: center;
}
.modal-content {
  background: #fff;
  padding: 20px;
  border-radius: 8px;
  min-width: 300px;
  position: relative;
}
.close-btn {
  margin-top: 15px;
  padding: 6px 12px;
  background: #409eff;
  color: #fff;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}
</style>

2. 父组件使用

<template>
  <div>
    <button @click="showModal = true">打开弹窗</button>
    <!-- v-model 控制弹窗显隐 -->
    <CustomModal v-model="showModal">
      <h3>自定义弹窗</h3>
      <p>使用 v-model 控制显隐，更简洁！</p>
    </CustomModal>
  </div>
</template>

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

const showModal = ref(false)
</script>

六、Vue3 自定义 v-model 核心总结

1. 基础绑定：子组件接收 modelValue，触发 update:modelValue
2. 多绑定：使用 v-model:参数名，子组件对应接收/触发
3. 自定义修饰符：通过 xxxModifiers 接收，在事件中处理数据
4. 最佳实践：封装表单组件、弹窗、开关等双向绑定场景优先用 v-model
5. 语法糖优势：简化代码，无需手动监听事件和传递属性

七、注意事项

1. Vue3 中不建议直接修改 props，必须通过触发事件的方式更新
2. 多 v-model 和自定义修饰符仅支持 Vue3，Vue2 不兼容
3. 修饰符命名建议语义化，避免和原生修饰符重名

结语

Vue3 自定义 v-model 是组件封装的核心技能，掌握高级用法后，能大幅提升代码复用性和开发效率。无论是简单的输入框，还是复杂的表单、弹窗组件，都能通过 v-model 实现简洁优雅的双向绑定。