Vue3自定义复选框组件绑定选中值数组失效问题排查

当使用自定义Checkbox组件绑定数组类型的v-model时，会出现所有复选框同步选中/取消、数组被替换为布尔值的异常，而原生HTML复选框绑定数组可正常收集选中值。核心原因是自定义组件的modelValue类型定义和emit逻辑未复现Vue原生复选框处理数组的行为。

原生复选框的处理逻辑 #

原生复选框绑定数组时，Vue会自动维护数组内容：

• 勾选复选框：将对应value添加到数组
• 取消勾选：将对应value从数组移除
  不会直接将数组替换为布尔值，这是原生组件内置的多值适配逻辑。

解决方案 #

修改自定义Checkbox组件，使其适配数组类型的v-model：

修改后的自定义Checkbox组件代码 #

<template>
  <div class="mt-1 relative">
    <input
      type="checkbox"
      :id="id"
      :name="name"
      :value="value"
      :checked="isChecked"
      class="bg-gray-200 text-gold-500 rounded border-0 w-5 h-5 mr-2 focus:ring-2 focus:ring-gold-500"
      @input="updateValue"
    />
    <label v-if="label" :for="id">{{ label }}</label>
  </div>
</template>

<script setup>
import { computed } from 'vue'

const props = defineProps({
  id: String,
  label: String,
  name: String,
  value: String,
  errors: Object,
  modelValue: [Boolean, Array] // 允许布尔或数组类型
})

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

// 动态计算当前复选框的选中状态
const isChecked = computed(() => {
  if (Array.isArray(props.modelValue)) {
    return props.modelValue.includes(props.value)
  }
  // 兼容布尔值绑定的场景
  return !!props.modelValue
})

const updateValue = function(event) {
  const isChecked = event.target.checked
  if (Array.isArray(props.modelValue)) {
    let newModelValue
    if (isChecked) {
      // 避免重复添加相同值
      newModelValue = [...new Set([...props.modelValue, props.value])]
    } else {
      // 移除对应value
      newModelValue = props.modelValue.filter(item => item !== props.value)
    }
    emit('update:modelValue', newModelValue)
  } else {
    // 布尔值绑定场景，直接emit布尔值
    emit('update:modelValue', isChecked)
  }
}
</script>

父组件代码（无需修改） #

<template>
  <div>
    <div class="mt-6">
      <Checkbox v-model="status" value="EVO" label="EVO" name="status"  />
      <Checkbox v-model="status" value="Solist" label="Solist" name="status" />
      <Checkbox v-model="status" value="SPL" label="SPL" name="status" />
    </div>
    <div class="mt-3">{{status}}</div>
  </div>
</template>

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

let status = ref([]);
</script>

关键修改点说明 #

1. 类型兼容：将modelValue的类型定义为[Boolean, Array]，同时支持单布尔值和多值数组两种绑定场景
2. 动态选中状态：通过computed属性判断当前value是否在数组中，或直接使用布尔值，适配不同绑定类型
3. 数组更新逻辑：针对数组类型的modelValue，通过添加/移除value来更新数组，而非直接赋值布尔值，完全复现原生复选框的行为

内容的提问来源于stack exchange，提问作者Axel Köhler