ng-zorro-antd Checkbox 禁用机制解析：nzDisabled、表单联动与 CSS 降级实现

UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载本文以 ng-zorro-antd 中 Checkbox 组件的不可用Disabled示例为入口讲解如何禁用单个 checkbox 与 checkbox 组、禁用态在模板类绑定与事件拦截中的具体实现、与FormControl禁用状态的联动逻辑以及mixin.less中禁用样式的设计。读完后你能掌握在表单场景中控制多选框交互权限的完整方案并能从源码层面解释禁用后点击为什么不生效。官方示例两个禁用状态的 checkbox官方演示 disabled.md 的主题只有一句话——checkbox 不可用。对应的演示组件 disabled.ts 展示了禁用态的两种视觉形态未选中禁用与已选中禁用import { Component } from angular/core; import { FormsModule } from angular/forms; import { NzCheckboxModule } from ng-zorro-antd/checkbox; 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 {}这个示例有两个要点nzDisabled是静态布尔属性直接书写即为true该输入使用了booleanAttribute转换见 checkbox.component.ts 中Input({ transform: booleanAttribute }) nzDisabled false;不需要值绑定两个 checkbox 分别用[ngModel]false和[ngModel]true锁定在未选中和已选中两种值上目的是让使用者确认禁用态只拦截交互不改变选中值——已选中的禁用 checkbox 依然呈现勾选外观。API 文档 doc/index.zh-CN.md 对nzDisabled的定义是设定 disable 状态类型为boolean默认值false。源码视角禁用如何拦截交互禁用并不是简单地加一个 CSS 类。在 checkbox.component.ts 中nzDisabled至少参与了三处控制模板类绑定视觉降级组件模板中内层span根据nzDisabled或所属 checkbox 组的禁用状态叠加ant-checkbox-disabled类真正的input typecheckbox同时绑定原生disabled属性span classant-checkbox [class.ant-checkbox-disabled]nzDisabled || checkboxGroupComponent?.finalDisabled() input typecheckbox classant-checkbox-input [disabled]nzDisabled || (checkboxGroupComponent?.finalDisabled() ?? false) / span classant-checkbox-inner/span /span见 checkbox.component.ts外层宿主元素则叠加ant-checkbox-wrapper-disabled类用于控制 label 文字颜色见同文件 host 配置。注意这里的判断是nzDisabled || 组级 finalDisabled即单个 checkbox 的禁用是自身属性与所在组禁用状态的逻辑或。事件层面两道拦截第一道在点击处理器中。组件构造时对宿主元素注册了 click 监听见 ngOnInitfromEventOutsideAngular(this.elementRef.nativeElement, click) .pipe(takeUntilDestroyed(this.destroyRef)) .subscribe(event { event.preventDefault(); this.focus(); if (this.nzDisabled) { return; } this.ngZone.run(() { this.innerCheckedChange(!this.nzChecked); this.cdr.markForCheck(); }); });点击被禁用 checkbox 时事件先preventDefault()再直接return不进入 NgZone、不触发任何变更检测。单测 checkbox.spec.ts 专门验证了这一点当nzDisabled为true时模拟点击断言ApplicationRef.tick未被调用且preventDefault被调用——禁用不仅看起来不能点也确实不产生任何 Angular 运行时开销。第二道在值变更入口innerCheckedChangecheckbox.component.tsinnerCheckedChange(checked: boolean): void { if (!this.nzDisabled !this.checkboxGroupComponent?.finalDisabled()) { this.setValue(checked); this.checkboxGroupComponent?.onCheckedChange(this.nzValue, checked); } }即所有经ngModelChange等途径到达的值变更都会先检查自身与所在组的禁用状态任一为真则丢弃。对应的功能断言见 checkbox.spec.ts 的 should disabled work设置disabled信号为true后点击checked信号、ant-checkbox-checked类与ngModelChange回调均保持不动。表单层面setDisabledState 的合并语义NzCheckboxComponent实现了ControlValueAccessor其中setDisabledState的逻辑值得注意checkbox.component.tssetDisabledState(disabled: boolean): void { this.nzDisabled (this.isNzDisableFirstChange this.nzDisabled) || disabled; this.isNzDisableFirstChange false; this.cdr.markForCheck(); }isNzDisableFirstChange标志位使首次调用时模板上已有的nzDisabled与表单控制器的禁用状态做或运算合并此后表单侧的enable()/disable()直接驱动组件禁用状态。这意味着在响应式表单中formControl.disable()会让即使未写nzDisabled的 checkbox 也进入禁用态。checkbox.spec.ts 的 form 用例 验证了完整闭环formControl.disable()后宿主出现ant-checkbox-disabled类、原生input.disabled为true、点击不改变formControl.value再enable()后点击可正常写入true。组合场景nz-checkbox-group 的组级禁用当 checkbox 处于nz-checkbox-group内时禁用判断多了一个来源——组的finalDisabled信号。在 checkbox-group.component.ts 中readonly finalDisabled linkedSignal(() this.nzDisabled());linkedSignal的用途在于它初始跟随输入信号nzDisabled()但之后可以被setDisabledState独立改写——组组件同样实现了ControlValueAccessor其 setDisabledState 也采用与单个组件一致的首次合并策略setDisabledState(disabled: boolean): void { untracked(() { this.finalDisabled.set((this.isDisabledFirstChange this.nzDisabled()) || disabled); }); this.isDisabledFirstChange false; }组级禁用向下传导有两条路径模板绑定组内部由nzOptions生成的每个子 checkbox其[nzDisabled]绑定为option.disabled || finalDisabled()checkbox-group.component.ts即选项自身禁用或整组禁用任一成立即禁用事件守卫子组件的innerCheckedChange与组组件的onCheckedChange都会先检查finalDisabled()为真时直接返回ngModel数组不会被增删checkbox-group.component.ts。组组件还提供选项级禁用NzCheckboxOption接口checkbox-group.component.ts带有可选的disabled?: boolean字段允许在整组可用时禁用其中某一项export interface NzCheckboxOption { label: string; value: string | number; disabled?: boolean; }checkbox-group.spec.ts 验证了组级与表单级两条禁用路径都会给每个选项元素加上ant-checkbox-wrapper-disabled类自定义布局在nz-checkbox-group内手写label nz-checkbox下同样生效自定义布局用例。样式层面ant-checkbox-disabled 的降级规则禁用外观由 style/mixin.less 的ant-checkbox-disabled规则块定义核心内容整个 wrapper 与内部 input 均为cursor: not-allowedinput 额外设置pointer-events: none原生层面阻止命中内框背景换为禁用底色input-disabled-bg边框用border-color-base !important覆盖选中高亮色对勾动画被animation-name: none关闭已选中项的对勾边框改用disabled-colorlabel 文字 span置灰为disabled-color:hover外发光边框通过visibility: hidden隐藏禁用项不显示悬停高亮。这些类名与前文源码中绑定的类一一对应ant-checkbox-disabled内层框、ant-checkbox-wrapper-disabled宿主 wrapper。由于组件使用ViewEncapsulation.None样式通过:global前缀生效这也解释了为什么测试可以直接断言firstElementChild.classList上的类名。实战动态切换禁用状态如果禁用状态需要随业务逻辑动态变化官方 controller 示例 给出了信号驱动的写法readonly checked signal(true); readonly disabled signal(false); toggleDisabled(): void { this.disabled.update(disabled !disabled); }label nz-checkbox [(ngModel)]checked [nzDisabled]disabled() {{ checked() ? Checked : Unchecked }} - {{ disabled() ? Disabled : Enabled }} /label button nz-button nzTypeprimary (click)toggleDisabled() {{ disabled() ? Enable : Disable }} /button在响应式表单中则直接调用formControl.disable()/formControl.enable()由前文的setDisabledState链路同步到组件无需手动维护布尔属性。小结ng-zorro-antd 的 checkbox 禁用机制由四层协作完成层面位置作用输入属性nzDisabledbooleanAttribute转换声明式禁用写属性即为true模板绑定checkbox.component.ts叠加ant-checkbox-*类、置位原生input[disabled]事件守卫innerCheckedChange/onCheckedChange的finalDisabled()检查丢弃一切禁用态下的值变更表单联动setDisabledState的首次合并语义FormControl.disable()自动传导到组件组级禁用通过finalDisabledlinkedSignal 与选项级NzCheckboxOption.disabled叠加CSS 层再以pointer-events: none、cursor: not-allowed与去动画化完成视觉降级。以上行为均有单测背书checkbox.spec.ts、checkbox-group.spec.ts可作为集成验证时的参照断言。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐ng-zorro-antd DatePicker 禁用状态实战nzDisabled、nzDisabledDate 与 nzDisabledTime 全解析ng zorro antd DatePicker 禁用状态实战nzDisabled、nzDisabledDate 与 nzDisabledTime 全解析 本UI组件前端Ghost 浏览器端到端测试编写与运行全指南E2E 工作区规范、Page Object 模式与基础设施实操Ghost 浏览器端到端测试编写与运行全指南E2E 工作区规范、Page Object 模式与基础设施实操 本文基于 Ghost monorepo 中 e2eUI组件前端强力解析Yarn Spinner如何革新游戏对话系统开发强力解析Yarn Spinner如何革新游戏对话系统开发 在游戏叙事开发领域Yarn Spinner作为一款开源对话系统工具正在彻底改变创作者与技术开发者UI组件前端上一篇Instatic界面定制CSS变量与主题切换完全指南下一篇解决ImmersionBar内存泄漏从原理到实战修复方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考