ng-zorro-antd Badge 徽标组件基础实战：nzCount 计数展示与 nzShowZero 零值显隐控制-育师

UI组件
前端

【免费下载链接】ng-zorro-antd

Angular UI Component Library based on Ant Design

项目地址：https://gitcode.com/gh_mirrors/ng/ng-zorro-antd

徽标（Badge）是数据展示场景中最常用的反馈组件之一，用于在图标、头像或文字块的右上角呈现消息条数。本指南以 ng-zorro-antd 的基本用法示例为骨架，结合 Badge 组件源码与 API 文档，系统讲解nzCount计数的渲染规则、nzShowZero零值显隐控制的底层实现，以及自定义计数模板等实战写法。读完本文，你将能够独立配置出"数字徽标、零值显示、图标计数、状态点、溢出封顶"等完整方案，并理解其内部滚动数字动画的原理。

一、组件定位与适用场景

Badge 一般出现在通知图标或头像的右上角，用于显示需要处理的消息条数，通过醒目的视觉形式吸引用户处理。在 ng-zorro-antd 中，入口模块为NzBadgeModule（公共 API），组件选择器为nz-badge，其核心职责有三：

数字徽标：右上角圆形徽标数字，如未读消息数、购物车商品数；
状态点：仅显示一个小圆点，配合nzStatus、nzText表达在线、错误、警告等状态；
缎带：通过nz-ribbon在元素边缘展示强调性色带。

本文聚焦第一种能力，即"包裹内容 + 展示计数"的基础形态，这正是 basic.md 演示的核心。

二、基本用法：包裹内容并展示计数

nz-badge采用"包裹宿主元素"的模式：把图标、链接或任意内容放进组件内部，徽标会自动定位到宿主的右上角。完整的基础示例代码如下：

import { Component } from '@angular/core'; import { NzBadgeModule } from 'ng-zorro-antd/badge'; import { NzIconModule } from 'ng-zorro-antd/icon'; @Component({ selector: 'nz-demo-badge-basic', imports: [NzBadgeModule, NzIconModule], template: ` <nz-badge [nzCount]="5"> <a class="head-example"></a> </nz-badge> <nz-badge [nzCount]="0" nzShowZero> <a class="head-example"></a> </nz-badge> <nz-badge [nzCount]="iconTemplate"> <a class="head-example"></a> </nz-badge> <ng-template #iconTemplate> <nz-icon nzType="clock-circle" class="ant-scroll-number-custom-component" style="color: #f5222d" /> </ng-template> `, styles: ` nz-badge { margin-inline-end: 20px; } .head-example { width: 42px; height: 42px; border-radius: 4px; background: #eee; display: inline-block; vertical-align: middle; } ` }) export class NzDemoBadgeBasicComponent {}

示例同时演示了三种核心形态：

普通数字徽标：[nzCount]="5"显示数字5；
零值显隐控制：[nzCount]="0" nzShowZero，数字为 0 时仍强制显示徽标；
模板计数：[nzCount]="iconTemplate"，将ng-template作为计数内容，此时徽标内渲染的是一个clock-circle图标而非数字。

需要特别注意的是，示例中的.head-example样式只是演示用占位块，实际项目中可以换成nz-icon、<a>、头像组件或任意自定义内容。

从零构建最小示例

在你的 Angular 项目中，只需三步即可复现：

引入模块：在组件的imports中加入NzBadgeModule（Standalone 组件直接引入，传统模块则在NgModule中声明）；
编写模板：用nz-badge包裹目标内容并传入nzCount；
按需引入图标：若使用模板计数或状态点，还需引入NzIconModule与对应图标。

三、核心输入属性：nzCount 与 nzShowZero

根据 Badge API 文档，nz-badge与计数展示直接相关的输入属性如下：

参数	说明	类型	默认值	全局配置
`[nzCount]`	展示的数字，大于`nzOverflowCount`时显示为`${nzOverflowCount}+`，为 0 时隐藏	`number \\| TemplateRef<void>`	-	-
`[nzShowZero]`	当数值为 0 时，是否展示 Badge	`boolean`	`false`	-
`[nzOverflowCount]`	展示封顶的数字值	`number`	`99`	✅
`[nzDot]`	不展示数字，只有一个小红点	`boolean`	`false`	-
`[nzShowDot]`	是否展示小红点	`boolean`	`true`	-
`[nzSize]`	在设置了`nzCount`的前提下有效，设置小圆点的大小	`'default' \\| 'small'`	`'default'`	-
`[nzOffset]`	设置状态点的位置偏移，格式为`[x, y]`（非独立使用时）	`[number, number]`	-	-
`[nzTitle]`	设置鼠标放在状态点上时显示的文字（非独立使用时），为`null`时隐藏	`string \\| null`	`nzCount`	-

对基本用法而言，两个最重要的属性是：

