antd FloatButton.Group 弹出方向（placement）完整指南：四种预设与实现原理

导读

浮动按钮（FloatButton）在页面角落提供全局快捷操作入口，而当多个操作需要收纳为**菜单模式（menu mode）**时，子菜单列表的展开方向由 placement 属性控制。本指南以 ant-design 仓库中的 placement 演示文档 为核心，完整讲解 top、right、bottom、left 四种预设的取值与默认行为，并结合 FloatButtonGroup.tsx 与 group.ts 样式源码 剖析其底层实现。读完你将掌握：如何通过 placement 控制 FloatButton.Group 子菜单的弹出方位、代码中各定位参数的实际含义，以及该属性背后的类名生成、vertical 布局切换与 CSS 动画推导逻辑。

placement 是什么：菜单模式下的子列表展开方向

placement 是 FloatButton.Group 的专用属性，其官方定义为“自定义菜单弹出位置 / Customize menu animation placement”，仅在该组件以 菜单模式（即设置了 trigger="click" 或 trigger="hover"）运行、子按钮以弹出列表形式呈现时生效。

它提供四个预设值，默认值为 top：

取值	含义
top（默认）	子菜单列表沿触发按钮向上弹出
right	子菜单列表沿触发按钮向右弹出
bottom	子菜单列表沿触发按钮向下弹出
left	子菜单列表沿触发按钮向左弹出

该属性自 antd@5.21.0 引入（见 index.en-US.md 中 API 表格的 Version 列），演示文档 placement.md 与配套演示 placement.tsx 在组件示例中被标记为 version="5.21.0" 条件展示，即低于该版本时此 Demo 不会出现在文档站点。

完整的官方演示解读

placement.tsx 在一个模拟页面上同时放置了四个 FloatButton.Group，逐一对应 top、right、bottom、left，让你直观对比四种弹出方向。其核心代码如下：

const BOX_SIZE = 100;
const BUTTON_SIZE = 40;

const insetInlineEnd: React.CSSProperties['insetInlineEnd'][] = [
  (BOX_SIZE - BUTTON_SIZE) / 2, // top 组：水平居中
  -(BUTTON_SIZE / 2),           // right 组：贴近右侧边界
  (BOX_SIZE - BUTTON_SIZE) / 2, // bottom 组：水平居中
  BOX_SIZE - BUTTON_SIZE / 2,   // left 组：贴近左侧边界
];

const bottom: React.CSSProperties['bottom'][] = [
  BOX_SIZE - BUTTON_SIZE / 2,   // top 组：贴近容器顶部
  (BOX_SIZE - BUTTON_SIZE) / 2, // right 组：垂直居中
  -BUTTON_SIZE / 2,             // bottom 组：贴近容器底部
  (BOX_SIZE - BUTTON_SIZE) / 2, // left 组：垂直居中
];

const App: React.FC = () => (
  <Flex justify="space-evenly" align="center" style={wrapperStyle}>
    <div style={boxStyle}>
      {(['top', 'right', 'bottom', 'left'] as const).map((placement, i) => {
        const style: React.CSSProperties = {
          position: 'absolute',
          insetInlineEnd: insetInlineEnd[i],
          bottom: bottom[i],
        };
        return (
          <FloatButton.Group
            key={placement}
            trigger="click"
            placement={placement}
            style={style}
            icon={icons[i]}
          >
            <FloatButton />
            <FloatButton icon={<CommentOutlined />} />
          </FloatButton.Group>
        );
      })}
    </div>
  </Flex>
);

对这段演示的要点拆解：

• 四个分组按序对齐：外层容器为 position: relative 的 100×100 方框，每个 FloatButton.Group 通过 style 以绝对定位放置在方框的一条边附近；insetInlineEnd 与 bottom 两个定位数组的下标与 placement 顺序一一对应，因而四个分组分别模拟“浮”在容器顶部、右侧、底部、左侧的按钮形态。
• trigger="click" 是前置条件：只有设置了 trigger，placement 才会驱动弹出动画，所以四组全部声明了 trigger="click"。图标 icons 数组中的 UpOutlined、RightOutlined、DownOutlined、LeftOutlined 也暗示了各自展开方向。
• 每个分组包含两个子按钮：触发按钮之外再放一个 <FloatButton /> 与带 CommentOutlined 图标的按钮，当点击触发按钮后，子列表沿对应方向展开并伴带动画。

演示文档本身说明（placement.md）：该能力提供 top、right、bottom、left 四个预设弹出位置，默认值为 top。官方 Demo 的 iframe 高度为 380，足以容纳四个方向的按钮分组。

属性声明与默认回退：源码中的 placement 处理

在 FloatButtonGroup.tsx 中，placement 被类型化为 'top' | 'left' | 'right' | 'bottom'（第 64 行）。在组件内部，取值并非直接透传给 DOM，而是先经过一层合并归一化：

// FloatButtonGroup.tsx
const mergedPlacement = ['top', 'left', 'right', 'bottom'].includes(placement!)
  ? placement
  : 'top';

也就是说，即便调用方传入了非法值或遗漏该属性，运行时也会统一回退到 top（与文档默认值一致），随后 mergedPlacement 进入两个关键分支：

1. 类名生成：根节点会被追加 ${groupPrefixCls}-${mergedPlacement}（例如 ant-float-btn-group-top）与 ant-float-btn-group-menu-mode 等类名，且仅当处于菜单模式（isMenuMode，即存在 trigger）时才拼接方位类名；
2. 布局方向判定：通过 const vertical = mergedPlacement === 'top' || mergedPlacement === 'bottom' 决定子列表使用纵向还是横向排布。

