Ant Design Popover 箭头指向中心：详解 arrow={{ pointAtCenter: true }} 的原理与用法

在 Ant Design 中，气泡卡片（Popover）默认的箭头指向触发元素，当气泡面板与触发元素位置错位时，视觉上可能显得不严谨。arrow={{ pointAtCenter: true }} 属性可以让箭头精确指向目标元素的中心，使面板、箭头、目标三者严格对齐。本篇基于 arrow-point-at-center 演示 及其配套源码，讲清该属性的用法、全部 12 个 placement 下的表现，以及它在 placements 计算与 useMergedArrow 合并链中的底层实现，帮助你在需要"箭头严格指中"的 UI 场景中直接落地。

一、pointAtCenter 解决什么问题

Popover 的 arrow 属性自 5.2.0 起支持两种写法：

• 布尔值：arrow={false} 隐藏箭头，arrow 缺省或 arrow={true} 显示箭头（默认显示）；
• 对象值：arrow={{ pointAtCenter: boolean }}，其中 pointAtCenter: true 表示"箭头指向触发元素（目标元素）的中心"。

这一条 API 说明可参考 Tooltip、Popconfirm、Popover 三组件共享的属性表 sharedProps.zh-CN.md，其中明确写着：arrow 用于"修改箭头的显示状态以及修改箭头是否指向目标元素中心"，类型为 boolean | { pointAtCenter: boolean }，默认值 true。

默认模式下，箭头位置由弹层与触发元素的几何关系决定（例如 topLeft 布局下箭头固定在面板左上角附近）；开启 pointAtCenter 后，即使面板整体因为布局或溢出调整发生平移，箭头也会重新计算位置，始终落在触发元素的中心点正上方/正下方/正左/正右，形成严格的视觉指向关系。

二、官方演示：12 个 placement 全量验证

官方演示 arrow-point-at-center.tsx 用一个 280×280 的虚线方格，同时渲染了全部 12 个 placement（topLeft、top、topRight、leftTop、left、leftBottom、rightTop、right、rightBottom、bottomLeft、bottom、bottomRight）下的 Popover，核心代码如下：

import React from 'react';
import { Flex, Popover } from 'antd';
import type { GetProp } from 'antd';

type Placement = GetProp<typeof Popover, 'placement'>;

const placements: Placement[] = [
  'topLeft', 'top', 'topRight',
  'leftTop', 'left', 'leftBottom',
  'rightTop', 'right', 'rightBottom',
  'bottomLeft', 'bottom', 'bottomRight',
];

const App = () => (
  <Flex gap={16} wrap>
    {placements.map((placement) => (
      <div key={placement} className={classNames.item}>
        <Popover
          placement={placement}
          content={<Flex align="center" justify="center">{placement}</Flex>}
          autoAdjustOverflow={false}
          arrow={{ pointAtCenter: true }}
          forceRender
          open
        >
          {/* 触发元素：40x40 色块 + 红蓝十字线，用于肉眼校验箭头是否指中 */}
          <div className={`${classNames.box} ${classNames.cross}`} />
        </Popover>
      </div>
    ))}
  </Flex>
);

演示代码中有三处值得注意的工程细节：

1. autoAdjustOverflow={false}：关闭溢出自动调整。默认情况下弹层被视口遮挡时会自动移位（见 getOverflowOptions 中 adjustX/adjustY/shiftX/shiftY 的计算），移位会改变箭头指向的基准。演示刻意关闭它，以便在纯几何状态下验证"箭头是否严格指向中心"。
2. forceRender + open：强制所有气泡常驻展开，方便一次性观察 12 个方向的指向效果。
3. 红蓝十字线：演示用 ::before（横向红线）和 ::after（纵向蓝线）在 40×40 的深蓝色块上画出中心十字，作为肉眼校验箭头落点的参考系。

同目录的 arrow.tsx 演示则展示了 arrow 属性的完整三态切换：

const mergedArrow = useMemo<PopoverProps['arrow']>(() => {
  if (arrow === 'Hide') {
    return false; // 隐藏箭头
  }
  if (arrow === 'Show') {
    return true; // 显示箭头，默认指向
  }
  return {
    pointAtCenter: true, // 显示箭头并指向目标中心
  };
}, [arrow]);

即 arrow 支持 false（隐藏）、true（默认指向）、{ pointAtCenter: true }（指中）三种形态，三者可在运行时切换。

三、底层实现：从 useMergedArrow 到 placements 计算

3.1 属性合并：useMergedArrow

Popover 本身不直接消费 arrow，而是在 components/popover/index.tsx 中通过 useMergedArrow(popoverArrow, contextArrow) 将实例属性与 ConfigProvider 全局配置合并，再把结果传给内部的 Tooltip。合并逻辑位于 useMergedArrow.ts：

interface MergedArrow {
  show: boolean;
  pointAtCenter?: boolean;
}

const useMergedArrow = (providedArrow, providedContextArrow) => {
  const toConfig = (arrow) =>
    typeof arrow === 'boolean' ? { show: arrow } : arrow || {};

  return React.useMemo(() => {
    const arrowConfig = toConfig(providedArrow);
    const contextArrowConfig = toConfig(providedContextArrow);

    return {
      ...contextArrowConfig,
      ...arrowConfig, // 实例属性优先级更高
      show: arrowConfig.show ?? contextArrowConfig.show ?? true,
    };
  }, [providedArrow, providedContextArrow]);
};

可以看出两条规则：实例 arrow 属性覆盖全局配置；show 在两侧均未指定时默认为 true。布尔写法 arrow={false} 会被归一化为 { show: false }。

3.2 指中布局的几何换算

