UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载导读本文聚焦 ng-zorro-antd 的nz-tag组件在nzModecheckable模式下的完整用法。该模式可以让一个普通的标签Tag像 Checkbox 一样支持点击切换选中状态常用于筛选条件、多选标签集合、状态标记等交互场景。读完本文你将掌握 checkable 模式的模板写法、双向绑定与事件监听方式并通过阅读 tag.component.ts 源码理解其底层实现机制与样式原理。一、原文档要点一行代码让 Tag 变成 Checkbox在 checkable.md 中官方文档给出的核心说明非常精炼中文描述可通过nzModecheckable实现类似 Checkbox 的效果点击切换选中效果。英文描述nzModecheckableworks like Checkbox, click it to toggle checked state.也就是说checkable 是nz-tag的三种模式之一。完整的nzMode取值域为default | closeable | checkable见 tag.component.ts 中Input() nzMode的类型定义默认值为default。三种模式各自承担不同职责模式行为典型场景default纯展示标签无交互行为静态分类标签、只读状态标识closeable右侧出现关闭图标点击后移除标签可删除的动态标签列表checkable点击切换选中/未选中状态样式随选中态变化多选筛选、可勾选标签组二、最小可运行示例checkable 的标准写法仓库配套示例位于 components/tag/demo/checkable.ts展示了最基础的用法import { Component } from angular/core; import { NzTagModule } from ng-zorro-antd/tag; Component({ selector: nz-demo-tag-checkable, imports: [NzTagModule], template: nz-tag nzModecheckable [nzChecked]true (nzCheckedChange)checkChange($event)Tag1/nz-tag nz-tag nzModecheckable [nzChecked]true (nzCheckedChange)checkChange($event)Tag2/nz-tag nz-tag nzModecheckable [nzChecked]true (nzCheckedChange)checkChange($event)Tag3/nz-tag }) export class NzDemoTagCheckableComponent { checkChange(e: boolean): void { console.log(e); } }这段示例体现了 checkable 模式三个核心输入输出nzModecheckable—— 开启可选择模式是进入本模式的唯一开关[nzChecked]true—— 初始化选中状态为 true即标签初始即处于已选中的视觉状态(nzCheckedChange)checkChange($event)—— 每次点击切换后事件回调会收到一个boolean类型的当前选中值。使用前请确保在你的模块或组件中导入NzTagModule见 tag.module.ts 与 public-api.ts。在 Angular 独立组件standalone模式下直接在组件imports中引入NzTagModule即可如上示例所示。三、核心 API 详解nzChecked 与 nzCheckedChangecheckable 模式涉及两个关键成员均定义在 tag.component.ts 中Input({ transform: booleanAttribute }) nzChecked false; Output() readonly nzCheckedChange new EventEmitterboolean();3.1 nzChecked可控的选中状态类型boolean通过 Angular 的booleanAttribute转换因此模板中可直接写nzChecked无值即为 true也可以写[nzChecked]true或[nzChecked]isChecked绑定组件字段。默认值false即默认未选中。语义它既是初始选中状态也是组件内部维护的当前选中状态。点击切换时组件会直接改写这个内部值详见下文源码原理。3.2 nzCheckedChange选中状态变化事件类型EventEmitterboolean。触发时机仅在 checkable 模式下、用户点击标签切换状态时触发每次点击触发一次回调参数为切换后的布尔值。典型用途把选中结果同步到业务状态中例如记录哪些标签被选中。3.3 双向绑定Banana in a Box写法组件官方测试用例tag.spec.ts使用了双向绑定语法nz-tag [nzMode]mode() [(nzChecked)]checked (nzCheckedChange)checkedChange($event) Tag 1 /nz-tag由于nzChecked与nzCheckedChange符合 Angular 的双向绑定命名约定xxx/xxxChange[(nzChecked)]可以直接使用省去手动同步状态的手写逻辑是最推荐的生产写法。四、源码原理点击后发生了什么checkable 模式的全部交互逻辑都集中在 tag.component.ts 的updateCheckedStatus()方法中updateCheckedStatus(): void { if (this.nzMode checkable) { this.nzChecked !this.nzChecked; this.nzCheckedChange.emit(this.nzChecked); } }对应的模板与宿主绑定[class.ant-tag-checkable]: nzMode checkable, [class.ant-tag-checkable-checked]: nzChecked, (click): updateCheckedStatus()整个交互链路可以拆解为三步点击触发组件的宿主元素绑定了(click)事件任意位置点击nz-tag都会调用updateCheckedStatus()模式守卫方法内部首先判断nzMode checkable只有 checkable 模式下才会取反nzChecked并发出nzCheckedChange事件。这意味着即使误点了 default 或 closeable 模式的标签也不会触发任何选中状态变化状态生效nzChecked变化后宿主绑定[class.ant-tag-checkable-checked]会随之更新标签的视觉选中样式立即生效。值得注意的是取反逻辑是立即、同步的没有防抖、没有动画干预点击一次状态就翻转一次与原生 Checkbox 的即时响应体验一致。五、样式原理ant-tag-checkable 与 ant-tag-checkable-checked选中状态的视觉反馈完全由 CSS 类驱动。相关样式定义在 components/tag/style/index.less-checkable { background-color: transparent; border-color: transparent; cursor: pointer; :not(-checked):hover { color: primary-color; } :active, -checked { color: text-color-inverse; } -checked { background-color: primary-6; } :active { background-color: primary-7; } }从样式代码可以总结出 checkable 标签的视觉行为未选中态背景透明、边框透明看起来像一段纯文字但cursor: pointer明确暗示其可点击性悬停态文字颜色变为主题色primary-color给出可交互的视觉提示选中态ant-tag-checkable-checked背景填充为主题色primary-6文字反白text-color-inverse与选中后的 Checkbox 语义一致按下态:active背景加深为primary-7提供按压反馈。也就是说nzModecheckable负责添加ant-tag-checkable类基础可点击样式而nzChecked为 true 时额外添加ant-tag-checkable-checked类选中填充样式两者组合构成了完整的 checkable 视觉体系。六、测试验证组件行为如何被保障checkable 的交互行为在单元测试中有完整覆盖见 tag.spec.ts 的should checkable work用例it(should checkable work, () { fixture.detectChanges(); expect(tag.nativeElement.classList).not.toContain(ant-tag-checkable); testComponent.mode.set(checkable); fixture.detectChanges(); expect(testComponent.checked()).toBe(false); expect(testComponent.checkedChange).toHaveBeenCalledTimes(0); expect(tag.nativeElement.classList).toContain(ant-tag-checkable); expect(tag.nativeElement.classList).not.toContain(ant-tag-checkable-checked); tag.nativeElement.click(); fixture.detectChanges(); expect(testComponent.checked()).toBe(true); expect(testComponent.checkedChange).toHaveBeenCalledTimes(1); expect(tag.nativeElement.classList).toContain(ant-tag-checkable-checked); });该测试逐条印证了前文分析的结论默认模式下标签不带ant-tag-checkable类切换为 checkable 模式后立即出现ant-tag-checkable类初始checked为 false且尚未触发任何checkedChange事件模拟一次原生click()后checked翻转为 true、checkedChange恰好触发一次、ant-tag-checkable-checked类出现。这与源码中updateCheckedStatus()的先取反、再 emit逻辑完全对应也从测试层面确认了事件只会在 checkable 模式下发出。七、进阶组合checkable 与其他 Tag 能力的搭配checkable 模式并非孤立功能它可以与nz-tag的其他输入自由组合使交互更丰富与nzColor组合给 checkable 标签指定预设色或自定义色NzTagColor类型见 typings.ts例如nz-tag nzModecheckable nzColorblue选中填充仍以主题色为主但未选中态可呈现彩色文字与nzBordered组合[nzBordered]false可去掉边框配合 checkable 更接近纯文本按钮风格默认nzBordered true见 tag.component.ts与 closeable 的区分checkable 和 closeable 是互斥的两种模式不可同时生效。需要可勾选 可删除时可在外层循环中分别渲染两类标签参考 control.ts 中按条件切换nzMode的写法。八、最佳实践小结开箱即用nzModecheckable一行即可获得 Checkbox 式交互无需引入额外组件优先双向绑定需要维护选中集合时用[(nzChecked)]state替代手写事件回调避免状态漂移事件只读、状态驱动nzCheckedChange只用于同步外部业务状态不要试图在回调里再次改写nzChecked组件内部已在 emit 前完成取反注意模式守卫事件仅在 checkable 模式下触发业务代码无需自行判断模式样式可预期选中/悬停/按下三态均由主题变量primary-color、primary-6、primary-7驱动跟随主题切换自动适配。结合 checkable.ts 示例、tag.component.ts 源码与 tag.spec.ts 测试你已经可以放心地在项目中落地 checkable 标签并能向他人讲清楚它的实现原理。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐ng-zorro-antd Slider 反向模式nzReverse实战指南从 Demo 到源码原理ng zorro antd Slider 反向模式nzReverse实战指南从 Demo 到源码原理 导读 在基于 Ant Design 的 AngulaUI组件前端ng-zorro-antd DatePicker 实战用 [nzMode] 动态切换 Date / Week / Month / Quarter / Year 选择器ng zorro antd DatePicker 实战用 nzMode 动态切换 Date / Week / Month / Quarter / Year 选UI组件前端ng-zorro-antd 日期范围选择器实战nzMode 六种粒度、双面板选择与源码细节ng zorro antd 日期范围选择器实战nzMode 六种粒度、双面板选择与源码细节 本文以 范围选择器示例 https://link.gitcode.UI组件前端上一篇MoocDownloader终极指南5分钟掌握.NET实现的MOOC课程离线下载技术下一篇如何自动生成并排名提示词gpt-prompt-engineer 完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/29 5:55:28 · 阅读 1.2k ng-zorro-antd Tag 可选择模式（Checkable）实战指南：从 nzMode 用法到源码原理
UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载导读本文聚焦 ng-zorro-antd 的nz-tag组件在nzModecheckable模式下的完整用法。该模式可以让一个普通的标签Tag像 Checkbox 一样支持点击切换选中状态常用于筛选条件、多选标签集合、状态标记等交互场景。读完本文你将掌握 checkable 模式的模板写法、双向绑定与事件监听方式并通过阅读 tag.component.ts 源码理解其底层实现机制与样式原理。一、原文档要点一行代码让 Tag 变成 Checkbox在 checkable.md 中官方文档给出的核心说明非常精炼中文描述可通过nzModecheckable实现类似 Checkbox 的效果点击切换选中效果。英文描述nzModecheckableworks like Checkbox, click it to toggle checked state.也就是说checkable 是nz-tag的三种模式之一。完整的nzMode取值域为default | closeable | checkable见 tag.component.ts 中Input() nzMode的类型定义默认值为default。三种模式各自承担不同职责模式行为典型场景default纯展示标签无交互行为静态分类标签、只读状态标识closeable右侧出现关闭图标点击后移除标签可删除的动态标签列表checkable点击切换选中/未选中状态样式随选中态变化多选筛选、可勾选标签组二、最小可运行示例checkable 的标准写法仓库配套示例位于 components/tag/demo/checkable.ts展示了最基础的用法import { Component } from angular/core; import { NzTagModule } from ng-zorro-antd/tag; Component({ selector: nz-demo-tag-checkable, imports: [NzTagModule], template: nz-tag nzModecheckable [nzChecked]true (nzCheckedChange)checkChange($event)Tag1/nz-tag nz-tag nzModecheckable [nzChecked]true (nzCheckedChange)checkChange($event)Tag2/nz-tag nz-tag nzModecheckable [nzChecked]true (nzCheckedChange)checkChange($event)Tag3/nz-tag }) export class NzDemoTagCheckableComponent { checkChange(e: boolean): void { console.log(e); } }这段示例体现了 checkable 模式三个核心输入输出nzModecheckable—— 开启可选择模式是进入本模式的唯一开关[nzChecked]true—— 初始化选中状态为 true即标签初始即处于已选中的视觉状态(nzCheckedChange)checkChange($event)—— 每次点击切换后事件回调会收到一个boolean类型的当前选中值。使用前请确保在你的模块或组件中导入NzTagModule见 tag.module.ts 与 public-api.ts。在 Angular 独立组件standalone模式下直接在组件imports中引入NzTagModule即可如上示例所示。三、核心 API 详解nzChecked 与 nzCheckedChangecheckable 模式涉及两个关键成员均定义在 tag.component.ts 中Input({ transform: booleanAttribute }) nzChecked false; Output() readonly nzCheckedChange new EventEmitterboolean();3.1 nzChecked可控的选中状态类型boolean通过 Angular 的booleanAttribute转换因此模板中可直接写nzChecked无值即为 true也可以写[nzChecked]true或[nzChecked]isChecked绑定组件字段。默认值false即默认未选中。语义它既是初始选中状态也是组件内部维护的当前选中状态。点击切换时组件会直接改写这个内部值详见下文源码原理。3.2 nzCheckedChange选中状态变化事件类型EventEmitterboolean。触发时机仅在 checkable 模式下、用户点击标签切换状态时触发每次点击触发一次回调参数为切换后的布尔值。典型用途把选中结果同步到业务状态中例如记录哪些标签被选中。3.3 双向绑定Banana in a Box写法组件官方测试用例tag.spec.ts使用了双向绑定语法nz-tag [nzMode]mode() [(nzChecked)]checked (nzCheckedChange)checkedChange($event) Tag 1 /nz-tag由于nzChecked与nzCheckedChange符合 Angular 的双向绑定命名约定xxx/xxxChange[(nzChecked)]可以直接使用省去手动同步状态的手写逻辑是最推荐的生产写法。四、源码原理点击后发生了什么checkable 模式的全部交互逻辑都集中在 tag.component.ts 的updateCheckedStatus()方法中updateCheckedStatus(): void { if (this.nzMode checkable) { this.nzChecked !this.nzChecked; this.nzCheckedChange.emit(this.nzChecked); } }对应的模板与宿主绑定[class.ant-tag-checkable]: nzMode checkable, [class.ant-tag-checkable-checked]: nzChecked, (click): updateCheckedStatus()整个交互链路可以拆解为三步点击触发组件的宿主元素绑定了(click)事件任意位置点击nz-tag都会调用updateCheckedStatus()模式守卫方法内部首先判断nzMode checkable只有 checkable 模式下才会取反nzChecked并发出nzCheckedChange事件。这意味着即使误点了 default 或 closeable 模式的标签也不会触发任何选中状态变化状态生效nzChecked变化后宿主绑定[class.ant-tag-checkable-checked]会随之更新标签的视觉选中样式立即生效。值得注意的是取反逻辑是立即、同步的没有防抖、没有动画干预点击一次状态就翻转一次与原生 Checkbox 的即时响应体验一致。五、样式原理ant-tag-checkable 与 ant-tag-checkable-checked选中状态的视觉反馈完全由 CSS 类驱动。相关样式定义在 components/tag/style/index.less-checkable { background-color: transparent; border-color: transparent; cursor: pointer; :not(-checked):hover { color: primary-color; } :active, -checked { color: text-color-inverse; } -checked { background-color: primary-6; } :active { background-color: primary-7; } }从样式代码可以总结出 checkable 标签的视觉行为未选中态背景透明、边框透明看起来像一段纯文字但cursor: pointer明确暗示其可点击性悬停态文字颜色变为主题色primary-color给出可交互的视觉提示选中态ant-tag-checkable-checked背景填充为主题色primary-6文字反白text-color-inverse与选中后的 Checkbox 语义一致按下态:active背景加深为primary-7提供按压反馈。也就是说nzModecheckable负责添加ant-tag-checkable类基础可点击样式而nzChecked为 true 时额外添加ant-tag-checkable-checked类选中填充样式两者组合构成了完整的 checkable 视觉体系。六、测试验证组件行为如何被保障checkable 的交互行为在单元测试中有完整覆盖见 tag.spec.ts 的should checkable work用例it(should checkable work, () { fixture.detectChanges(); expect(tag.nativeElement.classList).not.toContain(ant-tag-checkable); testComponent.mode.set(checkable); fixture.detectChanges(); expect(testComponent.checked()).toBe(false); expect(testComponent.checkedChange).toHaveBeenCalledTimes(0); expect(tag.nativeElement.classList).toContain(ant-tag-checkable); expect(tag.nativeElement.classList).not.toContain(ant-tag-checkable-checked); tag.nativeElement.click(); fixture.detectChanges(); expect(testComponent.checked()).toBe(true); expect(testComponent.checkedChange).toHaveBeenCalledTimes(1); expect(tag.nativeElement.classList).toContain(ant-tag-checkable-checked); });该测试逐条印证了前文分析的结论默认模式下标签不带ant-tag-checkable类切换为 checkable 模式后立即出现ant-tag-checkable类初始checked为 false且尚未触发任何checkedChange事件模拟一次原生click()后checked翻转为 true、checkedChange恰好触发一次、ant-tag-checkable-checked类出现。这与源码中updateCheckedStatus()的先取反、再 emit逻辑完全对应也从测试层面确认了事件只会在 checkable 模式下发出。七、进阶组合checkable 与其他 Tag 能力的搭配checkable 模式并非孤立功能它可以与nz-tag的其他输入自由组合使交互更丰富与nzColor组合给 checkable 标签指定预设色或自定义色NzTagColor类型见 typings.ts例如nz-tag nzModecheckable nzColorblue选中填充仍以主题色为主但未选中态可呈现彩色文字与nzBordered组合[nzBordered]false可去掉边框配合 checkable 更接近纯文本按钮风格默认nzBordered true见 tag.component.ts与 closeable 的区分checkable 和 closeable 是互斥的两种模式不可同时生效。需要可勾选 可删除时可在外层循环中分别渲染两类标签参考 control.ts 中按条件切换nzMode的写法。八、最佳实践小结开箱即用nzModecheckable一行即可获得 Checkbox 式交互无需引入额外组件优先双向绑定需要维护选中集合时用[(nzChecked)]state替代手写事件回调避免状态漂移事件只读、状态驱动nzCheckedChange只用于同步外部业务状态不要试图在回调里再次改写nzChecked组件内部已在 emit 前完成取反注意模式守卫事件仅在 checkable 模式下触发业务代码无需自行判断模式样式可预期选中/悬停/按下三态均由主题变量primary-color、primary-6、primary-7驱动跟随主题切换自动适配。结合 checkable.ts 示例、tag.component.ts 源码与 tag.spec.ts 测试你已经可以放心地在项目中落地 checkable 标签并能向他人讲清楚它的实现原理。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐ng-zorro-antd Slider 反向模式nzReverse实战指南从 Demo 到源码原理ng zorro antd Slider 反向模式nzReverse实战指南从 Demo 到源码原理 导读 在基于 Ant Design 的 AngulaUI组件前端ng-zorro-antd DatePicker 实战用 [nzMode] 动态切换 Date / Week / Month / Quarter / Year 选择器ng zorro antd DatePicker 实战用 nzMode 动态切换 Date / Week / Month / Quarter / Year 选UI组件前端ng-zorro-antd 日期范围选择器实战nzMode 六种粒度、双面板选择与源码细节ng zorro antd 日期范围选择器实战nzMode 六种粒度、双面板选择与源码细节 本文以 范围选择器示例 https://link.gitcode.UI组件前端上一篇MoocDownloader终极指南5分钟掌握.NET实现的MOOC课程离线下载技术下一篇如何自动生成并排名提示词gpt-prompt-engineer 完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考