vertical 分支进一步影响渲染结构：当分组内子按钮为相互独立的圆形按钮（shape === 'circle' 时的 individual 模式）时，用 <Flex vertical={vertical}> 排布；否则使用 <Space.Compact vertical={vertical}> 将子按钮紧凑拼接（同一段源码第 271–283 行）。因此 top / bottom 两组方向对应垂直堆叠的弹出列表，而 left / right 两组方向对应水平排列的弹出列表，动画方向与布局方向保持一致。

另外需要留意 group.test.tsx 中的用例：遍历 ['bottom', 'left', 'right', 'top'] 渲染 FloatButton.Group 并断言根节点含有对应类 ant-float-btn-group-${placement}（第 195–205 行），这从测试层面确认了四个取值都能正确映射为语义化类名，可供你在排查样式时用选择器定位。

动画与定位的底层样式推导

弹出列表的实际方位由 style/group.ts 通过 CSS 变量实现。源码首先生成两个基础变量：

[varName('list-transform-start')]: `translate(0,${unit(floatButtonSize)})`,
[varName('list-trigger-offset')]: `calc(${unit(floatButtonSize)} + ${unit(padding)})`,

• list-trigger-offset：触发按钮尺寸（floatButtonSize）与组间距（padding）之和，用于让弹出列表始终贴合按钮边缘而不重叠；
• list-transform-start：菜单从何处滑入的“初始位移”，进入/离开动画都从该位移变换到 translate(0, 0)（展开态）。

随后针对四种方位分别覆写初始位移与列表锚点（源码第 100–127 行）：

'&-top': {          // 默认：自下而上滑入
  [listCls]: { bottom: varRef('list-trigger-offset') },
},
'&-bottom': {       // 自上而下滑入
  [listCls]: {
    [varName('list-transform-start')]: `translate(0, calc(${unit(floatButtonSize)} * -1))`,
    top: varRef('list-trigger-offset'),
  },
},
'&-left': {         // 自右而左滑入
  [listCls]: {
    [varName('list-transform-start')]: `translate(${unit(floatButtonSize)}, 0)`,
    right: varRef('list-trigger-offset'),
  },
},
'&-right': {        // 自左而右滑入
  [listCls]: {
    [varName('list-transform-start')]: `translate(calc(${unit(floatButtonSize)} * -1), 0)`,
    left: varRef('list-trigger-offset'),
  },
},

从中可以提炼出三个一致的规律：

1. 列表永远“贴在触发按钮外侧”：top 与 bottom 方向分别把列表的 bottom / top 定位到触发按钮之外 list-trigger-offset 处；left 与 right 方向则分别使用 right / left 属性做同样处理，保证四种方位都不会与触发按钮重叠。
2. 初始位移恒等于按钮整体高度/宽度：floatButtonSize 取自 Design Token 中 controlHeightLG（见 style/index.ts），进入动画统一从“位移一个按钮尺寸”的位置滑回原位，因而视觉效果是子列表像抽屉一样从按钮身后展开，这与文档所称“animation placement”（动画弹出方位）吻合。
3. 动画由 fade 类 motion 驱动：style/index.ts 中通过 initFadeMotion(token) 引入淡入淡出帧，同时列表自身的 &-motion 负责位移过渡（transition: all token.motionDurationSlow）。因此 placement 实际改变的是 CSSMotion 展开时的起始 transform 与列表锚点位置，而非动画时长。

组合使用建议与注意事项

综合源码、API 表格与测试用例，实际使用时有以下几点需要留意：

• placement 仅对菜单模式生效：未设置 trigger 时，子按钮直接平铺渲染（isMenuMode 为 false），此时不会生成方位类名，placement 也就没有视觉意义。
• 默认弹出方向是 top：从页面右下角的常规悬浮位置出发，菜单向上弹出最不易超出视口，这也是其被选为默认值的原因；当按钮靠近页面顶部时，可改用 bottom 避免列表被视口裁切。
• open 必须与 trigger 搭配：源码会在开发环境给出 Warning: [antd: FloatButton.Group] \open` need to be used together with `trigger``，该行为同样被 group.test.tsx 第 160–182 行的用例覆盖验证。
• 弹出列表与语义化样式均可独立定制：FloatButton.Group 支持对 root、list、item、trigger 等语义节点传入 classNames / styles（对象或函数形式，函数可依据 props.placement 做条件分支，测试中即有按 placement === 'bottom' 切换类名的用例），在按方向微调样式时不必触碰全局 CSS。
• 版本边界：placement 引入于 5.21.0，升级依赖后若使用更早版本将不会生效；请以实际引入的 antd 版本（对应本仓库 package.json 的发行线）为准。

若需要在一个页面中同时承载“回到顶部”“常用操作”等多组悬浮入口，可将多组 FloatButton.Group 分别置于不同方位，并通过 placement 让各自菜单向内或向外展开，避免互相遮挡；而在设计稿有严格间隔要求时，则可像官方演示那样直接用 style 覆盖组容器默认的 insetInlineEnd 与 bottom（即 Design Token 中的 floatButtonInsetInlineEnd / floatButtonInsetBlockEnd，分别取自 marginLG 与 marginXXL），把按钮精确摆放到期望的边界位置。