Ant Design FloatButton 完全指南：悬浮按钮、BackTop 与分组菜单的 API 详解及源码实现

本指南以 ant-design 仓库 FloatButton 官方文档 为主体，系统讲解悬浮按钮在“站点全局功能入口、随处可见的快捷操作”两类典型场景中的落地方法。读完本文，你将掌握 FloatButton 单按钮 / Group 菜单模式 / BackTop 回顶三者的全部配置参数、受控与非受控写法，并能结合源码理解其渲染、滚动监听与语义化样式等底层机制。

适用场景（When To Use）

根据官方文档定义，FloatButton（Floating Action Button，FAB）适合以下两种业务诉求：

• 站点全局功能：提供贯穿全站的入口型功能（如在线客服、意见反馈、帮助中心）。
• 随处可触达的按钮：在用户任意浏览位置都能一眼看到并触发的快捷操作（如“回到顶部”“发起会话”）。

它从 antd@5.0.0 开始提供，是页面右下角等位置常驻操作的标准解。默认情况它是一个圆形图标按钮；通过追加 .BackTop、.Group 两个复合子组件，可分别得到“滚动回顶”与“多按钮分组展开”两种增强形态。

最小可用示例

与文档 basic.tsx demo 一致，最简单的写法只需要一个自闭合组件：

import React from 'react';
import { FloatButton } from 'antd';

const App: React.FC = () => <FloatButton onClick={() => console.log('onClick')} />;

export default App;

什么都不传时，组件会渲染为一个默认悬浮在页面右下的圆形按钮，其图标来自组件内置的默认值：源码中当既没有 content 也没有 icon 时，会自动填充 FileTextOutlined（见 FloatButton.tsx 中 mergedIcon 的逻辑）。

通用 API（common API）

官方文档给出的通用属性表如下，涵盖单按钮与各复合子组件的公共能力：

Property	Description	Type	Default	Version	Global Config
icon	Set the icon component of button	ReactNode	-		FloatButton: ×, BackTop: 5.27.0
classNames	Customize class for each semantic structure inside the component. Supports object or function.	Record<SemanticDOM, string> | (info: { props })=> Record<SemanticDOM, string>	-		6.0.0
content	Text and other	ReactNode	-		×
description	Please use content instead	ReactNode	-		×
tooltip	The text shown in the tooltip	ReactNode | TooltipProps	-	TooltipProps: 5.25.0	×
type	Setting button type	default | primary	default		×
shape	Setting button shape	circle | square	circle		×
styles	Customize inline style for each semantic structure inside the component. Supports object or function.	Record<SemanticDOM, CSSProperties> | (info: { props })=> Record<SemanticDOM, CSSProperties>	-		6.0.0
onClick	Set the handler to handle click event	(event) => void	-		×
href	The target of hyperlink	string	-		×
target	Specifies where to display the linked URL	string	-		×
htmlType	Set the original html type of button, see: MDN	submit | reset | button	button	5.21.0	×
badge	Attach Badge to FloatButton. status and other props related are not supported.	BadgeProps	-	5.4.0	×
disabled	Whether the button is disabled	boolean	-	6.4.0	×

对照 FloatButton.tsx 中的 FloatButtonProps 类型定义，可以逐一确认上述属性的真实含义：

