ant-design Badge 徽标数组件完全指南：API、滚动数字动画与源码实现解析

ant-design Badge 徽标数组件完全指南：API、滚动数字动画与源码实现解析

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

Badge（徽标数）是 ant-design 中最常用的展示型组件之一，用于在图标或头像右上角以圆形徽标呈现待处理消息条数，通过醒目的视觉形式吸引用户处理。本文以 components/badge/index.md 为核心，结合 组件实现、滚动数字实现、样式定义 与全部 7 个官方 demo，完整讲解 Badge 的 API、使用场景、封顶逻辑、小红点模式与底层动画原理，帮助你在实际项目中正确选用并深度定制 Badge。

何时使用

Badge 一般出现在通知图标或头像的右上角，用于显示需要处理的消息条数，通过醒目视觉形式吸引用户处理。典型场景包括：

• 站内信 / 消息中心未读数提示；
• 购物车商品数量角标；
• 头像上的动态提醒小红点；
• 表格、列表行级状态标记。

Badge 有两种核心形态：数字徽标（count）与纯红点（dot），前者传达具体数量，后者只表达"有新内容"这一状态，两者可独立使用也可与任意子元素（图标、链接、头像等）组合。

API 一览

// 包裹子元素：徽标显示在子元素右上角 <Badge count={5}> <a href="#" className="head-example"></a> </Badge> // 独立使用：不包裹任何元素，徽标直接渲染 <Badge count={5} />

参数	说明	类型	可选值	默认值
count	展示的数字，大于 overflowCount 时显示为${overflowCount}+，为 0 时隐藏	Number
overflowCount	展示封顶的数字值	Number	99
dot	不展示数字，只有一个小红点	boolean	false

结合 components/badge/index.jsx 可以确认这三个属性的类型与默认行为：

AntBadge.defaultProps = { prefixCls: 'ant-badge', count: null, dot: false, overflowCount: 99, }; AntBadge.propTypes = { count: React.PropTypes.oneOfType([ React.PropTypes.string, React.PropTypes.number ]), dot: React.PropTypes.bool, overflowCount: React.PropTypes.number, };

需要特别说明的是：虽然文档表格中 count 标注为 Number，但源码 propTypes 明确允许string或number两种类型，因此你也可以传入字符串形式的数字（如count="5"）。

关键行为一：封顶显示（overflowCount）

组件渲染时首先执行count > overflowCount ?${overflowCount}+: count（见 components/badge/index.jsx）。当数字超过封顶值时，一律显示为${overflowCount}+，避免超长数字撑破角标布局：

// count=99 未超过默认封顶值 99，显示 "99" <Badge count={99}> <a href="#" className="head-example"></a> </Badge> // count=200 超过 99，显示 "99+" <Badge count={200}> <a href="#" className="head-example"></a> </Badge>

封顶值可以自由定制（demo 见 components/badge/demo/overflow.md）：

// 自定义封顶为 10，count=99 显示 "10+" <Badge count={99} overflowCount={10}> <a href="#" className="head-example"></a> </Badge> // 自定义封顶为 999，count=1000 显示 "999+" <Badge count={1000} overflowCount={999}> <a href="#" className="head-example"></a> </Badge>

关键行为二：count 为 0 时自动隐藏

源码中的隐藏判定为(!count || count === '0') && !dot（见 components/badge/index.jsx），这意味着null、undefined、空字符串""、字符串"0"以及数字0均不会渲染徽标，避免页面出现无意义的零角标。此规则对dot模式不生效——小红点模式下无论 count 为何值都会显示红点（该行之前已执行count = ''清空数字）。

基本用法

最简单的用法是用 Badge 包裹一个子元素，徽标会绝对定位在子元素右上角（demo 见 components/badge/demo/basic.md）：

import { Badge } from 'antd'; ReactDOM.render( <Badge count={5}> <a href="#" className="head-example"></a> </Badge> , mountNode);

