企业官网建设流程全解析

Ant Design Badge 徽标基础用法全解析：count、showZero 与徽标显示逻辑

【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design

导读

本文围绕 ant-design（当前仓库 components/badge 模块）中最基础的徽标（Badge）演示展开，讲解“最简单的徽标展示”这一核心场景：当count为0时徽标默认隐藏，通过showZero可以强制显示。你将掌握 Badge 的完整 API 参数含义、count的封顶与隐藏规则、作为 ReactNode 传入的自定义徽标内容，以及底层源码中徽标显示/隐藏的判定逻辑，可直接应用于通知角标、头像角标等典型业务场景。

基础用法：从 demo 说起

官方演示 basic.tsx 展示了一个包含三种形态的“基本”示例，配套文档 basic.md 的说明非常精炼：

简单的徽章展示，当count为0时，默认不显示，但是可以使用showZero修改为显示。

完整代码如下（可直接复制运行）：

import React from 'react'; import { ClockCircleOutlined } from '@ant-design/icons'; import { Avatar, Badge, Space } from 'antd'; const App: React.FC = () => ( <Space size="middle"> <Badge count={5}> <Avatar shape="square" size="large" /> </Badge> <Badge count={0} showZero> <Avatar shape="square" size="large" /> </Badge> <Badge count={<ClockCircleOutlined style={{ color: '#f5222d' }} />}> <Avatar shape="square" size="large" /> </Badge> </Space> ); export default App;

这个示例实际上覆盖了 Badge 的三个关键能力：

count 为 0 时为何默认隐藏

count为 0 时隐藏徽标是 antd 的既定设计——徽标用来提示“有待处理的事项数量”，0 意味着没有待处理事项，因此不展示反而更符合直觉。这在 index.tsx 的默认参数中可以找到依据：count = null、showZero = false均为默认值。

如果业务上确实需要在数量为 0 时也展示徽标（例如“已处理 0 条”的统计场景），只需设置showZero：

<Badge count={0} showZero> <Avatar shape="square" size="large" /> </Badge>

源码视角：徽标的显示与隐藏判定逻辑

要理解“0 隐藏 / showZero 显示”的完整规则，需要阅读 index.tsx 的核心实现。Badge 的渲染逻辑大致分三步：

1. 数字封顶：numberedDisplayCount判断count是否超过overflowCount，超过则显示为${overflowCount}+（默认封顶值 99）：

const numberedDisplayCount = ( (count as number) > (overflowCount as number) ? `${overflowCount}+` : count ) as string | number | null;

2. 零值识别：isZero同时兼容数字0和字符串'0'（例如count="0"的场景），因为count的类型是ReactNode：

const isZero = numberedDisplayCount === '0' || numberedDisplayCount === 0;

3. 隐藏判定：ignoreCount同时考虑“count 为空”和“count 为 0 且未开启 showZero”两种情况：

const ignoreCount = count === null || (isZero && !showZero);

由此可以得到完整的显隐规则表：

此外，源码中还使用useRef缓存了count与mergedCount（见 index.tsx），保证徽标隐藏与显隐切换动画过程中数字内容不发生抖动——这与 ScrollNumber.tsx 中逐位滚动数字的动画机制配合，实现了数字更新时的滚动效果（仅整数走逐位动画，浮点数如3.5直接整体渲染，测试用例见 index.test.tsx）。

Badge 核心 API 参数详解

以下参数表完整继承自官方文档 index.zh-CN.md，并补充了源码确认的默认值与实现细节：

几点来自源码的补充说明：

• offset 的 RTL 适配：在 index.tsx 中，offset的第二个值会转为marginTop，第一个值在 RTL 方向下转成left，在 LTR 下转成right并取负值。测试用例 index.test.tsx 专门验证了offset={[10, 10]}在 RTL 下的渲染。
• title 的兜底：不传title时，会默认取count的字符串/数字值作为原生title属性（index.tsx），测试确认自定义title会覆盖默认值（index.test.tsx）。
• borderColor 兼容：通过style传入borderColor时，ScrollNumber.tsx 会用box-shadow模拟描边，兼容旧版用法。
• 负数的支持：测试用例确认count={-10}与count="-10"均可正常渲染（index.test.tsx）。

Badge.Ribbon 缎带

缎带是 Badge 的另一个形态（挂载于Badge.Ribbon），API 如下：

基础用法的实战延伸

理解基础用法后，官方其他 demo 都是在同一套 API 上的扩展，这里给出与“基础用法”最相关的几个变体：

独立使用（无包裹元素）

Badge 不包裹任何子元素时，会加上ant-badge-not-a-wrapper类名，作为独立元素展示：

import { Badge } from 'antd'; <Badge count={25} /> <Badge count={show ? 109 : 0} style={{ backgroundColor: '#52c41a' }} />

完整示例见 no-wrapper.tsx，其中也演示了showZero与自定义color/backgroundColor的组合使用。在 style/index.ts 中，not-a-wrapper模式会取消绝对定位的 translate 位移，让徽标按普通行内元素排版。

封顶数字（overflowCount）

<Badge count={99}> <Avatar shape="square" size="large" /> </Badge> <Badge count={100}> <Avatar shape="square" size="large" /> </Badge> <Badge count={99} overflowCount={10}> <Avatar shape="square" size="large" /> </Badge>

count={100}未设置overflowCount时显示为99+，而count={99} overflowCount={10}会显示为10+，完整示例见 overflow.tsx。

讨嫌的小红点（dot）

<Badge dot> <NotificationOutlined style={{ fontSize: 16 }} /> </Badge>

只显示红点、不显示数字，常用于“有新消息”的提示（dot.tsx）。源码中showAsDot = dot && !isZero（index.tsx），即count为 0 时红点也会隐藏（测试用例见 index.test.tsx）。

状态点（status）

<Badge status="success" /> <Badge status="error" text="Error" /> <Badge status="processing" text="Processing" />

status支持success、processing、default、error、warning五种预置状态，可配合text展示文字（status.tsx）。其中processing状态带有一个无限扩散的光圈动画，动画实现位于 style/index.ts，持续时间为1.2s（badgeProcessingDuration）。

主题变量（Design Token）

Badge 支持通过 Theme 定制样式，组件级 Token 定义在 style/index.ts：

通过ConfigProvider的theme.components.Badge即可覆盖这些 Token，例如：

import { ConfigProvider, Badge } from 'antd'; <ConfigProvider theme={{ components: { Badge: { indicatorHeight: 22, dotSize: 10, textFontWeight: 600 }, }, }} > <Badge count={5} /> </ConfigProvider>

小结

从最简单的count={5}到showZero的显隐控制，Badge 基础用法背后是一套严谨的显示逻辑：默认隐藏 0 值、超过overflowCount自动封顶、count支持任意 ReactNode、动画与缓存机制保证数字切换平滑。把握住 index.tsx 中的显隐判定与 style/index.ts 中的 Token 体系，就可以自由组合出通知角标、状态点、缎带等各类场景下的徽标方案。

【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design