Vue中@update:model-value的作用、工作原理与父子组件用法示例

设计目的 #

@update:model-value是Vue组件双向绑定约定的标准组成部分，核心设计目标是维持单向数据流的一致性：

• 避免子组件直接修改父组件传入的prop引发的状态不可追溯问题
• 给自定义组件提供统一的双向绑定对接标准，让组件可以无缝适配v-model语法糖，减少重复样板代码

注意：模板中写的@update:model-value是驼峰事件名update:modelValue的短横线等价写法，受HTML标签属性不区分大小写的特性影响，两种写法在Vue模板中运行效果完全一致。

具体作用 #

结合给出的q-input代码片段，两个绑定的分工非常明确：

• :model-value="modelValue"：单向传值，父组件把自身的modelValue状态传递给q-input组件，作为输入框的当前显示值
• @update:model-value=""：事件监听，空白位置需要绑定值更新逻辑，用来接收q-input内部抛出的最新输入值，同步回父组件的状态
  当你把这两部分补全为标准写法后，本质就是v-model="modelValue"的完整展开形式——v-model本身是Vue提供的语法糖，编译阶段会自动拆解为prop传值+事件监听的组合，不需要手动编写重复代码。

运行机制 #

整个值同步流程是严格的单向闭环，不会出现双向状态篡改：

1. 初始渲染阶段，父组件将自身的响应式状态modelValue通过prop传入q-input，q-input将值渲染到输入框DOM上
2. 用户触发输入操作时，q-input内部不会直接修改传入的modelValueprop（Vue框架本身禁止子组件直接修改父级传入的prop），而是捕获最新的输入内容，通过emit('update:modelValue', 新输入值)的方式向外抛出值变更事件
3. 父组件上绑定的@update:model-value监听到事件后，拿到回调参数携带的新值，执行赋值操作更新自身的modelValue响应式状态
4. 父组件状态变更后，会将最新的modelValue重新传递给q-input组件，触发输入框重新渲染，完成一次完整的值同步循环

完整实现示例 #

父组件使用q-input的两种等价写法 #

写法1：手动展开v-model逻辑（即给出的代码补全后的可运行版本）

<template>
  <div>
    <p>当前输入内容：{{ inputText }}</p>
    <q-input
      :model-value="inputText"
      @update:model-value="newVal => inputText = newVal"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'
const inputText = ref('')
</script>

写法2：使用v-model语法糖简化，运行效果和写法1完全一致

<template>
  <div>
    <p>当前输入内容：{{ inputText }}</p>
    <q-input v-model="inputText" />
  </div>
</template>

<script setup>
import { ref } from 'vue'
const inputText = ref('')
</script>

子组件核心逻辑参考（模拟q-input的v-model实现） #

如果要自己实现一个和q-input行为一致的输入组件，核心逻辑如下，可以直观理解事件抛出的过程：

<!-- CustomInput.vue 自定义输入子组件 -->
<template>
  <input
    type="text"
    :value="modelValue"
    @input="handleInput"
  />
</template>

<script setup>
// 声明接收父组件传入的modelValue prop
const props = defineProps({
  modelValue: {
    type: String,
    default: ''
  }
})
// 声明对外抛出的update:modelValue事件
const emit = defineEmits(['update:modelValue'])

const handleInput = (e) => {
  // 输入变化时取到最新值，通过事件抛给父组件，不直接修改prop
  emit('update:modelValue', e.target.value)
}
</script>

内容的提问来源于stack exchange，提问作者Hawkeye345