ng-zorro-antd Popover 箭头指向目标中心：nzPopoverArrowPointAtCenter 完全指南

气泡卡片（Popover）是 ng-zorro-antd 中常用的数据展示组件，当用户点击或移入目标元素时，会弹出卡片式浮层来承载标题、描述内容乃至链接按钮等可交互元素。在默认行为下，Popover 的箭头始终对齐目标元素的边缘；而通过设置 nzPopoverPlacement 与 nzPopoverArrowPointAtCenter，可以让箭头精确指向目标元素的中心，从而获得更精细的对齐效果。本指南将以 components/popover/demo/arrow-point-at-center.md 及其配套示例为核心，结合 Popover 完整 API 文档 与源码实现，讲解如何配置这一能力、它与边缘对齐的差异、底层定位机制及适用场景，读完后你将能准确控制 Popover 浮层在任意方位上的箭头对齐行为。

一、示例解读：边缘对齐与中心指向

components/popover/demo/arrow-point-at-center.md 演示的核心结论是：通过设置 nzPopoverPlacement，可以让箭头指向目标元素的中心。准确地说，该能力由属性 nzPopoverArrowPointAtCenter（默认 false）开启，并搭配具体方位（如 topLeft）使用。

配套示例 arrow-point-at-center.ts 并排渲染了两个使用相同方位 topLeft 的按钮，直观对比两种对齐模式：

import { Component } from '@angular/core';

import { NzButtonModule } from 'ng-zorro-antd/button';
import { NzNoAnimationDirective } from 'ng-zorro-antd/core/animation';
import { NzPopoverModule } from 'ng-zorro-antd/popover';

@Component({
  selector: 'nz-demo-popover-arrow-point-at-center',
  imports: [NzButtonModule, NzPopoverModule, NzNoAnimationDirective],
  template: `
    <button nz-button nzPopoverTitle="Title" nzPopoverContent="Content" nzPopoverPlacement="topLeft" nz-popover>
      Align edge / 边缘对齐
    </button>
    <button
      nz-button
      nz-popover
      nzPopoverTitle="Title"
      nzPopoverContent="Content"
      nzPopoverPlacement="topLeft"
      [nzPopoverArrowPointAtCenter]="true"
      nzNoAnimation
    >
      Arrow points to center / 箭头指向中心
    </button>
  `,
  styles: `
    button {
      margin-right: 8px;
      margin-bottom: 8px;
    }
  `
})
export class NzDemoPopoverArrowPointAtCenterComponent {}

两个按钮的关键差异仅在于一行：

• 边缘对齐（Align edge）：仅设置 nzPopoverPlacement="topLeft"，箭头对齐按钮左上边缘；
• 中心指向（Arrow points to center）：额外设置 [nzPopoverArrowPointAtCenter]="true"，箭头指向按钮中心。

示例中引入的 NzNoAnimationDirective 来自 ng-zorro-antd/core/animation，用于禁用浮层缩放动画（源码中通过 [nzNoAnimation] 绑定到组件模板），在演示场景中可以让对齐效果更直观地呈现；实际业务中按需使用即可。

二、属性 API：nzPopoverArrowPointAtCenter

2.1 参数定义

根据 Popover API 文档，[nz-popover] 指令支持如下箭头相关配置：

参数	说明	类型	默认值
[nzPopoverArrowPointAtCenter]	箭头指向锚点的中心	boolean	false

该属性控制的是箭头的落点而非浮层整体位置：

• false（默认）：箭头指向目标元素边缘的对应方位点；
• true：箭头指向目标元素的几何中心。

2.2 源码中的定义与继承关系

从源码结构看，Popover 的箭头配置并非独立实现，而是建立在 Tooltip 底座之上。在 popover.ts 中，指令通过继承与覆写获得该属性：

