# 悬浮按钮

- 页面: https://jiguang132.com/zh/resources/ant-design/docs/float-button
- 资源: Ant Design (https://jiguang132.com/zh/resources/ant-design.md)
- 全部指南: https://jiguang132.com/zh/resources/ant-design/docs.md

悬浮于页面上方的按钮。


## 何时使用 {#when-to-use}

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

## 代码演示 {#examples}


- 基本 · `basic`
- 类型 · `type`
- 形状 · `shape`
- 描述 · `content`
- 含有气泡卡片的悬浮按钮 · `tooltip`
- 悬浮按钮组 · `group`
- 菜单模式 · `group-menu`
- 受控模式 · `controlled`
- 弹出方向 · `placement`
- 可拖拽 · `draggable`
- 回到顶部 · `back-top`
- 滚动进度 · `progress-ring`
- 徽标数 · `badge`

- 自定义语义结构的样式和类 · `style-class`


## API

通用属性参考：[通用属性](#jguang-common-props)

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

### 共同的 API {#common-api}

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

### FloatButton.Group

| 参数 | 说明 | 类型 | 默认值 | 版本 | [全局配置](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| 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）{#design-token}

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

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

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

```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;
};
```


## 原生通用属性 {#jguang-common-props}


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

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


## 安装并复现示例

```bash
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 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt