Vue3嵌套组件v-model绑定问题：复选框初始状态与值更新异常

一、核心问题分析 #

1. Vue3与Vue2的v-model机制差异：Vue3默认使用modelValue prop + update:modelValue事件，而非Vue2的value + input
2. 硬编码:checked="true"覆盖了v-model的状态，导致初始值不生效
3. 重复触发值更新逻辑：v-model的setter和@input事件的onInput同时修改this.value，且类型不匹配（数组 vs 布尔值）
4. 组件间事件传递未适配Vue3，导致值无法正确同步

二、逐组件修改方案 #

1. FormCheckboxBase.vue（底层复选框） #

恢复事件触发，确保原生事件正确向上传递：

<template>
  <div :class="$style['form-item']">
    <input
      :id="id"
      :value="inputValue"
      @change="updateInput"
      :type="type"
      v-bind="$attrs"
      class="input"
      :class="$style.input"
    />
    <slot />
  </div>
</template>

<script>
export default {
  props: {
    type: {
      type: String,
      default: 'checkbox',
    },
    inputValue: {
      type: String,
      required: true,
    },
    title: {
      type: String,
      required: true,
    },
    id: {
      type: String,
      required: true,
    },
    required: {
      type: Boolean,
      default: false,
    },
    checkboxList: {
      type: Boolean,
      default: false,
    },
  },
  methods: {
    updateInput(event) {
      this.$emit('updateInput', event); // 恢复事件触发，传递原生事件对象
    },
  },
};
</script>

2. FormCheckbox.vue（中间层组件） #

适配Vue3的v-model规范，替换prop和事件名：

<template>
  <FormCheckboxBase
    :checked="shouldBeChecked"
    type="checkbox"
    :class="$style.check"
    :input-value="inputValue"
    :title="title"
    :id="id"
    :name="name"
    :required="required"
    v-bind="$attrs"
    @updateInput="updateInput"
  />
</template>

<script>
export default {
  components: {
    FormCheckboxBase,
  },
  props: {
    // 替换Vue2的value为Vue3的modelValue
    modelValue: {
      type: Array,
      default: () => [],
    },
    inputValue: {
      type: String,
      required: true,
    },
    title: {
      type: String,
      required: true,
    },
    id: {
      type: String,
      required: true,
    },
    name: {
      type: String,
      default: '',
    },
    required: {
      type: Boolean,
      default: false,
    },
  },
  computed: {
    shouldBeChecked() {
      if (!this.modelValue) {
        return false;
      }
      return this.modelValue.includes(this.inputValue);
    },
  },
  methods: {
    updateInput(event) {
      const { checked, value } = event.target;
      const newValue = [...this.modelValue];

      if (checked) {
        newValue.push(value);
      } else {
        const index = newValue.indexOf(value);
        if (index > -1) {
          newValue.splice(index, 1);
        }
      }
      // 触发Vue3的v-model更新事件
      this.$emit('update:modelValue', newValue);
    },
  },
};
</script>

3. CheckboxFieldComponent.vue（上层业务组件） #

移除硬编码的checked属性，避免重复更新逻辑：

<template>
  <div v-show="isVisible">
    <FormCheckbox
      v-model="booleanFromStoreConvertedToArray"
      :input-value="field.model.itemId"
      :title="title"
      :id="field.valueField.id"
      :class="field.model.cssClass"
      :name="field.valueField.name"
      <!-- 移除硬编码的:checked="true"，避免覆盖v-model状态 -->
      :required="required"
      :disabled="!isEnabled"
      <!-- 移除@input里的onInput调用，因为v-model的setter已经处理了value更新 -->
      @change="$emit('change')"
      @focus="field.tracker.onFocusField(field, value)"
      @blur="field.tracker.onBlurField(field, value, errors.value)"
    />
  </div>
</template>

<script>
export default {
  extends: BaseField,
  computed: {
    booleanFromStoreConvertedToArray: {
      get() {
        const isSelected = this.value;
        return isSelected ? [this.field.model.itemId] : [];
      },
      set(value) {
        // 这里已经更新了this.value，无需再通过onInput重复处理
        this.value = value.length > 0;
        // 直接在这里调用验证逻辑，避免重复触发
        this.validate();
      },
    },
  },
};
</script>

4. BaseField.vue（基类组件） #

因为已经在CheckboxFieldComponent的setter里调用了validate，可移除onInput中的重复逻辑：

onInput(value) {
  // 现在由v-model的setter处理value更新，此方法可根据其他业务场景保留或调整
  // this.value = value;
  // this.validate();
},

三、初始值设置说明 #

初始值由父组件传递给CheckboxFieldComponent的value prop（继承自BaseField），只要父组件传入API获取的初始布尔值（false对应未选中），booleanFromStoreConvertedToArray的getter会返回空数组，FormCheckbox的shouldBeChecked就会返回false，复选框将处于未选中状态。

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