@Directive({
  selector: '[nz-popover]',
  exportAs: 'nzPopover',
  host: {
    '[class.ant-popover-open]': 'visible'
  }
})
export class NzPopoverDirective extends NzTooltipBaseDirective {
  @Input({ alias: 'nzPopoverArrowPointAtCenter', transform: booleanAttribute })
  override arrowPointAtCenter?: boolean;
  // ...
}

其继承链路为：

1. 抽象基类 NzTooltipBaseDirective 声明抽象属性 abstract arrowPointAtCenter?: boolean，并在属性代理映射中注册 arrowPointAtCenter: ['nzArrowPointAtCenter', () => this.arrowPointAtCenter]；
2. NzPopoverDirective 以 nzPopoverArrowPointAtCenter 为别名覆写该属性，并通过 transform: booleanAttribute 将字符串形式的属性值（如 nzPopoverArrowPointAtCenter="true" 或空属性）自动归一化为布尔值；
3. 该值经由代理映射转发给 Popover 的浮层组件 NzPopoverComponent，最终绑定到模板中的 [nzArrowPointAtCenter] 输入。

因此，nzPopoverArrowPointAtCenter 与 Tooltip 的 nzTooltipArrowPointAtCenter（见 tooltip.ts）共享同一套定位逻辑，这也解释了为何 Popover API 文档中注明“更多属性请参考 Tooltip”。

三、底层原理：箭头如何“指向中心”

3.1 指令与浮层模板

NzPopoverComponent 的模板（popover.ts）使用 cdkConnectedOverlay 挂载浮层，并将箭头配置传给核心 Overlay 指令：

<ng-template
  #overlay="cdkConnectedOverlay"
  cdkConnectedOverlay
  nzConnectedOverlay
  [cdkConnectedOverlayOrigin]="origin"
  [cdkConnectedOverlayPositions]="_positions"
  [cdkConnectedOverlayOpen]="_visible"
  [nzArrowPointAtCenter]="nzArrowPointAtCenter"
  ...
>
  <div class="ant-popover" ...>
    <div class="ant-popover-arrow"></div>
    <div class="ant-popover-content">...</div>
  </div>
</ng-template>

3.2 核心定位算法

真正的“指向中心”逻辑位于 NzConnectedOverlayDirective。该指令监听浮层的位置变化，在 nzArrowPointAtCenter 为真时根据当前方位计算浮层相对目标元素的偏移量：

private updateArrowPosition(position: ConnectedOverlayPositionChange): void {
  const originRect = this.getOriginRect();
  const placement = getPlacementName(position);

  let offsetX: number | undefined = 0;
  let offsetY: number | undefined = 0;

  if (placement === 'topLeft' || placement === 'bottomLeft') {
    offsetX = originRect.width / 2 - 14;
  } else if (placement === 'topRight' || placement === 'bottomRight') {
    offsetX = -(originRect.width / 2 - 14);
  } else if (placement === 'leftTop' || placement === 'rightTop') {
    offsetY = originRect.height / 2 - 10;
  } else if (placement === 'leftBottom' || placement === 'rightBottom') {
    offsetY = -(originRect.height / 2 - 10);
  }

  if (this.cdkConnectedOverlay.offsetX !== offsetX || this.cdkConnectedOverlay.offsetY !== offsetY) {
    this.cdkConnectedOverlay.offsetY = offsetY;
    this.cdkConnectedOverlay.offsetX = offsetX;
    this.cdkConnectedOverlay.overlayRef.updatePosition();
  }
}

该算法可以拆解为三个要点：

1. 取目标元素尺寸：通过 getOriginRect() 获取锚点（origin）的 getBoundingClientRect() 信息，即目标元素的宽高与位置；
2. 按方位计算偏移：只有当方位是 8 个组合方位（topLeft / topRight / bottomLeft / bottomRight / leftTop / leftBottom / rightTop / rightBottom）之一时才需要补偿偏移；四个主轴方位（top / bottom / left / right）本身箭头就已居中，无需调整；
3. 补偿常量与公式：偏移量取目标宽度（或高度）的一半再减去箭头自身的半尺寸（横向约 14px、纵向约 10px），以抵消箭头占据的空间，使箭头尖精确落在目标中心；计算后写入 cdkConnectedOverlay.offsetX/offsetY 并调用 overlayRef.updatePosition() 重新定位。

