NG-ZORRO中nz-checkbox-group与响应式表单的正确使用方式

在使用NG-ZORRO组件库开发Angular应用时，nz-checkbox-group是一个常用的多选框组件。最近有开发者反馈在Angular 19和NG-ZORRO 19版本中，该组件与响应式表单配合使用时出现了显示问题。本文将详细介绍这个问题的原因和解决方案。

问题现象

开发者在使用nz-checkbox-group组件时，发现当它与响应式表单结合使用时，无法正常显示数据。具体表现为：

<form nz-form [formGroup]="demoForm">
    <h1>Options:</h1>
    <nz-checkbox-group formControlName="options" />
</form>

demoForm = new FormGroup({
    options: new FormControl([
        { label: 'Apple', value: 'Apple' },
        { label: 'Pear', value: 'Pear' },
        { label: 'Orange', value: 'Orange' },
    ]),
});

问题原因分析

经过NG-ZORRO团队确认，这个问题源于两个关键配置项的误解：

1. options属性未设置：nz-checkbox-group需要显式设置[options]属性来定义可选项
2. 表单值格式不正确：formControl的值应该是选项值(NzCheckboxOption['value'])的数组，而不是完整的选项对象数组

正确使用方法

要使nz-checkbox-group在响应式表单中正常工作，需要按照以下方式配置：

1. 定义选项列表：首先需要定义完整的选项列表
2. 设置表单值：表单控制的值应该是选中项的value数组

listOfOptions = [
    { label: 'Apple', value: 'Apple' },
    { label: 'Pear', value: 'Pear' },
    { label: 'Orange', value: 'Orange' },
];

demoForm = new FormGroup({
    selectedOptions: new FormControl(['Apple']), // 这里应该是选中项的value数组
});

<nz-checkbox-group
    formControlName="selectedOptions"
    [nzOptions]="listOfOptions"
/>

版本兼容性说明

这个问题在NG-ZORRO 19版本中被明确为预期行为，而非bug。开发者在升级到Angular 19和NG-ZORRO 19时需要注意这一变化。

最佳实践建议

1. 分离选项定义和选中值：保持选项列表和表单值的分离，这样更符合Angular响应式表单的设计理念
2. 类型安全：为选项列表和表单值定义明确的类型，可以提高代码的可维护性
3. 文档参考：虽然本文提供了解决方案，但建议开发者定期查阅官方文档以获取最新API变更

通过以上方式，开发者可以正确地在响应式表单中使用nz-checkbox-group组件，实现多选框功能。