Angular动态material-checkboxes默认选中时controlValue为空提交异常

我构建了一个仅包含material-checkboxes组件的Angular表单，该组件有静态和动态两个实现版本，唯一区别是动态版本的控件值从API调用获取，两者初始化时均有一个或多个选项默认勾选。

问题表现 #

• 未进行手动操作时，动态版本的模型与视图不同步，只要不点击任意复选框执行选中或取消操作，提交时就会返回空值，只有在点击任意复选框后，模型才会更新与视图同步
• 静态版本提交完全符合预期，默认选中项会正常提交，但动态版本即便视图显示有默认选中项，提交数据仍为空

静态版本效果 #

• 提交前默认状态：
• 提交后返回值（符合预期）：

动态版本效果 #

• 提交前控件状态（视图显示默认选中）：
• 提交后返回结果（为空不符合预期）：

运行结果对比 #

预期结果：this.controlValue = ['12', 'd4']
实际结果：

• onInit阶段：this.controlValue = ['12', 'd4']
• 执行updateValue方法后：this.controlValue = undefined （视图和初始化时完全一致）

如果我手动修改任意选项的值，哪怕改回和默认值完全一致，就能正常提交数据，看起来表单数据只有在手动点击选项后才会被正确设置

组件模板代码片段 #

<mat-checkbox
    type="checkbox"
    [class.mat-checkboxes-invalid]="showError && touched"
    [class.mat-checkbox-readonly]="options?.readonly"
    [checked]="allChecked"
    [disabled]="(controlDisabled$ | async) || options?.readonly"
    [color]="options?.color || 'primary'"
    [indeterminate]="someChecked"
    [name]="options?.name"
    (focusout)="onFocusOut()"
    (change)="updateAllValues($event)"
    [required]="required"
    [value]="controlValue">

解决方案 #

原因分析 #

该问题核心是异步数据加载的变更检测时序问题：API返回数据是异步操作，给controlValue赋值时没有同步通知Angular表单控件更新自身状态，表单仍认为控件值为初始空值，只有手动触发change事件后才会将视图状态同步到模型。

修复方案 #

1. 异步赋值后手动触发控件值更新
   如果使用响应式表单，在API获取到数据、给controlValue赋值完成后，手动调用表单控件的setValue/patchValue方法，同步模型状态：

this.apiService.getCheckboxOptions().subscribe(res => {
  this.titleMap = res;
  this.controlValue = ['12', 'd4'];
  // 手动更新表单控件值
  this.checkboxControl.setValue(this.controlValue);
  // 若仍有不同步问题，手动触发变更检测
  this.changeDetectorRef.markForCheck();
})

2. 补充双向绑定配置
   当前模板仅绑定了[value]单向输入，没有添加模型绑定逻辑，导致视图状态不会自动同步回模型：

• 模板驱动表单补充[(ngModel)]绑定

<mat-checkbox
  <!-- 其他原有属性保持不变 -->
  [(ngModel)]="controlValue">

• 响应式表单补充formControl绑定

<mat-checkbox
  <!-- 其他原有属性保持不变 -->
  [formControl]="checkboxControl">

3. 初始化后手动调用状态同步方法
   检查updateAllValues方法逻辑，在初始化赋值完成后手动调用一次该方法，将初始选中状态同步到表单模型：

this.controlValue = ['12', 'd4'];
this.updateAllValues();

内容的提问来源于stack exchange，提问作者js-newb