ant-design Badge 徽标数组件完全指南API 详解、源码原理与实战应用【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-designBadge徽标数是 ant-design 数据展示组件家族中最常用的组件之一通常出现在通知图标或头像的右上角用于展示待处理消息条数、未读标记或状态信号。本文基于当前仓库 components/badge 目录下的官方中文文档与源码实现系统讲解 Badge 的全部 API、核心交互行为封顶、溢出、滚动动画、状态点、缎带等及其底层实现原理帮助你在实际项目中熟练使用并知其所以然。何时使用一般出现在通知图标或头像的右上角用于显示需要处理的消息条数通过醒目视觉形式吸引用户处理。典型场景包括导航栏/侧边栏的通知入口展示未读消息数量头像右上角展示待办数量或在线状态列表项右侧展示待处理事项的数量标记卡片或内容区域用状态点success/error/warning表达业务状态。快速上手Badge 作为独立组件从antd包中导出最简单的用法是包裹一个子元素并传入countimport { Badge, Avatar } from antd; const App: React.FC () ( Badge count{5} Avatar shapesquare sizelarge / /Badge );完整可运行示例可参考仓库中的 基本用法演示其中还演示了count{0} showZero强制展示零值以及把count直接传一个 ReactNode如ClockCircleOutlined /实现自定义图标徽标的能力。Badge API通用属性参考通用属性。Badge 组件对外暴露的核心属性如下表参数说明类型默认值版本color自定义小圆点的颜色string-count展示的数字大于 overflowCount 时显示为${overflowCount}为 0 时隐藏ReactNode-classNames语义化结构 classRecordSemanticDOM, string-5.7.0dot不展示数字只有一个小红点booleanfalseoffset设置状态点的位置偏移[number, number]-overflowCount展示封顶的数字值number99showZero当数值为 0 时是否展示 Badgebooleanfalsesize在设置了count的前提下有效设置小圆点的大小default|small--status设置 Badge 为状态点success|processing|default|error|warning-styles语义化结构 styleRecordSemanticDOM, CSSProperties-5.7.0text在设置了status的前提下有效设置状态点的文本ReactNode-title设置鼠标放在状态点上时显示的文字string-核心属性详解count展示的数字默认值为null源码中count null见 index.tsx。计数逻辑遵循三条规则大于overflowCount时显示为${overflowCount}为 0 时隐藏除非设置showZero传入ReactNode时直接渲染自定义内容例如 basic.tsx 中传入ClockCircleOutlined style{{ color: #f5222d }} /。从源码看index.tsx展示值由numberedDisplayCount计算count overflowCount ? \${overflowCount} : count随后isZero、ignoreCount、isHidden等布尔量共同决定徽标是否渲染。特别地负数和字符串数字如-10、-10、3.5也能正确展示测试用例见 index.test.tsx 与 index.test.tsx。overflowCount封顶数字值默认99当 count 超过该值时显示${overflowCount}。参考 封顶数字演示Badge count{99} / Badge count{100} / {/* 显示 99 */} Badge count{99} overflowCount{10} / {/* 显示 10 */} Badge count{1000} overflowCount{999} / {/* 显示 999 */}dot小红点设置为true时不展示数字只显示一个小红点。参考 讨嫌的小红点演示。注意两个边界行为源码与测试均已覆盖dot在count为 0 时不展示showAsDot dot !isZero见 index.tsx且 dot 模式下不会因为位数多而加宽为“多字符胶囊”样式测试见 index.test.tsx。showZero是否展示零值默认false即count{0}时徽标整体隐藏。设置为true后可展示数字 0参考 basic.tsx 中的Badge count{0} showZero。size徽标大小在设置了count的前提下有效取值default或small。参考 大小演示。源码中size small会额外追加${prefixCls}-count-sm样式类index.tsx其视觉差异由样式文件定义见下文主题变量部分。offset位置偏移类型为[number, number]分别表示水平与垂直偏移。参考 自定义位置偏移演示Badge count{5} offset{[10, 10]} Avatar shapesquare sizelarge / /Badge源码中偏移的实现值得注意index.tsx垂直方向通过marginTop: offset[1]实现水平方向根据ConfigContext中的direction判断——LTR 下设置right -parseInt(offset[0])RTL 下设置left parseInt(offset[0])从而天然适配从右到左的阅读方向。offset同样支持传入 ReactNode 作为 count 的场景index.test.tsx。status状态点取值success|processing|default|error|warning参考 状态点演示Badge statussuccess / Badge statusprocessing / Badge statuserror textError /状态点可搭配text展示文字如textError也可单独使用。源码中hasStatus判定index.tsx说明只有当status或color被设置、且count为空ignoreCount时组件才会以“状态点”模式渲染即根节点只渲染状态圆点与文本不包裹 children。其中processing状态带有一个循环扩散的脉冲动画。title悬浮提示设置鼠标悬停在徽标上时显示的文字。默认情况下若未显式传title会取当前展示的数值作为 titleindex.tsx。参考 自定义标题演示测试覆盖见 index.test.tsx。color自定义颜色既可用于数字徽标count 模式也可用于状态点。支持两种写法预设色名pink、red、yellow、orange、cyan、green、blue、purple、geekblue、magenta、volcano、gold、lime完整预设列表见 theme/interface/presetColors.ts任意 CSS 颜色值#f50、rgb(...)、hsl(...)、hwb(...)均可。参考 多彩徽标演示。源码中通过isPresetColor(color, false)来自 _util/colors.ts区分预设色与自定义色预设色走genPresetColor生成的样式类如.ant-badge-color-red自定义色则以内联样式background/color直接写入index.tsx。classNames / styles语义化结构定制5.7.0用于对 Badge 内部结构做细粒度样式定制详见下文 Semantic DOM。Badge.Ribbon APIRibbon缎带通过Badge.Ribbon子组件使用可将一个文本缎带贴在卡片等容器的右上角/左上角参数说明类型默认值版本color自定义缎带的颜色string-placement缎带的位置start和end随文字方向RTL 或 LTR变动start|endendtext缎带中填入的内容ReactNode-参考 缎带演示Badge.Ribbon textHippies Card titlePushes open the window sizesmall and raises the spyglass. /Card /Badge.Ribbon Badge.Ribbon textHippies colorpink Card titlePushes open the window sizesmall and raises the spyglass. /Card /Badge.Ribbon从源码看Ribbon.tsxRibbon 的实现要点placement默认end渲染类名${prefixCls}-placement-${placement}预设色复用isPresetColor判定生成-color-*类自定义色直接写入background缎带主体与“折角”corner分离渲染corner元素通过边框 badgeRibbonCornerTransform: scaleY(0.75)与badgeRibbonCornerFilter: brightness(75%)实现立体折角效果见 style/ribbon.tsRTL 环境下自动追加${prefixCls}-rtl类start/end位置随文字方向对调Ribbon.tsx。Semantic DOM从 5.7.0 版本开始Badge 提供语义化 DOM 结构可通过classNames与styles精确命中内部节点节点说明版本root根节点5.7.0indicator指示器节点徽标数字/圆点本身5.7.0对应源码中的类型定义index.tsxclassNames?: { root?: string; indicator?: string; }; styles?: { root?: React.CSSProperties; indicator?: React.CSSProperties; };参考 语义化结构演示。使用示例Badge count{5} classNames{{ root: my-badge-root, indicator: my-badge-indicator }} styles{{ indicator: { background: #52c41a } }} Avatar shapesquare sizelarge / /Badge源码中classNames.root与styles.root会被合并到根span上classNames.indicator与styles.indicator会被合并到内部状态点status-dot或滚动数字scroll-number节点上index.tsx。此外ConfigProvider同样支持通过badge.classNames/badge.styles为全局 Badge 统一注入语义化样式。主题变量Design TokenBadge 组件支持通过 ConfigProvider 的theme.components.Badge配置组件级 Token。参考 组件 Token 演示ConfigProvider theme{{ components: { Badge: { indicatorHeight: 24, indicatorHeightSM: 18, dotSize: 4, textFontWeight: bold, statusSize: 8, }, }, }} {/* ... */} /ConfigProvider组件级 Token 的完整定义与默认值见 style/index.ts 与prepareComponentTokenstyle/index.tsToken说明默认值计算indicatorZIndex徽标 z-indexautoindicatorHeight徽标高度Math.round(fontSize * lineHeight) - 2 * lineWidthindicatorHeightSM小号徽标高度fontSizedotSize点状徽标尺寸fontSizeSM / 2textFontSize徽标文本尺寸fontSizeSMtextFontSizeSM小号徽标文本尺寸fontSizeSMtextFontWeight徽标文本粗细normalstatusSize状态徽标尺寸fontSizeSM / 2同时 Badge 还依赖若干全局派生 Token见prepareTokenstyle/index.ts其中几个值得关注badgeColor徽标默认背景色取全局colorError红色系这也是数字徽标默认是红色的原因badgeColorHoverhover 时的背景色取colorErrorHoverbadgeTextColor徽标文字颜色取colorBgContainer通常为白色badgeProcessingDurationprocessing状态脉冲动画周期固定1.2sbadgeShadowSize/badgeShadowColor徽标外圈描边用 box-shadow 模拟细边框取全局lineWidth与colorBorderBg。数字滚动动画原理Badge 的数字切换带有一个逐位“滚动/翻牌”动画这是它区别于普通角标的最大视觉特征。整体渲染链路为外层InternalBadge通过CSSMotionrc-motion控制徽标的出现/消失缩放动画-zoom系列motionDeadline{1000}见 index.tsx数字部分交由 ScrollNumber.tsx 渲染为sup元素内部将数字字符串按字符拆分每个字符由 SingleNumber.tsx 负责逐位滚动它先生成从旧值到新值的一段连续数字单位列表UnitNumber再通过transform: translateY(...)将容器偏移到目标位置onTransitionEnd后收敛为静态单位。关键实现细节SingleNumber.tsx仅对整数启用逐位滚动count Number(count) % 1 0ScrollNumber.tsx浮点数如3.5直接整体渲染滚动方向由新旧 count 大小决定unit prevCount count ? 1 : -1并计算从旧值滚到新值的最短路径偏移getOffset若浏览器不支持 transitionend 事件则用 1000ms 定时器兜底SingleNumber.tsx为了兼容旧用法Badge count{4} style{{ borderColor: #d9d9d9 }} /当样式里带borderColor时ScrollNumber 会用boxShadow: 0 0 0 1px borderColor inset模拟边框ScrollNumber.tsx对应测试见 index.test.tsx。此外出现/消失与 processing 脉冲动画均在样式文件中以 Keyframes 定义antZoomBadgeIn/Out、antNoWrapperZoomBadgeIn/Out、antStatusProcessing、antBadgeLoadingCircle见 style/index.tsprocessing状态通过::after伪元素循环scale(0.8 → 2.4)并渐隐实现呼吸扩散效果style/index.ts。常用组合场景独立使用not-a-wrapperBadge 可以不包裹任何子元素独立存在count 或 status 模式此时自动追加ant-badge-not-a-wrapper类index.tsx样式上徽标不再绝对定位、而是作为行内元素参与布局style/index.ts并且缩放动画的原点变为自身中心。参考 独立使用演示Badge count{show ? 11 : 0} showZero color#faad14 / Badge count{show ? 25 : 0} /动态切换用 state 驱动 count 变化即可实现动态徽标配合减/加/随机按钮体验数字滚动动画。参考 动态演示其中用Switch控制dot的显隐演示动画的进入与离开。注意源码中徽标隐藏后仍会缓存最后一次的 count 与 dot 状态countRef、displayCountRef、isDotRef见 index.tsx避免离场动画期间数字闪变。可点击将 Badge 包进a即可实现整体可点击link.tsxa href# Badge count{5} Avatar shapesquare sizelarge / /Badge /a样式文件同时定义了a:hover 下的背景变化badgeColorHover保证 hover 时徽标有反馈style/index.ts。与 Tooltip 组合Badge 可与 Tooltip 自由组合例如在错误状态点上悬浮提示修复信息相关测试见 index.test.tsx。测试与验证仓库为 Badge 提供了完整的测试覆盖位于 components/badge/__tests__index.test.tsx核心行为测试包括 mount/rtl 基础测试、float/负数展示、dot 边界、自定义 title、offset 与 ReactNode count 组合、与 Tooltip 组合、数字变化动画快照、borderColor 兼容等ribbon.test.tsx缎带行为测试demo.test.tsx 与 demo-extend.test.tsx对全部官方 demo 的渲染与快照回归image.test.ts视觉回归测试。总结Badge 虽是一个小组件但信息密度很高从 API 层面看它同时支持数字徽标、小红点、状态点、多彩徽标与缎带五种形态从实现层面看它内部封装了 rc-motion 缩放动画、逐位数字滚动、RTL 适配、预设色系统与组件级 Design Token。理解 index.tsx 中count/overflowCount/showZero/dot的联动判定逻辑、SingleNumber.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），仅供参考