3.3 样式层支撑

浮层中的箭头由 popover 样式 中的 placementArrow 混入（mixin）渲染，位于 class="ant-popover-arrow" 元素上，并通过 --antd-arrow-background-color 变量控制背景色以匹配卡片底色。定位算法给出的 offset 正是让这个箭头元素在几何上对准目标中心的依据。

四、结合方位配置的完整用法

4.1 与 nzPopoverPlacement 的组合

nzPopoverPlacement 决定浮层相对目标元素的方位，支持 12 个单一方位或 Array<string> 形式的回退序列（默认 'top'）：

'top' | 'left' | 'right' | 'bottom' | 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight' | 'leftTop' | 'leftBottom' | 'rightTop' | 'rightBottom'

参考 placement 演示，12 个方位覆盖了目标元素的四边与四角。当 nzPopoverArrowPointAtCenter 为 true 时：

• 四边方位（top/left/right/bottom）下箭头本就位于中心，行为不变；
• 四角方位（如 topLeft）下，箭头从“贴边”改为“指向目标中心”，配合 nzPopoverPlacement 可将浮层整体偏移到角方位，形成“角部卡片、箭头居中”的布局。

4.2 回退序列场景

当 nzPopoverPlacement 传入数组（如 ['top', 'topLeft']）时，浮层会在空间不足时按序列回退。由于 NzConnectedOverlayDirective 在每次位置变化时都会依据当前 placement 重新计算偏移，箭头中心指向逻辑在回退后依然成立，无需额外处理。

4.3 最小可运行示例

将以下代码放入任意 Angular 组件（需在模块或组件 imports 中引入 NzPopoverModule 与 NzButtonModule）：

<button
  nz-button
  nz-popover
  nzPopoverTitle="Title"
  nzPopoverContent="Content"
  nzPopoverPlacement="topLeft"
  [nzPopoverArrowPointAtCenter]="true"
>
  箭头指向目标中心
</button>

效果：浮层出现在按钮左上方，箭头尖对准按钮中心而非左上角边缘。

五、使用注意与常见问题

1. 事件接收要求：Popover 文档强调，请确保 <a href="https://link.gitcode.com/i/0c456fc6463e6cfa9bf3eca1e5a2e582" target="_blank">nz-popover] 元素能接受 onMouseEnter、onMouseLeave、onFocus、onClick 事件（详见 [index.zh-CN.md），否则默认的 hover 触发或 click/focus 触发将无法工作。
2. 滚动容器跟随：默认浮层以 body 为滚动容器；若页面存在自定义滚动容器，需在该容器元素上添加 CdkScrollable 指令（从 @angular/cdk/scrolling 导入），否则滚动时浮层不会跟随（见文档 FAQ）。
3. 触发方式：nzPopoverTrigger 支持 'click' | 'focus' | 'hover' | null，默认 'hover'；设为 null 时不响应光标事件，可配合 nzPopoverVisible 完全受控。
4. 动画：如示例所示，可通过 NzNoAnimationDirective（nzNoAnimation）禁用缩放动画，便于精确观察箭头对齐效果。

六、小结

nzPopoverArrowPointAtCenter 是 ng-zorro-antd Popover 提供的一个轻量而实用的精细控制开关：在 arrow-point-at-center.ts 中与 nzPopoverPlacement="topLeft" 组合使用，即可让箭头从默认的边缘对齐切换为指向目标中心。其底层由 NzConnectedOverlayDirective 根据目标元素尺寸与当前方位动态计算浮层偏移实现，并与 Tooltip 共享同一套继承体系。在需要强调浮层与目标元素几何关联的场景（如数据标注、引导提示、角部工具卡片）中，这一配置能让视觉指向更精准。