nzCount：支持number与TemplateRef<void>两种类型。传入数字时渲染滚动数字；传入模板时完全自定义计数内容（如示例中的时钟图标）。从 badge.component.ts 可以看到，nzCount同时被NzOutletModule的nzStringTemplateOutlet消费，因此也支持字符串。
nzShowZero：默认false。当其值为false且nzCount为 0 时，徽标整体隐藏；设为true后，即使数字为 0 也会渲染一个0徽标，这在"新消息数为 0 也要让用户知道入口存在"的产品需求中非常实用。

四、源码级解析：0 值隐藏与显示的判定逻辑

nzShowZero为什么能控制显隐？答案在 badge.component.ts 的ngOnChanges中：

ngOnChanges(changes: SimpleChanges): void { const { nzColor, nzShowDot, nzDot, nzCount, nzShowZero } = changes; ... if (nzShowDot || nzDot || nzCount || nzShowZero) { this.showSup = (this.nzShowDot && this.nzDot) || (typeof this.nzCount === 'number' && (this.nzCount > 0 || this.nzShowZero)); } }

可见「是否渲染徽标角标」由受保护的成员showSup决定，判定规则为两个分支的或运算：

圆点模式：nzShowDot && nzDot为真，即开启圆点且允许显示；
数字模式：nzCount是数字，且满足「大于 0」或「等于 0 但开了nzShowZero」。

因此[nzCount]="0"且不设nzShowZero时，第二个分支条件nzCount > 0为假、nzShowZero为假，showSup为false，徽标隐藏——这正是 basic.md 中描述的行为："Badge will be hidden whennzCountis0, but we can usenzShowZeroto show it."

两个值得注意的实现细节：

nzShowZero、nzDot、nzShowDot均使用booleanAttribute转换（badge.component.ts），因此模板中既可以写nzShowZero属性简写形式，也可以写[nzShowZero]="true"的绑定形式；
只有当nzCount是number类型时才参与"0 值隐藏"判定；如果传入的是TemplateRef（如示例中的图标），则showSup直接为真，模板计数始终显示。

五、滚动数字与溢出封顶：nz-badge-sup 的内部实现

当showSup为真时，badge.component.ts 会渲染内部组件nz-badge-sup（选择器nz-badge-sup）。这个小组件承担了徽标角标的全部视觉细节，其模板逻辑（badge-sup.component.ts）包含两个关键分支：

@if (count <= nzOverflowCount) { @for (n of maxNumberArray; track n; let i = $index) { <span class="ant-scroll-number-only" [style.transform]="'translateY(' + -countArray[i] * 100 + '%)'"> ... </span> } } @else { {{ nzOverflowCount }}+ }

滚动数字动画：每个数位是一列 0–9 的纵向单元，通过translateY(-count * 100%)滚动到目标数字，形成经典的"数字翻牌"效果；当countArray.length >= 2时还会追加ant-badge-multiple-words类以适配多位数宽度。
溢出封顶：当count > nzOverflowCount时，直接渲染为${nzOverflowCount}+文本，例如默认值 99 时，[nzCount]="200"会显示99+。该行为在 overflow 示例中有直观演示，其中还包含[nzOverflowCount]="10"、[nzOverflowCount]="999"的自定义封顶写法。
数据派生：ngOnChanges中把nzCount钳制为非负整数（Math.max(0, nzCount)）后按位拆分为countArray（badge-sup.component.ts），负数计数值不会产生非法渲染。

六、实战扩展：动态计数、状态点与全局配置

在基本用法之上，结合仓库内其他示例可快速扩展出完整方案：

动态增减计数。参考 dynamic.ts，使用signal维护count，通过按钮addCount/minusCount/random更新；minusCount中Math.max(0, count - 1)与源码的钳制逻辑一致，避免负值。该示例同时用nz-switch切换nzDot演示"红点模式"。

红点模式。参考 dot.ts，<nz-badge nzDot>只显示一个小红点而不渲染数字，适合"有更新但不必显示数量"的场景。

状态点与预设色。nzStatus取值为'success' | 'processing' | 'default' | 'error' | 'warning'（见 types.ts），与nzText搭配可构成带文案的状态徽标。此外 preset-colors.ts 定义了pink/red/yellow/orange/cyan/green/blue/purple/geekblue/magenta/volcano/gold/lime共 13 种预设色，nzColor命中预设色时会复用预设样式类而非内联背景色（badge.component.ts）。

全局配置。nzOverflowCount与nzColor标注了"全局配置 ✅"，可通过NzConfigService的setConfig('badge', { nzOverflowCount: 999 })全局统一默认值，避免在每个组件上重复声明。

七、小结

ng-zorro-antd 的 Badge 基础用法以nzCount为数据入口、以nzShowZero控制 0 值显隐，背后由showSup的布尔判定与nz-badge-sup的滚动数字渲染协同完成。掌握 basic.ts 中的三种写法（数字、0 值、模板计数），再结合溢出封顶、动态计数与状态点能力，即可覆盖绝大多数"消息提醒 / 数量展示"交互场景。更多完整属性说明可继续阅读 Badge 组件文档及组件规格测试。