Vue组件报错：Unexpected mutation of 'apiStepNumber' prop求解决

问题背景 #

在父组件中通过API调用进度更新apiNumber变量，并将其作为apiStepNumber prop传递给子组件。子组件使用Vuetify的v-stepper，需要将这个prop绑定到v-model上，但直接绑定会触发"Unexpected mutation of 'apiStepNumber' prop"错误。

父组件代码 #

// API调用成功时更新步骤
if(firstApiCallSuccessful) this.apiNumber = 2;
if(secondApiCallSuccessful) this.apiNumber = 3;
// ...以此类推

<child-component :apiStepNumber="apiNumber"></child-component>

子组件代码 #

<script>
export default {
    props: {
        apiStepNumber: {
            type: Number,
            required: true,
            default: 1,
        },
    },
    data() {
        return {
            steps: [
                { id: 1, text: "Emailing the Link" },
                { id: 2, text: "Getting Details" },
                { id: 3, text: "Extracting Data" },
                { id: 4, text: "Validating Data" },
                { id: 5, text: "Almost there..." },
                { id: 6, text: "All Done!" },
            ],
        };
    },
}
</script>

<v-stepper v-model="apiStepNumber" vertical>
  <v-stepper-step
    v-for="(item, i) in steps"
    :key="item.id"
    :complete="apiStepNumber > i + 1"
    :step="i + 1"
    :color="apiStepNumber > i + 1 ? 'success' : 'primary'"
  >{{ item.text }}</v-stepper-step>
</v-stepper>

已尝试将prop存到子组件本地data，但不符合需求，因为需要和父组件的状态保持实时同步。

解决方案 #

方案1：使用.sync修饰符实现双向绑定 #

Vue的.sync修饰符专门用于实现prop的双向绑定，既遵守单向数据流规则，又能保持父子组件状态同步。

1. 修改父组件的prop传递方式

<child-component :apiStepNumber.sync="apiNumber"></child-component>

2. 子组件中用计算属性替代直接绑定prop
   通过计算属性的get读取prop值，set时触发更新事件通知父组件修改状态：

<script>
export default {
    props: {
        apiStepNumber: {
            type: Number,
            required: true,
            default: 1,
        },
    },
    data() {
        return {
            steps: [
                { id: 1, text: "Emailing the Link" },
                { id: 2, text: "Getting Details" },
                { id: 3, text: "Extracting Data" },
                { id: 4, text: "Validating Data" },
                { id: 5, text: "Almost there..." },
                { id: 6, text: "All Done!" },
            ],
        };
    },
    computed: {
        localStepNumber: {
            get() {
                return this.apiStepNumber;
            },
            set(newValue) {
                this.$emit('update:apiStepNumber', newValue);
            }
        }
    }
}
</script>

3. 修改子组件模板的v-model绑定

<v-stepper v-model="localStepNumber" vertical>
  <v-stepper-step
    v-for="(item, i) in steps"
    :key="item.id"
    :complete="localStepNumber > i + 1"
    :step="i + 1"
    :color="localStepNumber > i + 1 ? 'success' : 'primary'"
  >{{ item.text }}</v-stepper-step>
</v-stepper>

方案2：拆分v-model为value和input事件 #

v-model本质是:value和@input的语法糖，手动拆分可以避免直接修改prop：

1. 修改子组件模板

<v-stepper :value="apiStepNumber" @input="handleStepChange" vertical>
  <v-stepper-step
    v-for="(item, i) in steps"
    :key="item.id"
    :complete="apiStepNumber > i + 1"
    :step="i + 1"
    :color="apiStepNumber > i + 1 ? 'success' : 'primary'"
  >{{ item.text }}</v-stepper-step>
</v-stepper>

2. 子组件添加事件处理方法

<script>
export default {
    props: {
        apiStepNumber: {
            type: Number,
            required: true,
            default: 1,
        },
    },
    data() {
        return {
            steps: [
                { id: 1, text: "Emailing the Link" },
                { id: 2, text: "Getting Details" },
                { id: 3, text: "Extracting Data" },
                { id: 4, text: "Validating Data" },
                { id: 5, text: "Almost there..." },
                { id: 6, text: "All Done!" },
            ],
        };
    },
    methods: {
        handleStepChange(newValue) {
            this.$emit('update:apiStepNumber', newValue);
        }
    }
}
</script>

3. 父组件监听更新事件
   如果不用.sync，父组件需要手动监听事件更新状态：

<child-component 
  :apiStepNumber="apiNumber" 
  @update:apiStepNumber="apiNumber = $event"
></child-component>

原理说明 #

Vue的单向数据流规则禁止子组件直接修改prop，因为prop是父组件维护的状态，直接修改会导致数据流向混乱，难以追踪状态变化。上述方案通过事件通知父组件更新状态，既遵守了单向数据流原则，又实现了父子组件的状态同步。

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