ant-design Badge 徽标数组件完全指南API、滚动数字动画与源码实现解析【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/antde/ant-designBadge徽标数是 ant-design 中最常用的展示型组件之一用于在图标或头像右上角以圆形徽标呈现待处理消息条数通过醒目的视觉形式吸引用户处理。本文以 components/badge/index.md 为核心结合 组件实现、滚动数字实现、样式定义 与全部 7 个官方 demo完整讲解 Badge 的 API、使用场景、封顶逻辑、小红点模式与底层动画原理帮助你在实际项目中正确选用并深度定制 Badge。何时使用Badge 一般出现在通知图标或头像的右上角用于显示需要处理的消息条数通过醒目视觉形式吸引用户处理。典型场景包括站内信 / 消息中心未读数提示购物车商品数量角标头像上的动态提醒小红点表格、列表行级状态标记。Badge 有两种核心形态数字徽标count与纯红点dot前者传达具体数量后者只表达有新内容这一状态两者可独立使用也可与任意子元素图标、链接、头像等组合。API 一览// 包裹子元素徽标显示在子元素右上角 Badge count{5} a href# classNamehead-example/a /Badge // 独立使用不包裹任何元素徽标直接渲染 Badge count{5} /参数说明类型可选值默认值count展示的数字大于 overflowCount 时显示为${overflowCount}为 0 时隐藏NumberoverflowCount展示封顶的数字值Number99dot不展示数字只有一个小红点booleanfalse结合 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两种类型因此你也可以传入字符串形式的数字如count5。关键行为一封顶显示overflowCount组件渲染时首先执行count overflowCount ?${overflowCount}: count见 components/badge/index.jsx。当数字超过封顶值时一律显示为${overflowCount}避免超长数字撑破角标布局// count99 未超过默认封顶值 99显示 99 Badge count{99} a href# classNamehead-example/a /Badge // count200 超过 99显示 99 Badge count{200} a href# classNamehead-example/a /Badge封顶值可以自由定制demo 见 components/badge/demo/overflow.md// 自定义封顶为 10count99 显示 10 Badge count{99} overflowCount{10} a href# classNamehead-example/a /Badge // 自定义封顶为 999count1000 显示 999 Badge count{1000} overflowCount{999} a href# classNamehead-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.mdimport { Badge } from antd; ReactDOM.render( Badge count{5} a href# classNamehead-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 typenotification /、头像或链接。讨嫌的小红点dot 模式当只需要表达有新内容而无需展示具体数量时使用dot模式demo 见 components/badge/demo/dot.mdimport { Badge, Icon } from antd; ReactDOM.render(div Badge dot Icon typenotification / /Badge Badge dot a href#一个链接/a /Badge /div, mountNode);从源码可见components/badge/index.jsxdot 模式下会无条件将 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.mdimport { 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.lessnot-a-wrapper模式下position: relative、取消translateX偏移、top: auto使角标按文档流正常排列。独立使用时右上角默认限定为红色自定义颜色需显式传入style。可点击将 Badge 包裹在a链接内即可实现点击跳转角标区域的 hover/active 状态还会呈现颜色加深反馈demo 见 components/badge/demo/link.mdimport { Badge } from antd; ReactDOM.render( a href# Badge count{5} span classNamehead-example/span /Badge /a , mountNode);这一交互细节定义在 style/components/badge.lessa .ant-badge-count:hover时背景变为tint(error-color, 20%):active时变为shade(error-color, 5%)。动态变化Badge 支持受控的数字增减与红点显隐切换配合按钮可构建典型的消息中心未读数交互demo 见 components/badge/demo/change.mdimport { 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# classNamehead-example/a /Badge Badge dot{this.state.show} a href# classNamehead-example/a /Badge div style{{ marginTop: 10 }} ButtonGroup Button typeghost onClick{this.decline} Icon typeminus / /Button Button typeghost onClick{this.increase} Icon typeplus / /Button /ButtonGroup Button typeghost onClick{this.onClick} style{{ marginLeft: 8 }} 切换红点显隐 /Button /div /div ); } }); ReactDOM.render( Test / , mountNode);示例中还演示了count递减时主动拦截为 0if (count 0) count 0这正好与源码中count 为 0 隐藏徽标的行为呼应——当未读数归零时角标自动消失。源码原理滚动数字ScrollNumber与入场动画Badge 数字角标的底层渲染由 components/badge/ScrollNumber.jsx 完成外层由rc-animate驱动缩放动画。数字切换动画当count变化时见 components/badge/ScrollNumber.jsx组件记录旧值lastCount先恢复数字到初始偏移位置animateStarted: true再在setTimeout5ms 后切换到新值配合 CSStransition实现数字自下而上的滚动效果。核心逻辑在getPositionByNumcomponents/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过渡名角标出现时执行antZoomBadgeIn0.3sease-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/-leave0.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/18 5:06:01 · 阅读 1.2k 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-designBadge徽标数是 ant-design 中最常用的展示型组件之一用于在图标或头像右上角以圆形徽标呈现待处理消息条数通过醒目的视觉形式吸引用户处理。本文以 components/badge/index.md 为核心结合 组件实现、滚动数字实现、样式定义 与全部 7 个官方 demo完整讲解 Badge 的 API、使用场景、封顶逻辑、小红点模式与底层动画原理帮助你在实际项目中正确选用并深度定制 Badge。何时使用Badge 一般出现在通知图标或头像的右上角用于显示需要处理的消息条数通过醒目视觉形式吸引用户处理。典型场景包括站内信 / 消息中心未读数提示购物车商品数量角标头像上的动态提醒小红点表格、列表行级状态标记。Badge 有两种核心形态数字徽标count与纯红点dot前者传达具体数量后者只表达有新内容这一状态两者可独立使用也可与任意子元素图标、链接、头像等组合。API 一览// 包裹子元素徽标显示在子元素右上角 Badge count{5} a href# classNamehead-example/a /Badge // 独立使用不包裹任何元素徽标直接渲染 Badge count{5} /参数说明类型可选值默认值count展示的数字大于 overflowCount 时显示为${overflowCount}为 0 时隐藏NumberoverflowCount展示封顶的数字值Number99dot不展示数字只有一个小红点booleanfalse结合 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两种类型因此你也可以传入字符串形式的数字如count5。关键行为一封顶显示overflowCount组件渲染时首先执行count overflowCount ?${overflowCount}: count见 components/badge/index.jsx。当数字超过封顶值时一律显示为${overflowCount}避免超长数字撑破角标布局// count99 未超过默认封顶值 99显示 99 Badge count{99} a href# classNamehead-example/a /Badge // count200 超过 99显示 99 Badge count{200} a href# classNamehead-example/a /Badge封顶值可以自由定制demo 见 components/badge/demo/overflow.md// 自定义封顶为 10count99 显示 10 Badge count{99} overflowCount{10} a href# classNamehead-example/a /Badge // 自定义封顶为 999count1000 显示 999 Badge count{1000} overflowCount{999} a href# classNamehead-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.mdimport { Badge } from antd; ReactDOM.render( Badge count{5} a href# classNamehead-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 typenotification /、头像或链接。讨嫌的小红点dot 模式当只需要表达有新内容而无需展示具体数量时使用dot模式demo 见 components/badge/demo/dot.mdimport { Badge, Icon } from antd; ReactDOM.render(div Badge dot Icon typenotification / /Badge Badge dot a href#一个链接/a /Badge /div, mountNode);从源码可见components/badge/index.jsxdot 模式下会无条件将 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.mdimport { 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.lessnot-a-wrapper模式下position: relative、取消translateX偏移、top: auto使角标按文档流正常排列。独立使用时右上角默认限定为红色自定义颜色需显式传入style。可点击将 Badge 包裹在a链接内即可实现点击跳转角标区域的 hover/active 状态还会呈现颜色加深反馈demo 见 components/badge/demo/link.mdimport { Badge } from antd; ReactDOM.render( a href# Badge count{5} span classNamehead-example/span /Badge /a , mountNode);这一交互细节定义在 style/components/badge.lessa .ant-badge-count:hover时背景变为tint(error-color, 20%):active时变为shade(error-color, 5%)。动态变化Badge 支持受控的数字增减与红点显隐切换配合按钮可构建典型的消息中心未读数交互demo 见 components/badge/demo/change.mdimport { 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# classNamehead-example/a /Badge Badge dot{this.state.show} a href# classNamehead-example/a /Badge div style{{ marginTop: 10 }} ButtonGroup Button typeghost onClick{this.decline} Icon typeminus / /Button Button typeghost onClick{this.increase} Icon typeplus / /Button /ButtonGroup Button typeghost onClick{this.onClick} style{{ marginLeft: 8 }} 切换红点显隐 /Button /div /div ); } }); ReactDOM.render( Test / , mountNode);示例中还演示了count递减时主动拦截为 0if (count 0) count 0这正好与源码中count 为 0 隐藏徽标的行为呼应——当未读数归零时角标自动消失。源码原理滚动数字ScrollNumber与入场动画Badge 数字角标的底层渲染由 components/badge/ScrollNumber.jsx 完成外层由rc-animate驱动缩放动画。数字切换动画当count变化时见 components/badge/ScrollNumber.jsx组件记录旧值lastCount先恢复数字到初始偏移位置animateStarted: true再在setTimeout5ms 后切换到新值配合 CSStransition实现数字自下而上的滚动效果。核心逻辑在getPositionByNumcomponents/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过渡名角标出现时执行antZoomBadgeIn0.3sease-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/-leave0.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考