ng-zorro-antd Checkbox 多选框组件完全指南：API 详解、源码原理与实战示例

UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载ng-zorro-antd 是 Angular 生态下基于 Ant Design 设计语言的 UI 组件库其 Checkbox多选框组件用于在一组可选项中进行多项选择或单独使用表示两种状态之间的切换。本指南以官方文档为核心结合仓库源码与测试用例系统讲解nz-checkbox、nz-checkbox-group的完整 API、双向绑定、禁用与半选indeterminate状态、全选联动以及表单集成的底层实现帮助你在真实项目中快速落地并理解其运行机制。何时使用 Checkbox根据官方文档 components/checkbox/doc/index.zh-CN.mdCheckbox 适合在以下两种场景中使用一组可选项中进行多项选择例如权限配置、兴趣标签、多条件筛选用户可同时勾选多个选项最终值与提交操作配合单独使用表示两种状态之间的切换功能上与switch类似但两者有本质区别——切换switch会直接触发状态改变而checkbox一般用于状态标记需要和提交操作配合使用即用户勾选后仍需通过按钮等操作提交。API 详解[nz-checkbox] 单选 Checkboxnz-checkbox是一个属性型选择器selector 为[nz-checkbox]通常直接作用于label元素上声明为exportAs: nzCheckbox。其完整输入输出参数如下参数说明类型默认值[nzId]组件内部 input 的id值string-[nzName]组件内部 input 的name值string-[nzAutoFocus]自动获取焦点booleanfalse[nzDisabled]设定 disable 状态booleanfalse[ngModel]指定当前是否选中可双向绑定booleanfalse[nzIndeterminate]设置 indeterminate 状态只负责样式控制booleanfalse[nzValue]仅与nz-checkbox-wrapper即 group 内部的选中回调配合使用any-(ngModelChange)选中变化时回调EventEmitterboolean-从源码 checkbox.component.ts 可以看到nzAutoFocus、nzDisabled、nzIndeterminate、nzChecked均通过booleanAttribute变换函数接收输入因此模板中可以简写为label nz-checkbox nzDisabled而不必显式传值。方法名称描述focus()获取焦点blur()移除焦点这两个方法的底层实现见 checkbox.component.tsfocus()借助angular/cdk/a11y的FocusMonitor.focusVia(this.inputElement, keyboard)以键盘方式聚焦到内部 inputblur()直接调用原生 input 的blur()。测试用例 checkbox.spec.ts 验证了调用focus()后document.activeElement即为内部 input调用blur()后焦点移除。基本用法示例最简单的用法来自官方 demo basic.ts使用[(ngModel)]双向绑定import { Component, signal } from angular/core; import { FormsModule } from angular/forms; import { NzCheckboxModule } from ng-zorro-antd/checkbox; Component({ selector: nz-demo-checkbox-basic, imports: [FormsModule, NzCheckboxModule], template: label nz-checkbox [(ngModel)]checkedCheckbox/label }) export class NzDemoCheckboxBasicComponent { readonly checked signal(true); }受控与非受控切换官方 demo controller.ts 展示了如何用外部按钮控制勾选与禁用状态Component({ selector: nz-demo-checkbox-controller, imports: [FormsModule, NzButtonModule, NzCheckboxModule], template: label nz-checkbox [(ngModel)]checked [nzDisabled]disabled() {{ checked() ? Checked : Unchecked }} - {{ disabled() ? Disabled : Enabled }} /label br /br / button nz-button nzTypeprimary (click)toggleChecked() nzSizesmall {{ checked() ? Uncheck : Check }} /button button nz-button nzTypeprimary (click)toggleDisabled() nzSizesmall {{ disabled() ? Enable : Disable }} /button }) export class NzDemoCheckboxControllerComponent { readonly checked signal(true); readonly disabled signal(false); toggleChecked(): void { this.checked.update(checked !checked); } toggleDisabled(): void { this.disabled.update(disabled !disabled); } }禁用态官方 demo disabled.ts 展示未选中与已选中两种禁用场景Component({ selector: nz-demo-checkbox-disabled, imports: [FormsModule, NzCheckboxModule], template: label nz-checkbox nzDisabled [ngModel]false/label br / label nz-checkbox nzDisabled [ngModel]true/label }) export class NzDemoCheckboxDisabledComponent {}nz-checkbox-group 复选框组nz-checkbox-groupselector 为nz-checkbox-groupexportAs: nzCheckboxGroup用于管理一组同义选项的多选值。其参数如下参数说明类型默认值[ngModel]指定可选项可双向绑定string[] \| number[][][nzName]CheckboxGroup 下所有 input 的name属性string-[nzOptions]指定可选项string[] \| number[] \| NzCheckboxOption[][][nzDisabled]设定全部 checkbox disable 状态booleanfalse(ngModelChange)选中数据变化时的回调EventEmitterstring[] \| number[]-从源码 checkbox-group.component.ts 可以看到nzName、nzDisabled、nzOptions均以 Angular 信号signal形式声明组件内部通过linkedSignal实现finalDisabled确保「表单控件禁用」与「nzDisabled属性禁用」二者合一。InterfacesNzCheckboxOptionnzOptions除了可以接收string[] | number[]的简写形式外还支持结构化配置对象export interface NzCheckboxOption { label: string; value: string | number; disabled?: boolean; }该接口定义于 checkbox-group.component.ts。当传入纯字符串或数字数组时组件内部的normalizeOptions()会将其规范化为{ label: value, value }形式见 checkbox-group.component.ts因此三种写法等价// 写法一纯字符串数组 options [Apple, Pear, Orange]; // 写法二纯数字数组 options [1, 2, 3]; // 写法三结构化配置支持单独禁用某一项 options: NzCheckboxOption[] [ { label: Apple, value: Apple }, { label: Pear, value: Pear }, { label: Orange, value: Orange, disabled: true } ];实战示例复选框组基本用法官方 demo group.ts 展示了 group 的标准用法包括多组复用、结构化禁用与整体禁用import { Component, signal } from angular/core; import { FormsModule } from angular/forms; import { NzCheckboxModule, NzCheckboxOption } from ng-zorro-antd/checkbox; Component({ selector: nz-demo-checkbox-group, imports: [FormsModule, NzCheckboxModule], template: nz-checkbox-group [nzOptions]options1 [(ngModel)]value (ngModelChange)log($event) / br /br / nz-checkbox-group [nzOptions]options2 [(ngModel)]value (ngModelChange)log($event) / br /br / nz-checkbox-group nzDisabled [nzOptions]options3 [(ngModel)]value (ngModelChange)log($event) / }) export class NzDemoCheckboxGroupComponent { readonly options1: NzCheckboxOption[] [ { label: Apple, value: Apple }, { label: Pear, value: Pear }, { label: Orange, value: Orange } ]; readonly options2: NzCheckboxOption[] [ { label: Apple, value: Apple }, { label: Pear, value: Pear }, { label: Orange, value: Orange, disabled: true } ]; readonly options3: NzCheckboxOption[] [ { label: Apple, value: Apple }, { label: Pear, value: Pear }, { label: Orange, value: Orange } ]; readonly value signal([Apple]); log(value: string[]): void { console.log(value); } }其中第三组使用了属性简写nzDisabled等价于[nzDisabled]true。测试用例 checkbox-group.spec.ts 验证了 options 为对象数组、数字数组、字符串数组三种形态时均能正确渲染出对应 label 文本。全选与半选indeterminate联动nzIndeterminate只负责样式控制不参与选中语义这是实现「全选 / 半选」联动的基础。官方 demo check-all.ts 给出了完整实现import { Component, computed, signal } from angular/core; import { FormsModule } from angular/forms; import { NzCheckboxModule, NzCheckboxOption } from ng-zorro-antd/checkbox; import { NzDividerModule } from ng-zorro-antd/divider; Component({ selector: nz-demo-checkbox-check-all, imports: [FormsModule, NzCheckboxModule, NzDividerModule], template: label nz-checkbox [ngModel]allChecked() (ngModelChange)onAllCheckedChange($event) [nzIndeterminate]indeterminate() Check all /label nz-divider / nz-checkbox-group [nzOptions]options [(ngModel)]value / }) export class NzDemoCheckboxCheckAllComponent { readonly value signalArrayNzCheckboxOption[value]([Apple, Orange]); readonly options: NzCheckboxOption[] [ { label: Apple, value: Apple }, { label: Pear, value: Pear }, { label: Orange, value: Orange } ]; readonly allChecked computed(() this.value().length this.options.length); readonly indeterminate computed(() this.value().length 0 !this.allChecked()); onAllCheckedChange(checked: boolean): void { this.value.set(checked ? this.options.map(item item.value) : []); } }这里的核心逻辑值得留意allChecked()通过computed派生当已选数量等于选项总数时为全选indeterminate()当已选数量大于 0 且未全选时为真此时顶部 Checkbox 显示为「横杠」半选样式点击顶部 Checkbox 后onAllCheckedChange根据结果一次性设置全部或清空值。从源码角度验证在 checkbox.component.ts 的模板中ant-checkbox-checked样式类仅在nzChecked !nzIndeterminate时生效ant-checkbox-indeterminate单独由nzIndeterminate控制——这印证了「半选只控制样式、不参与选中状态」的设计。测试 checkbox.spec.ts 也验证了设置为nzIndeterminate后 wrapper 会带上ant-checkbox-indeterminate类。自定义布局在 group 中内嵌任意子元素官方 demo layout.ts 展示了另一种高级用法nz-checkbox-group除了nzOptions数据驱动方式外还支持投影内容ng-content自定义布局让nzValue与布局解耦import { Component } from angular/core; import { FormsModule } from angular/forms; import { NzCheckboxModule } from ng-zorro-antd/checkbox; import { NzGridModule } from ng-zorro-antd/grid; Component({ selector: nz-demo-checkbox-layout, imports: [FormsModule, NzCheckboxModule, NzGridModule], template: nz-checkbox-group ngModelA [style.width.%]100 nz-row nz-col nzSpan8 label nz-checkbox nzValueAA/label /nz-col nz-col nzSpan8 label nz-checkbox nzValueBB/label /nz-col nz-col nzSpan8 label nz-checkbox nzValueCC/label /nz-col nz-col nzSpan8 label nz-checkbox nzValueDD/label /nz-col nz-col nzSpan8 label nz-checkbox nzValueEE/label /nz-col /nz-row /nz-checkbox-group }) export class NzDemoCheckboxLayoutComponent {}这里的nzValue就是为这种场景设计的group 模板通过ng-content投影子元素见 checkbox-group.component.ts每个投影进来的nz-checkbox将nzValue上报给 groupgroup 据此维护选中值集合。测试 checkbox-group.spec.ts 验证了点击自定义布局中的复选框时group 的绑定值会正确增删对应nzValue。源码级原理剖析双向绑定与控制值访问器CVAnz-checkbox与nz-checkbox-group都实现了ControlValueAccessor接口以NG_VALUE_ACCESSOR多提供者形式注册见 checkbox.component.ts 与 checkbox-group.component.ts。这意味着它们不仅能配合模板表单的ngModel还能直接接入响应式表单Component({ imports: [ReactiveFormsModule, NzCheckboxModule], template: label nz-checkbox [formControl]formControl/label }) export class DemoComponent { formControl new FormControl(false); }组件通过writeValue()接收外部值、registerOnChange()注册变更回调、registerOnTouched()注册触摸回调。测试 checkbox.spec.ts 专门覆盖了响应式表单场景表单禁用时组件同步进入禁用态且禁用状态下点击不会改变FormControl的值。组件的内部联动机制单个nz-checkbox通过注入NZ_CHECKBOX_GROUP令牌定义于 tokens.ts感知自己是否处于 group 内group 内在构造函数中通过effect监听 group 的value信号若value.includes(this.nzValue)则自动同步选中态checkbox.component.ts点击上报用户点击后innerCheckedChange会调用checkboxGroupComponent.onCheckedChange(this.nzValue, checked)group 根据结果把nzValue追加或过滤出选中值数组checkbox-group.component.ts禁用合并finalDisabled由linkedSignal派生nz-checkbox的模板同时判断自身nzDisabled与 group 的finalDisabledcheckbox.component.ts。事件处理与变更检测优化组件对点击事件做了精细处理checkbox.component.tswrapper 上的点击事件通过fromEventOutsideAngular订阅在 Angular Zone 之外监听命中禁用态时直接preventDefault返回避免无意义的变更检测内部 input 的点击事件stopPropagation防止事件冒泡造成重复触发状态变化后通过ngZone.run()手动回到 Zone 内执行变更检测。测试 checkbox.spec.ts 验证了这些优化点击内部 input 不会触发ApplicationRef.tick()禁用态点击 wrapper 也不会触发变更检测从而保证高频交互下的性能。样式类与 RTL 支持组件渲染的 DOM 结构为ant-checkbox-wrapper ant-checkbox (ant-checkbox-input ant-checkbox-inner) 投影文本选中、禁用、半选分别对应ant-checkbox-checked、ant-checkbox-disabled、ant-checkbox-indeterminate样式类见 checkbox.spec.ts。同时两个组件都注入Directionality在 RTL 环境下自动添加ant-checkbox-rtl/ant-checkbox-group-rtl类样式文件位于 style/index.less。集成与使用前提NzCheckboxModule定义于 checkbox.module.ts导出NzCheckboxComponent与NzCheckboxGroupComponent已并入组件库的公开 API可通过 public-api.ts 从ng-zorro-antd/checkbox导入。由于组件依赖ngModel/formControl等表单能力使用时需同步引入FormsModule或ReactiveFormsModule。模块引入方式import { NgModule } from angular/core; import { FormsModule } from angular/forms; import { NzCheckboxModule } from ng-zorro-antd/checkbox; NgModule({ imports: [FormsModule, NzCheckboxModule] }) export class DemoModule {}小结单选label nz-checkbox [(ngModel)]checked即可获得完整选中语义nzIndeterminate专门用于半选样式常与「全选」联动多选nz-checkbox-group支持数据驱动nzOptions与投影布局ng-contentnzValue两种模式nzOptions支持字符串、数字、结构化对象三种形态表单两个组件均实现ControlValueAccessor可无缝对接ngModel与响应式表单禁用态由「属性禁用 表单禁用」合并控制原理group 通过NZ_CHECKBOX_GROUP注入令牌与信号联动实现值同步事件在 Zone 外监听并手动回 Zone 执行变更检测兼顾正确性与性能。以上内容均可在仓库源码与测试用例中得到验证读者可结合 components/checkbox 目录下的实现与 spec 文件继续深入。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐ng-zorro-antd Checkbox 组件完全指南API、源码原理与全选/半选实战ng zorro antd Checkbox 组件完全指南API、源码原理与全选/半选实战 ng zorro antd 是基于 Ant Design 设计体系UI组件前端如何利用Upptime实现智能故障检测全面监控策略指南如何利用Upptime实现智能故障检测全面监控策略指南 Upptime是一款由GitHub Actions、Issues和Pages驱动的开源正常运行时间监控UI组件前端Ant Design Checkbox 多选框组件完全指南API、Checkbox.Group、全选模式与源码原理剖析Ant Design Checkbox 多选框组件完全指南API、Checkbox.Group、全选模式与源码原理剖析 Checkbox多选框是 Ant前端UI组件设计系统上一篇Adele - 设计系统仓库项目推荐下一篇深度解析vis-three框架如何构建企业级3D场景编辑器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考