Ant Design FloatButton 徽标（Badge）实战：为悬浮按钮添加数字与圆点通知

在 Ant Design 中，FloatButton 作为悬浮于页面角落的常驻按钮，经常承担「反馈入口」「快捷操作」等职责。当需要提示新消息数量或未读状态时，可直接在 FloatButton 上挂载 Badge。官方 badge 示例（demo/badge.md 与 demo/badge.tsx）展示的就是这一能力：阅读完本文，你将掌握 badge 属性的全部用法，包括 dot 圆点模式、count 数字模式、overflowCount 封顶策略、徽标颜色定制，以及多个悬浮按钮/按钮组并排时避免视觉重叠的布局技巧。

示例全景：三种典型徽标形态

该 Demo 的完整源码位于 components/float-button/demo/badge.tsx，同时渲染了三组按钮，覆盖了徽标在 FloatButton 上最典型的三种应用场景：

import React from 'react';
import { QuestionCircleOutlined } from '@ant-design/icons';
import { FloatButton } from 'antd';

const App: React.FC = () => (
  <>
    <FloatButton shape="circle" style={{ insetInlineEnd: 24 + 70 + 70 }} badge={{ dot: true }} />
    <FloatButton.Group shape="circle" style={{ insetInlineEnd: 24 + 70 }}>
      <FloatButton tooltip={<div>custom badge color</div>} badge={{ count: 5, color: 'blue' }} />
      <FloatButton badge={{ count: 5 }} />
    </FloatButton.Group>
    <FloatButton.Group shape="circle">
      <FloatButton badge={{ count: 12 }} icon={<QuestionCircleOutlined />} />
      <FloatButton badge={{ count: 123, overflowCount: 999 }} />
      <FloatButton.BackTop visibilityHeight={0} />
    </FloatButton.Group>
  </>
);

export default App;

• 圆点模式（dot）：第一个独立的 <FloatButton> 使用 badge={{ dot: true }}，不显示具体数字，仅用一个小红点表达「有新动态」，常用于消息中心、待办提醒等无需精确计数的场景。
• 数字模式（count）：第二个 FloatButton.Group 内的两个按钮分别显示「5」；其中第一个按钮同时通过 color: 'blue' 将徽标染成主题蓝，并通过 tooltip 提示这是自定义颜色的徽标。
• 大数字封顶（overflowCount）：第三个 FloatButton.Group 中，count: 123 正常显示完整数字，而第二个按钮配置了 count: 123, overflowCount: 999。由于 123 未超过封顶值 999，因此完整显示；若计数超过 overflowCount，则会按规则展示为「overflowCount+」（详见下文源码分析）。

需要说明的是，FloatButton.BackTop（BackTop.tsx）在示例中用于构建第三个按钮组的收尾项，其自身不承载 badge 属性，这也体现了「同一悬浮组内可混排普通按钮与回到顶部按钮」的组合灵活性。

badge 属性的类型边界与可用配置

在 Ant Design 的类型设计中，FloatButton 的 badge 并非直接复用完整 BadgeProps，而是经过了类型裁剪。在 FloatButton.tsx 中定义：

export type FloatButtonBadgeProps = Omit<BadgeProps, 'status' | 'text' | 'title' | 'children'>;

也就是说，徽标的 status（状态点）、text（文字徽标）、title、children 四种能力在 FloatButton 上被禁用——原因是这些形态与悬浮按钮小巧、单点的视觉定位不符。结合官方 API 文档（components/float-button/index.en-US.md，badge 自 antd@5.4.0 起支持），以下配置在实际开发中最常用：

配置项	说明	Demo 中的用法
dot	是否仅显示圆点（不渲染数字）	badge={{ dot: true }}
count	徽标展示的数值	badge={{ count: 5 }}
color	徽标背景色（自定义颜色）	badge={{ count: 5, color: 'blue' }}
overflowCount	显示封顶值，超过后展示为 n+ 形式	badge={{ count: 123, overflowCount: 999 }}
className	自定义徽标节点样式类	用于配合语义化样式微调

