Ant Design Vue Badge 徽标组件完全指南count 计数、状态点与 Ribbon 缎带实战【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址: https://gitcode.com/gh_mirrors/an/ant-design-vueBadge徽标是 Ant Design Vue 中用于在通知图标、用户头像等 UI 元素旁展示小数值或状态描述的组件通常承担未读消息数量这类需要抓人眼球的信息展示。本篇指南以 components/badge/index.en_US.md 官方文档为骨架结合仓库中 Badge.tsx、Ribbon.tsx、ScrollNumber.tsx 的源码实现与demo/目录下的真实示例带你掌握 Badge 全部 API 的用法、数字滚动动效原理、状态点与 Ribbon 缎带的完整实战方案。When To Use什么场景下使用 BadgeBadge 通常出现在通知图标或用户头像附近凭借醒目的视觉表现红点、数字徽标、彩色缎带来吸引用户注意力最典型的场景就是展示未读消息数量。当 count 为0时徽标默认隐藏但可通过showZero强制显示这一细节在 demo/basic.vue 中有最直观的演示。快速上手两种基本用法官方文档给出了两种最基本的写法——包裹式与独立式。包裹式将徽标嵌套在任意子元素上徽标出现在其右上角。a-badge :count5 a href# classhead-example / /a-badge独立式不包裹任何子元素徽标独立渲染为一个小数字气泡。a-badge :count5 /对应到源码 Badge.tsx组件会通过flattenChildren(slots.default?.())判断是否存在默认插槽子节点有子节点时渲染为包装器并添加badge-not-a-wrapper之外的常规样式无子节点时添加badge-not-a-wrapper类名demo/no-wrapper.vue 展示了独立使用时的自定义样式玩法a-badge count25 / a-badge count4 :number-style{ backgroundColor: #fff, color: #999, boxShadow: 0 0 0 1px #d9d9d9 inset, } / a-badge count109 :number-style{ backgroundColor: #52c41a } /Badge API 完整参数详解下表完整继承自官方文档并补充了源码层面的默认值与类型信息源码见 badgePropsPropertyDescriptionTypeDefaultVersioncolor自定义徽标圆点颜色string-1.5.0count徽标中显示的数字number | string | slotdot是否以红点代替count显示booleanfalseoffset徽标圆点偏移量如 [x, y][number | string, number | string]-overflowCount最大显示数量number99showZerocount为 0 时是否显示徽标booleanfalsestatus将 Badge 设为状态点success|processing|default|error|warningtext设置status时状态点旁的展示文本stringnumberStyle设置数字气泡的显示样式objecttitle鼠标悬停时显示的文字stringcountcount数字徽标与插槽count支持数字、字符串和插槽三种形态。当传入插槽时可以自定义徽标内容例如 demo/basic.vue 中放入一个时钟图标a-badge template #count clock-circle-outlined stylecolor: #f5222d / /template a-avatar shapesquare sizelarge / /a-badge源码层面Badge.tsx 会通过typeof count object || (count undefined slots.count)判断是否渲染自定义组件节点并透传mergedStyle样式。overflowCount数字封顶当count超过overflowCount时显示为${overflowCount}默认封顶值为99。源码中的实现位于 Badge.tsxconst numberedDisplayCount computed(() { return ( (props.count as number) (props.overflowCount as number) ? ${props.overflowCount} : props.count ) as string | number | null; });demo/overflow.vue 给出了封顶的实际效果对比a-badge :count99 a-avatar shapesquare sizelarge / /a-badge a-badge :count100 a-avatar shapesquare sizelarge / /a-badge a-badge :count99 :overflow-count10 a-avatar shapesquare sizelarge / /a-badge a-badge :count1000 :overflow-count999 a-avatar shapesquare sizelarge / /a-badgecount为 100 时默认显示99而设置:overflow-count10后 count 为 99 即显示10。dot讨嫌的小红点不显示具体数字仅显示一个红点适合有新内容但无需告知数量的场景。需要注意当 count 为 0 时不显示红点demo/dot.vue 文档注释明确说明 If count equals 0, it wont display the dot。源码通过 Badge.tsx 的showAsDot computed(() props.dot !isZero.value)实现这一规则。a-badge dot notification-outlined stylefont-size: 16px / /a-badge a-badge dot a href#Link something/a /a-badgeoffset徽标位置偏移offset接收[x, y]二元数组调整徽标相对默认位置的偏移。源码实现Badge.tsx揭示了底层细节y 方向通过marginTop实现x 方向通过负的rightLTR 方向实现若 y 值为数字会自动补上px单位。同时组件从 ConfigProvider 读取direction在 RTL 环境下 x 偏移自动切换为left体现了对 RTL 布局的完整适配。a-badge :count5 :offset[10, 10] a-avatar shapesquare sizelarge / /a-badgeshowZero零值是否展示默认false——count为 0 时徽标隐藏。设置showZero后即使 count 为 0 也会显示。相关判断逻辑见 Badge.tsx 与 Badge.tsx其中isHidden同时考虑了mergedCount为空和零值两种情况。a-badge count0 show-zero a-avatar shapesquare sizelarge / /a-badgetitle悬停提示鼠标悬停在徽标上时显示的提示文本默认取count值。源码 Badge.tsx 中titleNode title ?? (typeof count string || typeof count number ? count : undefined)即未显式指定时回退到 count 本身并将该值透传给内部的 ScrollNumber 作为sup标签的title属性。color / status / text状态点三件套当设置status或color且没有包裹子元素时Badge 渲染为一个独立的状态圆点可选status值包括success、processing、default、error、warningtext用于设置状态点旁的描述文字。完整示例见 demo/status.vuea-badge statussuccess / a-badge statuserror / a-badge statusdefault / a-badge statusprocessing / a-badge statuswarning / a-badge statussuccess textSuccess / a-badge statuserror textError / a-badge statusdefault textDefault / a-badge statusprocessing textProcessing / a-badge statuswarning textwarning /源码实现上Badge.tsx 在无子节点且有状态时直接渲染状态点分支使用isPresetColor判断color是否为预设色见 _util/colors.ts预设色通过badge-status-${status}、badge-color-${color}类名走 CSS 变量渲染自定义颜色则通过statusStyle内联background与color实现见 Badge.tsx。数字滚动动效底层实现原理这是 Badge 最具标志性的交互细节。当count动态变化时数字会以垂直滚动的动画方式过渡参考 demo/change.vue 的动态示例。整条调用链分为三层Badge.tsx负责计算展示值displayCount与显隐状态并通过getTransitionProps为数字气泡包裹 zoom 过渡Badge.tsx同时用livingCount缓存 count确保移除动画期间数字不闪烁Badge.tsx。ScrollNumber.tsx判断 count 是否为整数Number(count) % 1 0仅对整数启用逐位拆分渲染——每个数字位通过 SingleNumber.tsx 独立渲染非整数或自定义节点则直接透传ScrollNumber.tsx。另外它还兼容旧用法传入borderColor样式时自动用boxShadow: 0 0 0 1px ${borderColor} inset模拟边框ScrollNumber.tsx。SingleNumber.tsx是滚动动画的核心当数字变化时它按% 10生成当前位到当前值10的一列数字单元用translateY负向偏移实现滚动并通过getOffset计算滚动距离还提供了transitionend事件与 1000ms 定时器兜底防止不支持过渡事件的浏览器卡住状态SingleNumber.tsx。这套整数拆位 translateY 滚动的方案让徽标数字在增减时保持顺滑而不跳动。Badge.Ribbon 缎带2.0.1Ribbon 是 Badge 的附加组件以缎带形态贴在内容块边缘常用于商品标签、优惠标识等场景。注册方式上index.ts 在Badge.install中同时注册了Badge与Ribbon两个组件因此可以直接使用a-badge-ribbon标签。Ribbon 参数详解PropertyDescriptionTypeDefaultVersioncolor自定义缎带颜色string-placement缎带位置start与end跟随文本方向RTL 或 LTRstart|endendtext缎带内容string | VNode | slot-源码 Ribbon.tsx 中placement默认值为end并同样使用isPresetColor区分预设色与自定义色预设色通过ribbon-color-${color}类名渲染自定义色内联background缎带折角处通过ribbon-corner元素配合cornerColorStyle.color呈现同色折角Ribbon.tsx。Ribbon 实战示例demo/ribbon.vue 给出了完整用法支持pink、red、cyan、green、purple、volcano、magenta等预设色a-space directionvertical stylewidth: 100% a-badge-ribbon textHippies a-card titlePushes open the window sizesmalland raises the spyglass./a-card /a-badge-ribbon a-badge-ribbon textHippies colorpink a-card titlePushes open the window sizesmalland raises the spyglass./a-card /a-badge-ribbon a-badge-ribbon textHippies colorvolcano a-card titlePushes open the window sizesmalland raises the spyglass./a-card /a-badge-ribbon a-badge-ribbon textHippies colormagenta a-card titlePushes open the window sizesmalland raises the spyglass./a-card /a-badge-ribbon /a-spacetext同时支持插槽写法源码中span classribbon-text{props.text || slots.text?.()}/span会优先渲染 prop否则渲染#text插槽Ribbon.tsx因此可以传入任意 VNode 或模板内容实现富文本缎带。源码结构速览与扩展阅读组件入口components/badge/index.ts —— 同时导出Badge与BadgeRibbon即Ribbon并注册为插件核心实现components/badge/Badge.tsx —— 计数、封顶、显隐、状态点全部逻辑所在滚动数字components/badge/ScrollNumber.tsx 与 components/badge/SingleNumber.tsx —— 整数拆位与 translateY 滚动动画缎带组件components/badge/Ribbon.tsx官方文档components/badge/index.en_US.md 与 components/badge/index.zh-CN.md全部示例components/badge/demo 下的 11 个.vue文件覆盖 basic、change、colors、dot、link、no-wrapper、overflow、ribbon、status、title 等完整场景。样式方面Badge 使用组件级 CSS-in-JSuseStyle生成见 components/badge/style并支持从ConfigProvider注入主题 token 与 RTL 方向无需手动引入独立样式文件主题定制可参照 components/config-provider 相关配置。【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址: https://gitcode.com/gh_mirrors/an/ant-design-vue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考