• icon：按钮图标节点。注意表格中 Global Config 列的差异——FloatButton 的 icon 不支持在全局组件配置中预设，而 FloatButton.BackTop 自 5.27.0 起支持（即通过 useComponentConfig('floatButton') 读取全局 backTopIcon，见 BackTop.tsx）。
• content 与 description：description 已废弃，应使用 content。源码中 mergedContent = content ?? description 保证迁移期兼容，并在开发环境抛出 description → content 的 deprecated 警告（见 [FloatButton.tsx](https://gitcode.com/GitHub_Trending/an/ant-design/blob/58b0ee1554835b3ea2d0541f4986306f3d70d0ce/components/float-button/FloatButton.tsx?utm_source=gitcode_repo_files#L110-L111, L170)）。
• type / shape：分别控制配色（default/primary）与外轮廓（circle 圆形/square 方形），默认 default 与 circle。源码会将它们拼入 float-btn-default、float-btn-circle 等 class（见 FloatButton.tsx）。
• tooltip：从 5.25.0 起既支持直接传字符串，也支持完整的 TooltipProps 对象，内部通过 convertToTooltipProps 归一化后包裹一层 Tooltip（见 [FloatButton.tsx](https://gitcode.com/GitHub_Trending/an/ant-design/blob/58b0ee1554835b3ea2d0541f4986306f3d70d0ce/components/float-button/FloatButton.tsx?utm_source=gitcode_repo_files#L157-L158, L209-L211)）。
• badge：自 5.4.0 支持为按钮挂角标。类型上已排除 status/text/title/children，运行时还会再 omit 一次以防透传（见 [FloatButton.tsx](https://gitcode.com/GitHub_Trending/an/ant-design/blob/58b0ee1554835b3ea2d0541f4986306f3d70d0ce/components/float-button/FloatButton.tsx?utm_source=gitcode_repo_files#L38, L145-L155)）。
• htmlType：自 5.21.0 支持透传原生 button 的 submit / reset / button 类型。

type / shape / content 的组合示例

官方提供了对应 demo：

• 视觉风格：type.tsx
• 外轮廓切换：shape.tsx
• 带文字内容：content.tsx
• 带 Tooltip 提示：tooltip.tsx

需要特别注意的是圆形按钮承载文字的限制。源码中给出了明确的开发期警告：content 仅在 shape === 'square' 时被支持（FloatButton.tsx 中的 usage 警告），原因正如警告文案所说——圆形空间狭窄，若确有文字需求应使用方形并保持文案简短。同时，当没有可渲染的 content 时组件会带上 float-btn-icon-only 类，此时按钮退化为纯图标形态。

FloatButton.Group：分组与菜单模式

多操作聚合时使用分组。官方文档的 API 表如下：

Property	Description	Type	Default	Version	Global Config
open	Whether the menu is visible or not, use it with trigger	boolean	-		×
closeIcon	Customize close button icon	React.ReactNode	<CloseOutlined />		5.16.0
placement	Customize menu animation placement	top | left | right | bottom	top	5.21.0	×
shape	Setting button shape of children	circle | square	circle		×
trigger	Which action can trigger menu open/close	click | hover	-		×
onOpenChange	Callback executed when active menu is changed, use it with trigger	(open: boolean) => void	-		×
onClick	Set the handler to handle click event (only work in Menu mode)	(event) => void	-	5.3.0	×

Group 有两种基本形态，在源码中用 isMenuMode（即传入 trigger）区分（见 FloatButtonGroup.tsx）：

• 普通分组：不传 trigger，子按钮以列表形式常驻展示（demo 见 group.tsx）。当子项为圆形时使用 Flex 独立排列，方形时则以 Space.Compact 无缝拼接。
• 菜单模式：传入 trigger="click" 或 trigger="hover"，出现一个主按钮，展开/收起浮层中的子按钮（demo 见 group-menu.tsx），列表展开动画基于 CSSMotion 完成。

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

const App: React.FC = () => (
  <>
    <FloatButton.Group
      trigger="click"
      type="primary"
      style={{ insetInlineEnd: 24 }}
      icon={<CustomerServiceOutlined />}
    >
      <FloatButton />
      <FloatButton icon={<CommentOutlined />} />
    </FloatButton.Group>
    <FloatButton.Group
      trigger="hover"
      type="primary"
      style={{ insetInlineEnd: 94 }}
      icon={<CustomerServiceOutlined />}
    >
      <FloatButton />
      <FloatButton icon={<CommentOutlined />} />
    </FloatButton.Group>
  </>
);

export default App;

上例与仓库 group-menu.tsx 一致，需要注意：菜单模式下两个开关动作会改变主按钮图标——展开时主按钮图标替换为 closeIcon（默认 <CloseOutlined />，自 5.16.0 可自定义，也支持全局 ConfigProvider 的 closeIcon 配置）。

受控 open 与 placement

• 受控模式：open 必须与 trigger 配合使用，否则开发环境会给出 'open' need to be used together with 'trigger' 警告。源码用 useControlledState(false, customOpen) 实现受控/非受控双模式，内部状态变化时回调 onOpenChange；click 触发下还注册了 document 级捕获监听，点击 Group 外部区域自动收起（见 [FloatButtonGroup.tsx](https://gitcode.com/GitHub_Trending/an/ant-design/blob/58b0ee1554835b3ea2d0541f4986306f3d70d0ce/components/float-button/FloatButtonGroup.tsx?utm_source=gitcode_repo_files#L137, L173-L185)）。完整示例见 controlled.tsx：

const [open, setOpen] = useState<boolean>(true);
// ...
<FloatButton.Group
  open={open}
  trigger="click"
  style={{ insetInlineEnd: 24 }}
  icon={<CustomerServiceOutlined />}
>
  <FloatButton />
  <FloatButton />
  <FloatButton icon={<CommentOutlined />} />
</FloatButton.Group>

• placement（5.21.0）：控制菜单浮层相对主按钮展开的方向，取 top / left / right / bottom，默认 top。源码在渲染前对非法值做兜底回退到 top（见 FloatButtonGroup.tsx），并且 top/bottom 时列表为纵向排列，left/right 时为横向排列。四种方向组合效果见 placement.tsx。
• disabled（6.4.0）：Group 会读取 ConfigProvider 的 DisabledContext，未显式传入 disabled 时继承全局禁用状态（见 FloatButtonGroup.tsx），禁用期间 triggerOpen 直接短路返回。

FloatButton.BackTop：回到顶部

BackTop 是 FloatButton 在“回顶”场景的封装，官方文档 API 表如下：

Property	Description	Type	Default	Version
duration	Time to return to top (ms). This property is ignored when enables reduced motion (prefers-reduced-motion: reduce)	number	450
showProgress	Show the current scroll progress ring around the BackTop button edge	boolean	false	6.6.0
target	Specifies the scrollable area dom node	() => HTMLElement	() => window
visibilityHeight	The BackTop button will not show until the scroll height reaches this value	number	400
onClick	A callback function, which can be executed when you click the button	() => void	-

典型用法是放在一个足够高（如 300vh）的容器内滚动验证，见 back-top.tsx：

import React from 'react';
import { FloatButton } from 'antd';

const Demo: React.FC = () => {
  return (
    <div style={{ height: '300vh', padding: 10 }}>
      <div>Scroll to bottom</div>
      {/* ... */}
      <FloatButton.BackTop style={{ insetInlineEnd: 24 }} shape="circle" />
      <FloatButton.BackTop style={{ insetInlineEnd: 88 }} shape="square" />
    </div>
  );
};

export default Demo;

对照 BackTop.tsx 的默认值实现，可以确认几个关键行为：

• visibilityHeight：默认 400，即滚动高度不足 400px 时按钮通过 CSSMotion（ant-fade 动效）隐藏；传入 0 则始终展示。滚动可见性由 useScroll.ts 中的 useScroll Hook 计算，该 Hook 内部用 throttleByAnimationFrame 对 scroll 事件做逐帧节流，并在 showProgress 开启时额外监听 resize 以重算进度。
• duration：默认 450ms 回到顶部。源码在点击时会检测 prefers-reduced-motion: reduce，若用户系统开启“减少动态效果”，则滚动时长降为 0（见 BackTop.tsx），对应表格中“降低动态效果时忽略该值”的说明；实际滚动由 _util/scrollTo 完成。
• showProgress（6.6.0）：围绕按钮边缘显示当前滚动进度圆环，如 progress-ring.tsx 所示。其原理是源码通过 CSS 变量注入圆环“走多少圈”：在 useScroll.ts 中按 scrollTop / (scrollHeight - clientHeight) 计算 0~1 的进度，再渲染为 ${scrollProgress}turn 的 progress CSS 变量（见 BackTop.tsx），圆环样式定义于 style 目录。
• target：默认返回 window，用于指定非窗口滚动容器，在 iframe 等场景下可通过 ownerDocument 自动定位。
• icon：BackTop 的默认图标为 VerticalAlignTopOutlined（见 BackTop.tsx），自 5.27.0 起可经全局配置覆写。
• badge：也可像普通按钮一样挂角标，用法参考 badge.tsx（debug 模式的圆点形态见 badge-debug.tsx）。

draggable 与自定义内容形态

• draggable：官方提供 draggable.tsx 演示将悬浮按钮设置为可拖拽（文档示例以 iframe 独立预览），适用于需要在页面内移动快捷入口的场景。该能力依赖 CSS inset 定位与拖拽事件处理，直接基于 FloatButton 本体使用。
• 自定义内容：除图标外，content 可放入任意 ReactNode（content.tsx），配合方形 shape 可承载图标 + 文案的复合信息。

Semantic DOM 语义化结构与 classNames / styles

自 6.0.0 起，FloatButton 及其 Group 支持“语义化结构定制”，即通过 classNames / styles 精准命中组件内部每一层 DOM 结构，支持传对象或接收 { props } 的函数两种写法。

FloatButton 的语义节点（继承自 Button 结构，见 [FloatButton.tsx](https://gitcode.com/GitHub_Trending/an/ant-design/blob/58b0ee1554835b3ea2d0541f4986306f3d70d0ce/components/float-button/FloatButton.tsx?utm_source=gitcode_repo_files#L122-L125, L127-L133) 的语义合并逻辑）包括：root、icon、content。

FloatButton.Group 的语义节点则由源码 FloatButtonGroup.tsx 的 FloatButtonGroupSemanticType 显式声明，共 8 个：

语义节点	作用范围
root	Group 最外层容器
list	子按钮列表容器
item / itemIcon / itemContent	列表内每个子按钮及其图标、内容
trigger / triggerIcon / triggerContent	菜单模式下的主触发按钮及其图标、内容

Group 内部正是通过 GroupContext（见 context.ts）将列表项、触发器各自的 classNames/styles 分别派发给对应的子 FloatButton。演示代码见 _semantic.tsx 与 _semantic_group.tsx；完整的自定义样式示例见 style-class.tsx。

源码级原理补充

从 index.tsx 可以看到组件体系的组装方式：FloatButton.Group、FloatButton.BackTop 以及仅供内部快照使用的 FloatButton._InternalPanelDoNotUseOrYouWillBeFired（对应 PurePanel.tsx）均以命名属性挂载在 FloatButton 上，构成复合组件。进一步阅读 FloatButton.tsx 可发现两个实现细节：

• 底层复用 Button：FloatButton 实际渲染的是 antd Button（固定 size="large"），因此自带 Button 的波浪点击反馈、语义样式与无障碍基础；类名前缀统一为 float-btn（floatButtonPrefixCls）。
• 层级与 RTL：组件通过 useZIndex('FloatButton', style?.zIndex) 参与统一层级管理；当 ConfigProvider 传入 direction="rtl" 时会追加 float-btn-rtl 类，配合 insetInlineEnd 等逻辑属性实现镜像布局（见 [FloatButton.tsx](https://gitcode.com/GitHub_Trending/an/ant-design/blob/58b0ee1554835b3ea2d0541f4986306f3d70d0ce/components/float-button/FloatButton.tsx?utm_source=gitcode_repo_files#L140-L142, L189)）。

Design Token

FloatButton 组件参与 antd 的主题 Token 体系，文档页通过 <ComponentTokenTable component="FloatButton"> 自动渲染其全部组件级 Token（源码样式定义位于 style 目录）。定制主题时，可在 ConfigProvider 的 theme.components.FloatButton 中覆盖这些 Token，使悬浮按钮与整套品牌色、圆角、阴影体系保持一致。

小结

本文从文档出发、以源码佐证，覆盖了 FloatButton 的完整形态：

• 单按钮：图标/内容/类型/形状/徽标/禁用/Tooltip 等通用 API；
• Group 分组：常驻列表与 click/hover 菜单模式、受控 open、四种 placement；
• BackTop 回顶：visibilityHeight 显隐阈值、duration 缓动与无障碍降级、6.6.0 的 showProgress 滚动进度环；
• 定制能力：Semantic DOM + classNames/styles 语义化定制。

需要完整查看每个场景的可运行代码时，可直接进入仓库 components/float-button/demo 目录按需阅读对应的 .tsx 示例。