示例)
UI組件前端【免費下載鏈接】ng-zorro-antdAngular UI Component Library based on Ant Design項目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd點擊查看免費下載ng-zorro-antd 是 Angular 生態(tài)下基于 Ant Design 設(shè)計語言的 UI 組件庫其 Checkbox多選框組件用于在一組可選項中進行多項選擇或單獨使用表示兩種狀態(tài)之間的切換。本指南以官方文檔為核心結(jié)合倉庫源碼與測試用例系統(tǒng)講解nz-checkbox、nz-checkbox-group的完整 API、雙向綁定、禁用與半選indeterminate狀態(tài)、全選聯(lián)動以及表單集成的底層實現(xiàn)幫助你在真實項目中快速落地并理解其運行機制。何時使用 Checkbox根據(jù)官方文檔 components/checkbox/doc/index.zh-CN.mdCheckbox 適合在以下兩種場景中使用一組可選項中進行多項選擇例如權(quán)限配置、興趣標簽、多條件篩選用戶可同時勾選多個選項最終值與提交操作配合單獨使用表示兩種狀態(tài)之間的切換功能上與switch類似但兩者有本質(zhì)區(qū)別——切換switch會直接觸發(fā)狀態(tài)改變而checkbox一般用于狀態(tài)標記需要和提交操作配合使用即用戶勾選后仍需通過按鈕等操作提交。API 詳解[nz-checkbox] 單選 Checkboxnz-checkbox是一個屬性型選擇器selector 為[nz-checkbox]通常直接作用于label元素上聲明為exportAs: nzCheckbox。其完整輸入輸出參數(shù)如下參數(shù)說明類型默認值[nzId]組件內(nèi)部 input 的id值string-[nzName]組件內(nèi)部 input 的name值string-[nzAutoFocus]自動獲取焦點booleanfalse[nzDisabled]設(shè)定 disable 狀態(tài)booleanfalse[ngModel]指定當前是否選中可雙向綁定booleanfalse[nzIndeterminate]設(shè)置 indeterminate 狀態(tài)只負責(zé)樣式控制booleanfalse[nzValue]僅與nz-checkbox-wrapper即 group 內(nèi)部的選中回調(diào)配合使用any-(ngModelChange)選中變化時回調(diào)EventEmitterboolean-從源碼 checkbox.component.ts 可以看到nzAutoFocus、nzDisabled、nzIndeterminate、nzChecked均通過booleanAttribute變換函數(shù)接收輸入因此模板中可以簡寫為label nz-checkbox nzDisabled而不必顯式傳值。方法名稱描述focus()獲取焦點blur()移除焦點這兩個方法的底層實現(xiàn)見 checkbox.component.tsfocus()借助angular/cdk/a11y的FocusMonitor.focusVia(this.inputElement, keyboard)以鍵盤方式聚焦到內(nèi)部 inputblur()直接調(diào)用原生 input 的blur()。測試用例 checkbox.spec.ts 驗證了調(diào)用focus()后document.activeElement即為內(nèi)部 input調(diào)用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 展示了如何用外部按鈕控制勾選與禁用狀態(tài)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); } }禁用態(tài)官方 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 復(fù)選框組nz-checkbox-groupselector 為nz-checkbox-groupexportAs: nzCheckboxGroup用于管理一組同義選項的多選值。其參數(shù)如下參數(shù)說明類型默認值[ngModel]指定可選項可雙向綁定string[] \| number[][][nzName]CheckboxGroup 下所有 input 的name屬性string-[nzOptions]指定可選項string[] \| number[] \| NzCheckboxOption[][][nzDisabled]設(shè)定全部 checkbox disable 狀態(tài)booleanfalse(ngModelChange)選中數(shù)據(jù)變化時的回調(diào)EventEmitterstring[] \| number[]-從源碼 checkbox-group.component.ts 可以看到nzName、nzDisabled、nzOptions均以 Angular 信號signal形式聲明組件內(nèi)部通過linkedSignal實現(xiàn)finalDisabled確?！副韱慰丶谩古c「nzDisabled屬性禁用」二者合一。InterfacesNzCheckboxOptionnzOptions除了可以接收string[] | number[]的簡寫形式外還支持結(jié)構(gòu)化配置對象export interface NzCheckboxOption { label: string; value: string | number; disabled?: boolean; }該接口定義于 checkbox-group.component.ts。當傳入純字符串或數(shù)字數(shù)組時組件內(nèi)部的normalizeOptions()會將其規(guī)范化為{ label: value, value }形式見 checkbox-group.component.ts因此三種寫法等價// 寫法一純字符串數(shù)組 options [Apple, Pear, Orange]; // 寫法二純數(shù)字數(shù)組 options [1, 2, 3]; // 寫法三結(jié)構(gòu)化配置支持單獨禁用某一項 options: NzCheckboxOption[] [ { label: Apple, value: Apple }, { label: Pear, value: Pear }, { label: Orange, value: Orange, disabled: true } ];實戰(zhàn)示例復(fù)選框組基本用法官方 demo group.ts 展示了 group 的標準用法包括多組復(fù)用、結(jié)構(gòu)化禁用與整體禁用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 為對象數(shù)組、數(shù)字數(shù)組、字符串數(shù)組三種形態(tài)時均能正確渲染出對應(yīng) label 文本。全選與半選indeterminate聯(lián)動nzIndeterminate只負責(zé)樣式控制不參與選中語義這是實現(xiàn)「全選 / 半選」聯(lián)動的基礎(chǔ)。官方 demo check-all.ts 給出了完整實現(xiàn)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派生當已選數(shù)量等于選項總數(shù)時為全選indeterminate()當已選數(shù)量大于 0 且未全選時為真此時頂部 Checkbox 顯示為「橫杠」半選樣式點擊頂部 Checkbox 后onAllCheckedChange根據(jù)結(jié)果一次性設(shè)置全部或清空值。從源碼角度驗證在 checkbox.component.ts 的模板中ant-checkbox-checked樣式類僅在nzChecked !nzIndeterminate時生效ant-checkbox-indeterminate單獨由nzIndeterminate控制——這印證了「半選只控制樣式、不參與選中狀態(tài)」的設(shè)計。測試 checkbox.spec.ts 也驗證了設(shè)置為nzIndeterminate后 wrapper 會帶上ant-checkbox-indeterminate類。自定義布局在 group 中內(nèi)嵌任意子元素官方 demo layout.ts 展示了另一種高級用法nz-checkbox-group除了nzOptions數(shù)據(jù)驅(qū)動方式外還支持投影內(nèi)容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就是為這種場景設(shè)計的group 模板通過ng-content投影子元素見 checkbox-group.component.ts每個投影進來的nz-checkbox將nzValue上報給 groupgroup 據(jù)此維護選中值集合。測試 checkbox-group.spec.ts 驗證了點擊自定義布局中的復(fù)選框時group 的綁定值會正確增刪對應(yīng)nzValue。源碼級原理剖析雙向綁定與控制值訪問器CVAnz-checkbox與nz-checkbox-group都實現(xiàn)了ControlValueAccessor接口以NG_VALUE_ACCESSOR多提供者形式注冊見 checkbox.component.ts 與 checkbox-group.component.ts。這意味著它們不僅能配合模板表單的ngModel還能直接接入響應(yīng)式表單Component({ imports: [ReactiveFormsModule, NzCheckboxModule], template: label nz-checkbox [formControl]formControl/label }) export class DemoComponent { formControl new FormControl(false); }組件通過writeValue()接收外部值、registerOnChange()注冊變更回調(diào)、registerOnTouched()注冊觸摸回調(diào)。測試 checkbox.spec.ts 專門覆蓋了響應(yīng)式表單場景表單禁用時組件同步進入禁用態(tài)且禁用狀態(tài)下點擊不會改變FormControl的值。組件的內(nèi)部聯(lián)動機制單個nz-checkbox通過注入NZ_CHECKBOX_GROUP令牌定義于 tokens.ts感知自己是否處于 group 內(nèi)group 內(nèi)在構(gòu)造函數(shù)中通過effect監(jiān)聽 group 的value信號若value.includes(this.nzValue)則自動同步選中態(tài)checkbox.component.ts點擊上報用戶點擊后innerCheckedChange會調(diào)用checkboxGroupComponent.onCheckedChange(this.nzValue, checked)group 根據(jù)結(jié)果把nzValue追加或過濾出選中值數(shù)組checkbox-group.component.ts禁用合并finalDisabled由linkedSignal派生nz-checkbox的模板同時判斷自身nzDisabled與 group 的finalDisabledcheckbox.component.ts。事件處理與變更檢測優(yōu)化組件對點擊事件做了精細處理checkbox.component.tswrapper 上的點擊事件通過fromEventOutsideAngular訂閱在 Angular Zone 之外監(jiān)聽命中禁用態(tài)時直接preventDefault返回避免無意義的變更檢測內(nèi)部 input 的點擊事件stopPropagation防止事件冒泡造成重復(fù)觸發(fā)狀態(tài)變化后通過ngZone.run()手動回到 Zone 內(nèi)執(zhí)行變更檢測。測試 checkbox.spec.ts 驗證了這些優(yōu)化點擊內(nèi)部 input 不會觸發(fā)ApplicationRef.tick()禁用態(tài)點擊 wrapper 也不會觸發(fā)變更檢測從而保證高頻交互下的性能。樣式類與 RTL 支持組件渲染的 DOM 結(jié)構(gòu)為ant-checkbox-wrapper ant-checkbox (ant-checkbox-input ant-checkbox-inner) 投影文本選中、禁用、半選分別對應(yīng)ant-checkbox-checked、ant-checkbox-disabled、ant-checkbox-indeterminate樣式類見 checkbox.spec.ts。同時兩個組件都注入Directionality在 RTL 環(huán)境下自動添加ant-checkbox-rtl/ant-checkbox-group-rtl類樣式文件位于 style/index.less。集成與使用前提NzCheckboxModule定義于 checkbox.module.ts導(dǎo)出NzCheckboxComponent與NzCheckboxGroupComponent已并入組件庫的公開 API可通過 public-api.ts 從ng-zorro-antd/checkbox導(dǎo)入。由于組件依賴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 {}小結(jié)單選label nz-checkbox [(ngModel)]checked即可獲得完整選中語義nzIndeterminate專門用于半選樣式常與「全選」聯(lián)動多選nz-checkbox-group支持數(shù)據(jù)驅(qū)動nzOptions與投影布局ng-contentnzValue兩種模式nzOptions支持字符串、數(shù)字、結(jié)構(gòu)化對象三種形態(tài)表單兩個組件均實現(xiàn)ControlValueAccessor可無縫對接ngModel與響應(yīng)式表單禁用態(tài)由「屬性禁用 表單禁用」合并控制原理group 通過NZ_CHECKBOX_GROUP注入令牌與信號聯(lián)動實現(xiàn)值同步事件在 Zone 外監(jiān)聽并手動回 Zone 執(zhí)行變更檢測兼顧正確性與性能。以上內(nèi)容均可在倉庫源碼與測試用例中得到驗證讀者可結(jié)合 components/checkbox 目錄下的實現(xiàn)與 spec 文件繼續(xù)深入。贊分享UI組件前端【免費下載鏈接】ng-zorro-antdAngular UI Component Library based on Ant Design項目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd點擊查看免費下載相關(guān)推薦ng-zorro-antd Checkbox 組件完全指南API、源碼原理與全選/半選實戰(zhàn)ng zorro antd Checkbox 組件完全指南API、源碼原理與全選/半選實戰(zhàn) ng zorro antd 是基于 Ant Design 設(shè)計體系UI組件前端如何利用Upptime實現(xiàn)智能故障檢測全面監(jiān)控策略指南如何利用Upptime實現(xiàn)智能故障檢測全面監(jiān)控策略指南 Upptime是一款由GitHub Actions、Issues和Pages驅(qū)動的開源正常運行時間監(jiān)控UI組件前端Ant Design Checkbox 多選框組件完全指南API、Checkbox.Group、全選模式與源碼原理剖析Ant Design Checkbox 多選框組件完全指南API、Checkbox.Group、全選模式與源碼原理剖析 Checkbox多選框是 Ant前端UI組件設(shè)計系統(tǒng)上一篇Adele - 設(shè)計系統(tǒng)倉庫項目推薦下一篇深度解析vis-three框架如何構(gòu)建企業(yè)級3D場景編輯器創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 ng-zorro-antd Checkbox 多選框組件完全指南：API 詳解、源碼原理與實戰(zhàn)示例
UI組件前端【免費下載鏈接】ng-zorro-antdAngular UI Component Library based on Ant Design項目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd點擊查看免費下載ng-zorro-antd 是 Angular 生態(tài)下基于 Ant Design 設(shè)計語言的 UI 組件庫其 Checkbox多選框組件用于在一組可選項中進行多項選擇或單獨使用表示兩種狀態(tài)之間的切換。本指南以官方文檔為核心結(jié)合倉庫源碼與測試用例系統(tǒng)講解nz-checkbox、nz-checkbox-group的完整 API、雙向綁定、禁用與半選indeterminate狀態(tài)、全選聯(lián)動以及表單集成的底層實現(xiàn)幫助你在真實項目中快速落地并理解其運行機制。何時使用 Checkbox根據(jù)官方文檔 components/checkbox/doc/index.zh-CN.mdCheckbox 適合在以下兩種場景中使用一組可選項中進行多項選擇例如權(quán)限配置、興趣標簽、多條件篩選用戶可同時勾選多個選項最終值與提交操作配合單獨使用表示兩種狀態(tài)之間的切換功能上與switch類似但兩者有本質(zhì)區(qū)別——切換switch會直接觸發(fā)狀態(tài)改變而checkbox一般用于狀態(tài)標記需要和提交操作配合使用即用戶勾選后仍需通過按鈕等操作提交。API 詳解[nz-checkbox] 單選 Checkboxnz-checkbox是一個屬性型選擇器selector 為[nz-checkbox]通常直接作用于label元素上聲明為exportAs: nzCheckbox。其完整輸入輸出參數(shù)如下參數(shù)說明類型默認值[nzId]組件內(nèi)部 input 的id值string-[nzName]組件內(nèi)部 input 的name值string-[nzAutoFocus]自動獲取焦點booleanfalse[nzDisabled]設(shè)定 disable 狀態(tài)booleanfalse[ngModel]指定當前是否選中可雙向綁定booleanfalse[nzIndeterminate]設(shè)置 indeterminate 狀態(tài)只負責(zé)樣式控制booleanfalse[nzValue]僅與nz-checkbox-wrapper即 group 內(nèi)部的選中回調(diào)配合使用any-(ngModelChange)選中變化時回調(diào)EventEmitterboolean-從源碼 checkbox.component.ts 可以看到nzAutoFocus、nzDisabled、nzIndeterminate、nzChecked均通過booleanAttribute變換函數(shù)接收輸入因此模板中可以簡寫為label nz-checkbox nzDisabled而不必顯式傳值。方法名稱描述focus()獲取焦點blur()移除焦點這兩個方法的底層實現(xiàn)見 checkbox.component.tsfocus()借助angular/cdk/a11y的FocusMonitor.focusVia(this.inputElement, keyboard)以鍵盤方式聚焦到內(nèi)部 inputblur()直接調(diào)用原生 input 的blur()。測試用例 checkbox.spec.ts 驗證了調(diào)用focus()后document.activeElement即為內(nèi)部 input調(diào)用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 展示了如何用外部按鈕控制勾選與禁用狀態(tài)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); } }禁用態(tài)官方 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 復(fù)選框組nz-checkbox-groupselector 為nz-checkbox-groupexportAs: nzCheckboxGroup用于管理一組同義選項的多選值。其參數(shù)如下參數(shù)說明類型默認值[ngModel]指定可選項可雙向綁定string[] \| number[][][nzName]CheckboxGroup 下所有 input 的name屬性string-[nzOptions]指定可選項string[] \| number[] \| NzCheckboxOption[][][nzDisabled]設(shè)定全部 checkbox disable 狀態(tài)booleanfalse(ngModelChange)選中數(shù)據(jù)變化時的回調(diào)EventEmitterstring[] \| number[]-從源碼 checkbox-group.component.ts 可以看到nzName、nzDisabled、nzOptions均以 Angular 信號signal形式聲明組件內(nèi)部通過linkedSignal實現(xiàn)finalDisabled確?！副韱慰丶谩古c「nzDisabled屬性禁用」二者合一。InterfacesNzCheckboxOptionnzOptions除了可以接收string[] | number[]的簡寫形式外還支持結(jié)構(gòu)化配置對象export interface NzCheckboxOption { label: string; value: string | number; disabled?: boolean; }該接口定義于 checkbox-group.component.ts。當傳入純字符串或數(shù)字數(shù)組時組件內(nèi)部的normalizeOptions()會將其規(guī)范化為{ label: value, value }形式見 checkbox-group.component.ts因此三種寫法等價// 寫法一純字符串數(shù)組 options [Apple, Pear, Orange]; // 寫法二純數(shù)字數(shù)組 options [1, 2, 3]; // 寫法三結(jié)構(gòu)化配置支持單獨禁用某一項 options: NzCheckboxOption[] [ { label: Apple, value: Apple }, { label: Pear, value: Pear }, { label: Orange, value: Orange, disabled: true } ];實戰(zhàn)示例復(fù)選框組基本用法官方 demo group.ts 展示了 group 的標準用法包括多組復(fù)用、結(jié)構(gòu)化禁用與整體禁用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 為對象數(shù)組、數(shù)字數(shù)組、字符串數(shù)組三種形態(tài)時均能正確渲染出對應(yīng) label 文本。全選與半選indeterminate聯(lián)動nzIndeterminate只負責(zé)樣式控制不參與選中語義這是實現(xiàn)「全選 / 半選」聯(lián)動的基礎(chǔ)。官方 demo check-all.ts 給出了完整實現(xiàn)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派生當已選數(shù)量等于選項總數(shù)時為全選indeterminate()當已選數(shù)量大于 0 且未全選時為真此時頂部 Checkbox 顯示為「橫杠」半選樣式點擊頂部 Checkbox 后onAllCheckedChange根據(jù)結(jié)果一次性設(shè)置全部或清空值。從源碼角度驗證在 checkbox.component.ts 的模板中ant-checkbox-checked樣式類僅在nzChecked !nzIndeterminate時生效ant-checkbox-indeterminate單獨由nzIndeterminate控制——這印證了「半選只控制樣式、不參與選中狀態(tài)」的設(shè)計。測試 checkbox.spec.ts 也驗證了設(shè)置為nzIndeterminate后 wrapper 會帶上ant-checkbox-indeterminate類。自定義布局在 group 中內(nèi)嵌任意子元素官方 demo layout.ts 展示了另一種高級用法nz-checkbox-group除了nzOptions數(shù)據(jù)驅(qū)動方式外還支持投影內(nèi)容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就是為這種場景設(shè)計的group 模板通過ng-content投影子元素見 checkbox-group.component.ts每個投影進來的nz-checkbox將nzValue上報給 groupgroup 據(jù)此維護選中值集合。測試 checkbox-group.spec.ts 驗證了點擊自定義布局中的復(fù)選框時group 的綁定值會正確增刪對應(yīng)nzValue。源碼級原理剖析雙向綁定與控制值訪問器CVAnz-checkbox與nz-checkbox-group都實現(xiàn)了ControlValueAccessor接口以NG_VALUE_ACCESSOR多提供者形式注冊見 checkbox.component.ts 與 checkbox-group.component.ts。這意味著它們不僅能配合模板表單的ngModel還能直接接入響應(yīng)式表單Component({ imports: [ReactiveFormsModule, NzCheckboxModule], template: label nz-checkbox [formControl]formControl/label }) export class DemoComponent { formControl new FormControl(false); }組件通過writeValue()接收外部值、registerOnChange()注冊變更回調(diào)、registerOnTouched()注冊觸摸回調(diào)。測試 checkbox.spec.ts 專門覆蓋了響應(yīng)式表單場景表單禁用時組件同步進入禁用態(tài)且禁用狀態(tài)下點擊不會改變FormControl的值。組件的內(nèi)部聯(lián)動機制單個nz-checkbox通過注入NZ_CHECKBOX_GROUP令牌定義于 tokens.ts感知自己是否處于 group 內(nèi)group 內(nèi)在構(gòu)造函數(shù)中通過effect監(jiān)聽 group 的value信號若value.includes(this.nzValue)則自動同步選中態(tài)checkbox.component.ts點擊上報用戶點擊后innerCheckedChange會調(diào)用checkboxGroupComponent.onCheckedChange(this.nzValue, checked)group 根據(jù)結(jié)果把nzValue追加或過濾出選中值數(shù)組checkbox-group.component.ts禁用合并finalDisabled由linkedSignal派生nz-checkbox的模板同時判斷自身nzDisabled與 group 的finalDisabledcheckbox.component.ts。事件處理與變更檢測優(yōu)化組件對點擊事件做了精細處理checkbox.component.tswrapper 上的點擊事件通過fromEventOutsideAngular訂閱在 Angular Zone 之外監(jiān)聽命中禁用態(tài)時直接preventDefault返回避免無意義的變更檢測內(nèi)部 input 的點擊事件stopPropagation防止事件冒泡造成重復(fù)觸發(fā)狀態(tài)變化后通過ngZone.run()手動回到 Zone 內(nèi)執(zhí)行變更檢測。測試 checkbox.spec.ts 驗證了這些優(yōu)化點擊內(nèi)部 input 不會觸發(fā)ApplicationRef.tick()禁用態(tài)點擊 wrapper 也不會觸發(fā)變更檢測從而保證高頻交互下的性能。樣式類與 RTL 支持組件渲染的 DOM 結(jié)構(gòu)為ant-checkbox-wrapper ant-checkbox (ant-checkbox-input ant-checkbox-inner) 投影文本選中、禁用、半選分別對應(yīng)ant-checkbox-checked、ant-checkbox-disabled、ant-checkbox-indeterminate樣式類見 checkbox.spec.ts。同時兩個組件都注入Directionality在 RTL 環(huán)境下自動添加ant-checkbox-rtl/ant-checkbox-group-rtl類樣式文件位于 style/index.less。集成與使用前提NzCheckboxModule定義于 checkbox.module.ts導(dǎo)出NzCheckboxComponent與NzCheckboxGroupComponent已并入組件庫的公開 API可通過 public-api.ts 從ng-zorro-antd/checkbox導(dǎo)入。由于組件依賴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 {}小結(jié)單選label nz-checkbox [(ngModel)]checked即可獲得完整選中語義nzIndeterminate專門用于半選樣式常與「全選」聯(lián)動多選nz-checkbox-group支持數(shù)據(jù)驅(qū)動nzOptions與投影布局ng-contentnzValue兩種模式nzOptions支持字符串、數(shù)字、結(jié)構(gòu)化對象三種形態(tài)表單兩個組件均實現(xiàn)ControlValueAccessor可無縫對接ngModel與響應(yīng)式表單禁用態(tài)由「屬性禁用 表單禁用」合并控制原理group 通過NZ_CHECKBOX_GROUP注入令牌與信號聯(lián)動實現(xiàn)值同步事件在 Zone 外監(jiān)聽并手動回 Zone 執(zhí)行變更檢測兼顧正確性與性能。以上內(nèi)容均可在倉庫源碼與測試用例中得到驗證讀者可結(jié)合 components/checkbox 目錄下的實現(xiàn)與 spec 文件繼續(xù)深入。贊分享UI組件前端【免費下載鏈接】ng-zorro-antdAngular UI Component Library based on Ant Design項目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd點擊查看免費下載相關(guān)推薦ng-zorro-antd Checkbox 組件完全指南API、源碼原理與全選/半選實戰(zhàn)ng zorro antd Checkbox 組件完全指南API、源碼原理與全選/半選實戰(zhàn) ng zorro antd 是基于 Ant Design 設(shè)計體系UI組件前端如何利用Upptime實現(xiàn)智能故障檢測全面監(jiān)控策略指南如何利用Upptime實現(xiàn)智能故障檢測全面監(jiān)控策略指南 Upptime是一款由GitHub Actions、Issues和Pages驅(qū)動的開源正常運行時間監(jiān)控UI組件前端Ant Design Checkbox 多選框組件完全指南API、Checkbox.Group、全選模式與源碼原理剖析Ant Design Checkbox 多選框組件完全指南API、Checkbox.Group、全選模式與源碼原理剖析 Checkbox多選框是 Ant前端UI組件設(shè)計系統(tǒng)上一篇Adele - 設(shè)計系統(tǒng)倉庫項目推薦下一篇深度解析vis-three框架如何構(gòu)建企業(yè)級3D場景編輯器創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考