悬浮按钮

悬浮于页面上方的按钮。

何时使用

用于网站上的全局功能；
无论浏览到何处都可以看见的按钮。

代码演示

API

通用属性参考：通用属性

自 antd@5.0.0 版本开始提供该组件。

共同的 API

参数	说明	类型	默认值	版本	全局配置
icon	自定义图标	ReactNode	-		FloatButton: ×，BackTop: 5.27.0
classNames	用于自定义组件内部各语义化结构的 class，支持对象或函数	Record<SemanticDOM, string> \| (info: { props })=> Record<SemanticDOM, string>	-		6.0.0
content	文字及其它内容	ReactNode	-		×
~~description~~	请使用 `content` 代替	ReactNode	-		×
tooltip	气泡卡片的内容	ReactNode \| TooltipProps	-	TooltipProps: 5.25.0	×
type	设置按钮类型	`default` \| `primary`	`default`		×
shape	设置按钮形状	`circle` \| `square`	`circle`		×
styles	用于自定义组件内部各语义化结构的行内 style，支持对象或函数	Record<SemanticDOM, CSSProperties> \| (info: { props })=> Record<SemanticDOM, CSSProperties>	-		6.0.0
onClick	点击按钮时的回调	(event) => void	-		×
href	点击跳转的地址，指定此属性 button 的行为和 a 链接一致	string	-		×
target	相当于 a 标签的 target 属性，href 存在时生效	string	-		×
htmlType	设置 `button` 原生的 `type` 值，可选值请参考 HTML 标准	`submit` \| `reset` \| `button`	`button`	5.21.0	×
badge	带徽标数字的悬浮按钮（不支持 `status` 以及相关属性）	BadgeProps	-	5.4.0	×
disabled	按钮是否禁用	boolean	-	6.4.0	×

FloatButton.Group

参数	说明	类型	默认值	版本	全局配置
shape	设置包含的 FloatButton 按钮形状	`circle` \| `square`	`circle`		×
trigger	触发方式（有触发方式为菜单模式）	`click` \| `hover`	-		×
open	受控展开，需配合 trigger 一起使用	boolean	-		×
closeIcon	自定义关闭按钮	React.ReactNode	`<CloseOutlined />`		5.16.0
placement	自定义菜单弹出位置	`top` \| `left` \| `right` \| `bottom`	`top`	5.21.0	×
onOpenChange	展开收起时的回调，需配合 trigger 一起使用	(open: boolean) => void	-		×
onClick	点击按钮时的回调（仅在菜单模式中有效）	(event) => void	-	5.3.0	×

FloatButton.BackTop

参数	说明	类型	默认值	版本
duration	回到顶部所需时间（ms）；开启“减弱动态效果”（`prefers-reduced-motion: reduce`）时不生效	number	450
showProgress	在 BackTop 按钮边缘展示当前滚动进度环	boolean	false	6.6.0
target	设置需要监听其滚动事件的元素	() => HTMLElement	() => window
visibilityHeight	滚动高度达到此参数值才出现 BackTop	number	400
onClick	点击按钮的回调函数	() => void	-

Semantic DOM

FloatButton

语义节点	原生说明	版本
`root`	根元素，设置悬浮按钮的基础样式、形状尺寸、类型主题、固定定位、层级、阴影、间距等容器样式	—
`icon`	图标元素，设置按钮内图标的尺寸、颜色、行高、对齐等图标显示样式	—
`content`	内容元素，设置按钮内文字内容的字体大小、颜色、对齐、换行等文本显示样式	—

语义说明来源: vendor/components/float-button/demo/_semantic.tsx

FloatButton.Group

语义节点	原生说明	版本
`root`	根元素，设置悬浮按钮组的容器样式、固定定位、层级、内边距、间距、方向模式等组合布局样式	—
`list`	列表元素，设置按钮组列表的Flex布局、圆角、阴影、动画过渡、垂直对齐等列表容器样式	—
`item`	列表项元素，设置单个悬浮按钮的样式、尺寸、形状、类型、状态、图标内容等按钮基础样式	—
`itemIcon`	列表项图标元素，设置悬浮按钮内图标的尺寸、颜色、对齐等图标显示样式	—
`itemContent`	列表项内容元素，设置悬浮按钮内文字内容、徽标、描述等内容区域样式	—
`trigger`	触发元素，设置菜单模式下触发按钮的样式、形状、图标、悬停态、展开收起状态等交互样式	—
`triggerIcon`	触发图标元素，设置触发按钮内图标的样式、旋转动画、切换状态等图标交互样式	—
`triggerContent`	触发内容元素，设置触发按钮内容区域的文字、标识、状态指示等内容样式	—

语义说明来源: vendor/components/float-button/demo/_semantic_group.tsx

主题变量（Design Token）

类型、继承关系和原生令牌声明保持固定源码原文；默认值由原生主题计算，并可能受 ConfigProvider 覆盖。本表不伪造静态默认值。

原生 ComponentToken 未声明可直接提取的自有字段；共享令牌或继承关系以以下声明为准。

声明来源: vendor/components/float-button/style/index.ts

import { initFadeMotion } from '../../style/motion/fade';

import type { FullToken, GetDefaultToken } from '../../theme/internal';

import { genStyleHooks, mergeToken } from '../../theme/internal';

import genFloatButtonStyle from './button';

import genGroupStyle from './group';

/** Component only token. Which will handle additional calculation of alias token */
export type ComponentToken = object;

/**
 * @desc FloatButton 组件的 Token
 * @descEN Token for FloatButton component
 */
export type FloatButtonToken = FullToken<'FloatButton'> & {
  /**
   * @desc FloatButton 尺寸
   * @descEN Size of FloatButton
   */
  floatButtonSize: number;
  /**
   * @desc FloatButton 图标尺寸
   * @descEN Icon size of FloatButton
   */
  floatButtonIconSize: number | string;

  // Position
  /**
   * @desc FloatButton 底部内边距
   * @descEN Bottom inset of FloatButton
   */
  floatButtonInsetBlockEnd: number;
  /**
   * @desc FloatButton 右侧内边距
   * @descEN Right inset of FloatButton
   */
  floatButtonInsetInlineEnd: number;
};

原生通用属性

Tips: 以下通用属性适用于 antd 大部分组件，不支持的组件会单独说明。

参数	说明	类型	默认值
style	自定义样式	CSSProperties	-
className	自定义类名	string	-
rootClassName	添加在组件最外层的 className	string	-
autoFocus	自动获取焦点，仅对表单类、链接、交互容器等可聚焦元素生效	boolean	false

安装并复现示例

npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23

使用 ConfigProvider 和原生 App，并单独配置 dayjs 语言。每个示例在查看代码中列出完整源码文件和额外固定依赖。示例名称用于选择演示，不是组件通用属性。主题、语言与 SSR 初始化见资源安装指南。

原生类型参考

源码查看器包含未修改的原生实现和以下声明文件，继承类型仍位于原生包中。代码中的英文注释保留为源码参考。

vendor/components/float-button/BackTop.tsx
vendor/components/float-button/FloatButton.tsx
vendor/components/float-button/FloatButtonGroup.tsx
vendor/components/float-button/PurePanel.tsx
vendor/components/float-button/context.ts
vendor/components/float-button/hooks/useScroll.ts
vendor/components/float-button/style/index.ts

来源与许可

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

保留原生中英文正文与可执行示例；官网专用的嵌入章节和令牌表格在本地展开。Ant Design 使用 MIT 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。