合并结果随后进入 components/tooltip/index.tsx，Tooltip 在构建内置 placements 时把开关传入：

const tooltipPlacements = React.useMemo<BuildInPlacements>(() => {
  return (
    builtinPlacements ||
    getPlacements({
      arrowPointAtCenter: mergedArrow?.pointAtCenter ?? false,
      autoAdjustOverflow,
      arrowWidth: mergedShowArrow ? token.sizePopupArrow : 0,
      borderRadius: token.borderRadius,
      offset: token.marginXXS,
      visibleFirst: true,
    })
  );
}, [mergedArrow, builtinPlacements, token, mergedShowArrow, autoAdjustOverflow]);

真正的位置换算是核心文件 placements.ts 完成的，其机制可以分三层理解：

（1）锚点对齐点的替换。 默认布局表 PlacementAlignMap 与指中布局表 ArrowCenterPlacementAlignMap 为每个 placement 定义了对齐锚点（points，如 'bl' -> 'tl' 表示触发元素左下对齐面板左上）。开启指中后，8 个角向 placement 会切换到指中专用锚点：

const ArrowCenterPlacementAlignMap: BuildInPlacements = {
  topLeft:     { points: ['bl', 'tc'] }, // 默认是 ['bl', 'tl']
  leftTop:     { points: ['tr', 'cl'] },
  topRight:    { points: ['br', 'tc'] },
  rightTop:    { points: ['tl', 'cr'] },
  bottomRight: { points: ['tr', 'bc'] },
  rightBottom: { points: ['bl', 'cr'] },
  bottomLeft:  { points: ['tl', 'bc'] },
  leftBottom:  { points: ['br', 'cl'] },
};

即触发元素的角点改为对齐到面板边线中点（tc/bc/cl/cr），从对齐基准上保证箭头垂直/水平指向中心。而 top/bottom/left/right 四个轴向 placement 的锚点本身已指向中心，无需替换。

（2）箭头位置补偿偏移。 锚点替换只解决了"面板放哪"，还需把箭头挪到能指中的位置。getPlacements 中对 8 个角向 placement 追加了静态偏移，其中 arrowOffsetHorizontal 来自 getArrowOffsetToken（由内容圆角换算的箭头水平补偿量）：

if (arrowPointAtCenter) {
  switch (key) {
    case 'topLeft':
    case 'bottomLeft':
      placementInfo.offset[0] = -arrowOffset.arrowOffsetHorizontal - halfArrowWidth;
      break;
    case 'topRight':
    case 'bottomRight':
      placementInfo.offset[0] = arrowOffset.arrowOffsetHorizontal + halfArrowWidth;
      break;
    case 'leftTop':
    case 'rightTop':
      placementInfo.offset[1] = -arrowOffset.arrowOffsetHorizontal * 2 + halfArrowWidth;
      break;
    case 'leftBottom':
    case 'rightBottom':
      placementInfo.offset[1] = arrowOffset.arrowOffsetHorizontal * 2 - halfArrowWidth;
      break;
  }
}

（3）关闭自动箭头，锁定设计位。 8 个角向 placement 位于 DisableAutoArrowList 中，会强制 autoArrow = false（源码注释：Disable autoArrow since design is fixed position）——因为指中模式下箭头位置是设计固定的，不需要 rc-trigger 的自动箭头跟随。

此外每个 placement 都会挂上 getOverflowOptions 计算的 overflow 配置：top/bottom 方向允许水平 shiftX（可滑动量 = arrowOffsetHorizontal * 2 + arrowWidth），left/right 方向允许 shiftY；当实例传入 autoAdjustOverflow={false} 时（如前文演示），adjustX/adjustY 全部关闭，弹层严格按上述几何位置渲染——这正是演示能直观验证指向精度的原因。

四、全局配置：ConfigProvider 统一开启

除实例属性外，arrow 自 6.0.0 起支持通过 ConfigProvider 全局配置（见 sharedProps.zh-CN.md 中"全局配置"一列：Tooltip / Popover / Popconfirm 均为 6.0.0）。在 components/popover/index.tsx 中，全局值来自 useComponentConfig('popover') 返回的 arrow: contextArrow，再经 useMergedArrow 与实例属性合并——即全局设置对所有 Popover 生效，实例 arrow 属性可逐点覆盖。

这意味着可以在应用入口一次性为所有气泡卡片开启指中箭头，个别不需要指中的组件再用 arrow 显式覆盖即可。

五、使用建议与适用场景

• 适用场景：数据标注、图表提示、画布/编辑器类应用中，气泡需要与目标元素建立严格"指向-被指向"关系时，pointAtCenter 比默认箭头更严谨；对 12 个 placement 全部生效，角向（topLeft 等 8 向）与轴向（top 等 4 向）表现一致。
• 注意溢出行为：pointAtCenter 与 autoAdjustOverflow 会相互作用——溢出调整会让面板移位，演示特意关闭了它以便观察；实际使用中建议保留默认溢出调整（autoAdjustOverflow 缺省为 true），牺牲极端情况下的精确指中换取面板完整可见。
• 注意 builtinPlacements：Tooltip 源码中 builtinPlacements || getPlacements(...) 表明一旦传入了自定义 builtinPlacements，指中偏移不再自动生效，需自行在自定义布局中复现上述锚点与偏移逻辑。
• 箭头宽度来源：指中偏移中的 arrowWidth 取自主题 token sizePopupArrow（隐藏箭头时为 0），因此更换主题 token 会同步影响指中的几何计算，无需手动维护箭头尺寸。

相关测试与快照位于 components/popover/tests 目录（demo.test.tsx 等），可作为该演示回归行为的参照。