企业官网建设流程全解析

• UI组件
• 前端

导读

本文聚焦 ng-zorro-antd 的nz-tag组件在nzMode="checkable"模式下的完整用法。该模式可以让一个普通的标签（Tag）像 Checkbox 一样支持点击切换选中状态，常用于筛选条件、多选标签集合、状态标记等交互场景。读完本文，你将掌握 checkable 模式的模板写法、双向绑定与事件监听方式，并通过阅读 tag.component.ts 源码理解其底层实现机制与样式原理。

一、原文档要点：一行代码让 Tag 变成 Checkbox

在 checkable.md 中，官方文档给出的核心说明非常精炼：

• 中文描述：可通过nzMode="checkable"实现类似 Checkbox 的效果，点击切换选中效果。
• 英文描述：nzMode="checkable"works like Checkbox, click it to toggle checked state.

也就是说，checkable 是nz-tag的三种模式之一。完整的nzMode取值域为'default' | 'closeable' | 'checkable'（见 tag.component.ts 中@Input() nzMode的类型定义），默认值为'default'。三种模式各自承担不同职责：

二、最小可运行示例：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 nzMode="checkable" [nzChecked]="true" (nzCheckedChange)="checkChange($event)">Tag1</nz-tag> <nz-tag nzMode="checkable" [nzChecked]="true" (nzCheckedChange)="checkChange($event)">Tag2</nz-tag> <nz-tag nzMode="checkable" [nzChecked]="true" (nzCheckedChange)="checkChange($event)">Tag3</nz-tag> ` }) export class NzDemoTagCheckableComponent { checkChange(e: boolean): void { console.log(e); } }

这段示例体现了 checkable 模式三个核心输入输出：

1. nzMode="checkable"—— 开启可选择模式，是进入本模式的唯一开关；
2. [nzChecked]="true"—— 初始化选中状态为 true（即标签初始即处于"已选中"的视觉状态）；
3. (nzCheckedChange)="checkChange($event)"—— 每次点击切换后，事件回调会收到一个boolean类型的当前选中值。

使用前请确保在你的模块或组件中导入NzTagModule（见 tag.module.ts 与 public-api.ts）。在 Angular 独立组件（standalone）模式下，直接在组件imports中引入NzTagModule即可，如上示例所示。

三、核心 API 详解：nzChecked 与 nzCheckedChange

checkable 模式涉及两个关键成员，均定义在 tag.component.ts 中：

@Input({ transform: booleanAttribute }) nzChecked = false; @Output() readonly nzCheckedChange = new EventEmitter<boolean>();

3.1 nzChecked：可控的选中状态

• 类型：boolean，通过 Angular 的booleanAttribute转换，因此模板中可直接写nzChecked（无值即为 true），也可以写[nzChecked]="true"或[nzChecked]="isChecked"绑定组件字段。
• 默认值：false，即默认未选中。
• 语义：它既是初始选中状态，也是组件内部维护的"当前选中状态"。点击切换时组件会直接改写这个内部值（详见下文"源码原理"）。

3.2 nzCheckedChange：选中状态变化事件

• 类型：EventEmitter<boolean>。
• 触发时机：仅在 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()'

整个交互链路可以拆解为三步：

1. 点击触发：组件的宿主元素绑定了(click)事件，任意位置点击nz-tag都会调用updateCheckedStatus()；
2. 模式守卫：方法内部首先判断nzMode === 'checkable'，只有 checkable 模式下才会取反nzChecked并发出nzCheckedChange事件。这意味着即使误点了 default 或 closeable 模式的标签，也不会触发任何选中状态变化；
3. 状态生效：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，提供按压反馈。

也就是说，nzMode="checkable"负责添加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'); });

该测试逐条印证了前文分析的结论：

1. 默认模式下标签不带ant-tag-checkable类；
2. 切换为 checkable 模式后立即出现ant-tag-checkable类，初始checked为 false，且尚未触发任何checkedChange事件；
3. 模拟一次原生click()后：checked翻转为 true、checkedChange恰好触发一次、ant-tag-checkable-checked类出现。

这与源码中updateCheckedStatus()的"先取反、再 emit"逻辑完全对应，也从测试层面确认了事件只会在 checkable 模式下发出。

七、进阶组合：checkable 与其他 Tag 能力的搭配

checkable 模式并非孤立功能，它可以与nz-tag的其他输入自由组合，使交互更丰富：

• 与nzColor组合：给 checkable 标签指定预设色或自定义色（NzTagColor类型见 typings.ts），例如<nz-tag nzMode="checkable" nzColor="blue">，选中填充仍以主题色为主，但未选中态可呈现彩色文字；
• 与nzBordered组合：[nzBordered]="false"可去掉边框，配合 checkable 更接近纯文本按钮风格（默认nzBordered = true，见 tag.component.ts）；
• 与 closeable 的区分：checkable 和 closeable 是互斥的两种模式，不可同时生效。需要"可勾选 + 可删除"时，可在外层循环中分别渲染两类标签，参考 control.ts 中按条件切换nzMode的写法。

八、最佳实践小结

1. 开箱即用：nzMode="checkable"一行即可获得 Checkbox 式交互，无需引入额外组件；
2. 优先双向绑定：需要维护选中集合时，用[(nzChecked)]="state"替代手写事件回调，避免状态漂移；
3. 事件只读、状态驱动：nzCheckedChange只用于同步外部业务状态，不要试图在回调里再次改写nzChecked，组件内部已在 emit 前完成取反；
4. 注意模式守卫：事件仅在 checkable 模式下触发，业务代码无需自行判断模式；
5. 样式可预期：选中/悬停/按下三态均由主题变量（@primary-color、@primary-6、@primary-7）驱动，跟随主题切换自动适配。

结合 checkable.ts 示例、tag.component.ts 源码与 tag.spec.ts 测试，你已经可以放心地在项目中落地 checkable 标签，并能向他人讲清楚它的实现原理。

• UI组件
• 前端