.ant-badge { margin-right: 16px; } .head-example { width: 42px; height: 42px; border-radius: 6px; background: #eee; display: inline-block; }

其中.head-example只是一个占位容器，实际项目中你可以替换为任意图标（<Icon type="notification" />）、头像或链接。

讨嫌的小红点（dot 模式）

当只需要表达"有新内容"而无需展示具体数量时，使用dot模式（demo 见 components/badge/demo/dot.md）：

import { Badge, Icon } from 'antd'; ReactDOM.render(<div> <Badge dot> <Icon type="notification" /> </Badge> <Badge dot> <a href="#">一个链接</a> </Badge> </div>, mountNode);

从源码可见（components/badge/index.jsx），dot 模式下会无条件将 count 置空，并切换到ant-badge-dot样式类。小红点的视觉规格在 style/components/badge.less 中定义：8px × 8px正圆、红色背景（@error-color）、白色描边阴影（box-shadow: 0 0 0 1px #fff），确保在深色图片或复杂背景上依然清晰可辨。

独立使用（不包裹子元素）

当 Badge 不包裹任何子元素时，会自动添加ant-badge-not-a-wrapper样式类（见 components/badge/index.jsx），角标由绝对定位切换为普通流式布局，此时可完全通过style自定义外观（demo 见 components/badge/demo/no-wrapper.md）：

import { Badge } from 'antd'; ReactDOM.render(<div> {/* 默认红色角标 */} <Badge count={25} /> {/* 白色底、灰色文字的自定义角标 */} <Badge count={4} style={{ backgroundColor: '#fff', color: '#999', borderColor: '#d9d9d9' }} /> {/* 绿色角标 */} <Badge count={109} style={{ backgroundColor: '#87d068' }} /> </div>, mountNode);

对应的样式约束位于 style/components/badge.less：not-a-wrapper模式下position: relative、取消translateX偏移、top: auto，使角标按文档流正常排列。独立使用时右上角默认限定为红色，自定义颜色需显式传入style。

可点击

将 Badge 包裹在<a>链接内即可实现点击跳转，角标区域的 hover/active 状态还会呈现颜色加深反馈（demo 见 components/badge/demo/link.md）：

import { Badge } from 'antd'; ReactDOM.render( <a href="#"> <Badge count={5}> <span className="head-example"></span> </Badge> </a> , mountNode);

这一交互细节定义在 style/components/badge.less：a .ant-badge-count:hover时背景变为tint(@error-color, 20%)，:active时变为shade(@error-color, 5%)。

动态变化

Badge 支持受控的数字增减与红点显隐切换，配合按钮可构建典型的"消息中心未读数"交互（demo 见 components/badge/demo/change.md）：

import { Badge, Button, Icon } from 'antd'; const ButtonGroup = Button.Group; const Test = React.createClass({ getInitialState() { return { count: 5, show: true, }; }, increase() { const count = this.state.count + 1; this.setState({ count }); }, decline() { let count = this.state.count - 1; if (count < 0) { count = 0; } this.setState({ count }); }, onClick() { this.setState({ show: !this.state.show, }); }, render() { return ( <div> <Badge count={this.state.count}> <a href="#" className="head-example"></a> </Badge> <Badge dot={this.state.show}> <a href="#" className="head-example"></a> </Badge> <div style={{ marginTop: 10 }}> <ButtonGroup> <Button type="ghost" onClick={this.decline}> <Icon type="minus" /> </Button> <Button type="ghost" onClick={this.increase}> <Icon type="plus" /> </Button> </ButtonGroup> <Button type="ghost" onClick={this.onClick} style={{ marginLeft: 8 }}> 切换红点显隐 </Button> </div> </div> ); } }); ReactDOM.render( <Test /> , mountNode);

示例中还演示了count递减时主动拦截为 0（if (count < 0) count = 0），这正好与源码中"count 为 0 隐藏徽标"的行为呼应——当未读数归零时角标自动消失。

源码原理：滚动数字（ScrollNumber）与入场动画

Badge 数字角标的底层渲染由 components/badge/ScrollNumber.jsx 完成，外层由rc-animate驱动缩放动画。

数字切换动画

当count变化时（见 components/badge/ScrollNumber.jsx），组件记录旧值lastCount，先恢复数字到初始偏移位置（animateStarted: true），再在setTimeout5ms 后切换到新值，配合 CSStransition实现数字自下而上的滚动效果。

核心逻辑在getPositionByNum（components/badge/ScrollNumber.jsx）：组件内部渲染 0–9 循环的 30 行数字列（renderNumberList，每行高度 18px），通过translate3d(0, -position * height, 0)定位到目标数字；当新值比旧值大时从下方（20 + num）滚入，反之从上方滚出，保证数字增减方向与滚动方向一致、视觉连贯。

// 数字位渲染，单行高度 18px（默认） const position = this.getPositionByNum(num, i); const height = this.props.height; style: { transition: removeTransition && 'none', transform: `translate3d(0, ${-position * height}px, 0)`, height, }

入场 / 离场缩放

外层 components/badge/index.jsx 使用Animate（来自rc-animate）绑定ant-badge-zoom过渡名：角标出现时执行antZoomBadgeIn（0.3s，@ease-out-back弹性缓动，从scale(0)放大到scale(1)），消失时执行antZoomBadgeOut（缩回并淡出），关键帧定义见 style/components/badge.less。

降级处理

render()中检测isCssAnimationSupported（见 components/badge/ScrollNumber.jsx）：当浏览器不支持 CSS 动画时，直接渲染纯文本数字props.count，保证基础功能在低端环境仍可用。

样式定制要点

Badge 相关样式集中在 style/components/badge.less，关键视觉规格如下：

元素	规格
-count数字角标	绝对定位、top: -10px、高 20px、圆角 10px、最小宽 20px、红色背景、白字 12px、box-shadow: 0 0 0 1px #fff白描边
-dot红点	绝对定位、top: -4px、8px × 8px正圆、红色背景、白描边
-not-a-wrapper	独立使用时改为文档流定位（position: relative，取消偏移）
-zoom-appear/-enter/-leave	0.3s 缩放动画，进入用@ease-out-back，离开用@ease-in-back

在实际项目中，可通过覆盖@error-color主题变量（见 style/themes/default/custom.less）统一调整徽标颜色，或对单个实例传入style进行局部定制。

小结

• Badge 提供count、overflowCount、dot三个核心属性，分别控制数字内容、封顶阈值与红点形态；
• count 超过overflowCount时显示为${overflowCount}+，count 为 0 时自动隐藏；
• 支持包裹子元素、独立使用、可点击三种布局形态，dot模式适合"有新内容"的轻提示场景；
• 数字切换具备滚动动画、入场缩放动画，并对不支持 CSS 动画的环境做了降级；
• 所有行为均可从 components/badge/index.jsx、components/badge/ScrollNumber.jsx 与 style/components/badge.less 中得到源码级印证，7 个官方 demo 位于 components/badge/demo 目录，可直接作为上手模板。

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