与 Badge 官方组件（components/badge/Badge.tsx）一致，overflowCount 默认值为 99，渲染逻辑为：当 count > overflowCount 时展示 ${overflowCount}+，否则直接展示 count（Badge.tsx）。因此示例中 count: 123 搭配 overflowCount: 999 仍显示完整数字；若不加该配置，count 超过 99 时会显示为 99+——这正是很多场景中用户困惑「为什么数字变成了 99+」的答案所在。

源码实现：badge 如何在 FloatButton 内部挂载

从实现层面看，badge 并非 FloatButton 自己绘制的，而是组合了 Badge 组件。在 FloatButton.tsx 内部：

const badgeProps = omit(badge, ['title', 'children', 'status', 'text'] as any[]) as typeof badge;

const badgeNode = 'badge' in props && (
  <Badge
    {...badgeProps}
    className={clsx(badgeProps.className, `${prefixCls}-badge`, {
      [`${prefixCls}-badge-dot`]: badgeProps.dot,
    })}
  />
);

这里有两处关键细节值得注意：

1. 双重防御式裁剪：虽然 TS 类型中已通过 Omit 去掉 status/text/title/children，运行时仍会再执行一次 omit（源码注释明确说明这是为了防止多余属性被透传），保证即使调用方绕过类型约束传入这些属性也不会生效。
2. 注入方式：badgeNode 作为 Button 的子节点、紧随 mergedContent 之后渲染（FloatButton.tsx）。整个 FloatButton 底层实际渲染的是 Ant Design 的 <Button>（size="large"），因此徽标节点依附于 Button 根结构；若配置了 tooltip，外层还会再包一层 <Tooltip>，形成 Tooltip → Button → Badge 的嵌套结构。

Badge 节点被追加了 float-btn-badge 类名，圆点模式下额外追加 float-btn-badge-dot，便于样式系统对徽标进行定位与定制。组件测试对此有直接验证：在 components/float-button/tests/index.test.tsx 中，分别断言 .ant-float-btn .ant-badge 下的 .ant-badge-count（数字模式）与 .ant-badge-dot（圆点模式）真实存在于 DOM 结构中，说明徽标复用的是 Ant Design Badge 的既有渲染与样式体系。

布局技巧：多个悬浮按钮组如何错开排布

当页面同时存在「独立悬浮按钮 + 多个悬浮按钮组」时，如果不做处理，它们会全部堆叠在屏幕同一角落。Demo 通过 insetInlineEnd（逻辑属性，在 RTL 场景下会自动翻转为左侧定位）的逐级递增实现了纵向错位：

• 第三个按钮组默认贴边：insetInlineEnd: 24；
• 第二个按钮组向外让出约一个按钮组的宽度：insetInlineEnd: 24 + 70；
• 独立按钮继续外移一层：insetInlineEnd: 24 + 70 + 70。

这种「以常量 70 为步进」的写法（demo/badge.tsx）比硬编码具体像素更易维护，也直观体现了 FloatButton.Group 采用 Flex 纵向排列子按钮的结构特征（见 FloatButtonGroup.tsx：circle 形态下用 <Flex vertical>，square 形态下用 <Space.Compact vertical>）。在按钮组场景中，shape 统一由 FloatButton.Group 的 shape 属性透传给内部所有子按钮——因此 Demo 只写了 Group 上的 shape="circle"，子按钮无需重复声明（FloatButton.tsx 会优先取 GroupContext 中的 shape）。

实战建议小结

• 表达「有无新内容」优先用 dot: true，视觉更轻；需要精确计数时再使用 count。
• 明确 overflowCount 的封顶语义：默认 99，超过即折叠为 99+；若业务数字不会很大（如 Demo 中 123），可上调 overflowCount 以显示完整数字。
• 自定义徽标颜色使用 color 属性，不必覆盖 CSS 变量；若需更深度的主题定制，可参考 Badge 组件的 Design Token。
• 多个悬浮按钮并存时，用 insetInlineEnd 逻辑属性的递增表达式依次错位，兼顾 LTR/RTL。
• title 类原生提示在 FloatButton 的 badge 上不可用，悬浮说明请使用 FloatButton 自带的 tooltip 属性（Demo 即用 tooltip 标注「custom badge color」）。

结合 index.en-US.md 中列出的完整 FloatButton API，可以进一步将 badge 与 type（default/primary）、tooltip、onClick 等属性组合使用，为站点右下角或左侧的悬浮操作区构建信息层级分明的通知体系。