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 sizemiddle Badge count{5} Avatar shapesquare sizelarge / /Badge Badge count{0} showZero Avatar shapesquare sizelarge / /Badge Badge count{ClockCircleOutlined style{{ color: #f5222d }} /} Avatar shapesquare sizelarge / /Badge /Space ); export default App;这个示例实际上覆盖了 Badge 的三个关键能力演示形态关键写法效果说明普通数字徽标Badge count{5}在头像Avatar右上角显示红色圆形徽标数字为 5零值显隐控制Badge count{0} showZerocount为 0 时默认隐藏加上showZero后显示为 0自定义内容count{ClockCircleOutlined ... /}count接受任意 ReactNode可渲染图标等富内容count 为 0 时为何默认隐藏count为 0 时隐藏徽标是 antd 的既定设计——徽标用来提示“有待处理的事项数量”0 意味着没有待处理事项因此不展示反而更符合直觉。这在 index.tsx 的默认参数中可以找到依据count null、showZero false均为默认值。如果业务上确实需要在数量为 0 时也展示徽标例如“已处理 0 条”的统计场景只需设置showZeroBadge count{0} showZero Avatar shapesquare sizelarge / /Badge源码视角徽标的显示与隐藏判定逻辑要理解“0 隐藏 / showZero 显示”的完整规则需要阅读 index.tsx 的核心实现。Badge 的渲染逻辑大致分三步数字封顶numberedDisplayCount判断count是否超过overflowCount超过则显示为${overflowCount}默认封顶值 99const numberedDisplayCount ( (count as number) (overflowCount as number) ? ${overflowCount} : count ) as string | number | null;零值识别isZero同时兼容数字0和字符串0例如count0的场景因为count的类型是ReactNodeconst isZero numberedDisplayCount 0 || numberedDisplayCount 0;隐藏判定ignoreCount同时考虑“count 为空”和“count 为 0 且未开启 showZero”两种情况const ignoreCount count null || (isZero !showZero);由此可以得到完整的显隐规则表count 取值showZero显示结果count{5}false默认显示5count{0}false默认隐藏count{0}true显示0count{null}未传任意隐藏count{100}默认 overflowCount99任意显示99此外源码中还使用useRef缓存了count与mergedCount见 index.tsx保证徽标隐藏与显隐切换动画过程中数字内容不发生抖动——这与 ScrollNumber.tsx 中逐位滚动数字的动画机制配合实现了数字更新时的滚动效果仅整数走逐位动画浮点数如3.5直接整体渲染测试用例见 index.test.tsx。Badge 核心 API 参数详解以下参数表完整继承自官方文档 index.zh-CN.md并补充了源码确认的默认值与实现细节参数说明类型默认值color自定义小圆点的颜色string-count展示的数字大于overflowCount时显示为${overflowCount}为 0 时隐藏ReactNode-classNames语义化结构 classroot/indicatorRecordSemanticDOM, string-5.7.0dot不展示数字只有一个小红点booleanfalseoffset设置状态点的位置偏移[水平, 垂直][number, number]-overflowCount展示封顶的数字值number99showZero当数值为 0 时是否展示 Badgebooleanfalsesize在设置了count的前提下有效设置小圆点的大小default|smalldefaultstatus设置 Badge 为状态点success|processing|default|error|warning-styles语义化结构 styleroot/indicatorRecordSemanticDOM, CSSProperties-5.7.0text在设置了status的前提下有效设置状态点的文本ReactNode-title设置鼠标放在状态点上时显示的文字string-几点来自源码的补充说明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.RibbonAPI 如下参数说明类型默认值color自定义缎带的颜色string-placement缎带的位置start和end随文字方向RTL 或 LTR变动start|endendtext缎带中填入的内容ReactNode-基础用法的实战延伸理解基础用法后官方其他 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 位移让徽标按普通行内元素排版。封顶数字overflowCountBadge count{99} Avatar shapesquare sizelarge / /Badge Badge count{100} Avatar shapesquare sizelarge / /Badge Badge count{99} overflowCount{10} Avatar shapesquare sizelarge / /Badgecount{100}未设置overflowCount时显示为99而count{99} overflowCount{10}会显示为10完整示例见 overflow.tsx。讨嫌的小红点dotBadge dot NotificationOutlined style{{ fontSize: 16 }} / /Badge只显示红点、不显示数字常用于“有新消息”的提示dot.tsx。源码中showAsDot dot !isZeroindex.tsx即count为 0 时红点也会隐藏测试用例见 index.test.tsx。状态点statusBadge statussuccess / Badge statuserror textError / Badge statusprocessing textProcessing /status支持success、processing、default、error、warning五种预置状态可配合text展示文字status.tsx。其中processing状态带有一个无限扩散的光圈动画动画实现位于 style/index.ts持续时间为1.2sbadgeProcessingDuration。主题变量Design TokenBadge 支持通过 Theme 定制样式组件级 Token 定义在 style/index.tsToken说明默认计算值indicatorZIndex徽标 z-indexautoindicatorHeight徽标高度round(fontSize * lineHeight) - 2 * lineWidthindicatorHeightSM小号徽标高度fontSizedotSize点状徽标尺寸fontSizeSM / 2textFontSize徽标文本尺寸fontSizeSMtextFontSizeSM小号徽标文本尺寸fontSizeSMtextFontWeight徽标文本粗细normalstatusSize状态徽标尺寸fontSizeSM / 2通过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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考