深入 Material UI Popover：锚点定位、虚拟元素与过渡定制的完整指南

本篇基于 Material UI 官方文档 docs/data/material/components/popover/popover.md 及其配套示例与 @mui/material 源码实现，系统讲解 Popover 组件的打开/关闭状态管理、锚点（anchor）定位模型、悬停触发与虚拟元素锚定、过渡（transition）替换等核心能力。读完后，你既能直接复用文档中的完整示例代码，也能从源码层面理解 marginThreshold 自动避让、updatePosition() 命令式刷新等机制的底层原理。

Popover 是什么：构建于 Modal 之上的锚定浮层

Popover 用于在页面某个元素（或其他锚点）之上展示内容。根据官方文档，使用 Popover 前需要先了解两条核心特性：

• 它构建于 Modal 组件之上：因此它继承 Modal 的焦点管理、滚动锁定与事件拦截能力，而非只是一个普通定位容器。
• 与 Popper 的区别：Popover 默认会锁定页面滚动，并在点击浮层外部（click-away）时自动关闭；而 Popper 不锁定滚动。这意味着 Popover 是"模态式"的弹出层，适合菜单式操作、表单确认等需要抢占用户注意力的场景。

从源码 Popover.js 可以印证这一点：组件的 Root 槽位默认元素 PopoverRoot 就是对 Modal 的 styled 封装（第 73–76 行），而 PopoverPaper 对 Paper 的封装则定义了浮层的基本样式——position: 'absolute'、maxWidth/maxHeight: 'calc(100% - 32px)'（保证 16px 安全边距）、overflowY: 'auto'（内容超高时可滚动）（第 78–93 行）。

基础用法：状态驱动的打开与关闭

官方基础示例（完整代码见 BasicPopover.tsx）演示了 Popover 最标准的受控用法——用"锚点元素是否为空"来表达开关状态：

import * as React from 'react';
import Popover from '@mui/material/Popover';
import Typography from '@mui/material/Typography';
import Button from '@mui/material/Button';

export default function BasicPopover() {
  const [anchorEl, setAnchorEl] = React.useState<HTMLButtonElement | null>(null);

  const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
    setAnchorEl(event.currentTarget);
  };

  const handleClose = () => {
    setAnchorEl(null);
  };

  const open = Boolean(anchorEl);
  const id = open ? 'simple-popover' : undefined;

  return (
    <div>
      <Button aria-describedby={id} variant="contained" onClick={handleClick}>
        Open Popover
      </Button>
      <Popover
        id={id}
        open={open}
        anchorEl={anchorEl}
        onClose={handleClose}
        anchorOrigin={{
          vertical: 'bottom',
          horizontal: 'left',
        }}
      >
        <Typography sx={{ p: 2 }}>The content of the Popover.</Typography>
      </Popover>
    </div>
  );
}

要点解析：

• open 是必传布尔值。示例中用 Boolean(anchorEl) 派生它——anchorEl 同时承担"是否打开"和"锚在哪里"两个职责；
• onClose 在点击浮层外部、按 Esc 等场景下由组件回调，实现里只需 setAnchorEl(null) 即可关闭；
• anchorOrigin={{ vertical: 'bottom', horizontal: 'left' }} 表示从按钮底部的左侧一点作为附着点，即浮层出现在按钮下方——这是最常见的"下拉"形态。
• 示例中还通过 aria-describedby={id} 在按钮与浮层之间建立了无障碍关联。

锚点模型：anchorOrigin / transformOrigin / anchorReference

官方文档中的 Anchor playground 示例（AnchorPlayground.js）通过单选按钮实时调整 anchorOrigin 与 transformOrigin 的位置组合，是理解 Popover 定位模型的最好工具。其核心 JSX 结构为：

<Popover
  anchorReference="anchorEl"
  anchorOrigin={{
    vertical: 'top',    // top | center | bottom | 数字(px)
    horizontal: 'left', // left | center | right | 数字(px)
  }}
  transformOrigin={{
    vertical: 'top',
    horizontal: 'left',
  }}
>
  The content of the Popover.
</Popover>

两个 origin 的分工（源码依据见 Popover.d.ts 第 84–94 行与 Popover.js 第 24–56 行）：

• anchorOrigin（锚点上的附着点）：决定 Popover 挂在锚点元素边框的哪个位置。源码中 getOffsetTop(rect, vertical) / getOffsetLeft(rect, horizontal) 负责把 top/center/bottom 等语义值换算成相对锚点矩形的像素偏移（如 center 取 rect.height / 2，bottom 取 rect.height），也接受数字作为精确像素偏移。默认值为 { vertical: 'top', horizontal: 'left' }。
• transformOrigin（浮层自身的对位点）：决定 Popover 纸面的哪个点去"贴合"锚点附着点，同时它也是 CSS 过渡变换（Grow）的缩放原点。默认同为 { vertical: 'top', horizontal: 'left' }。
• anchorReference：决定参考哪个属性来定位，取值为 'anchorEl' | 'anchorPosition' | 'none'，默认 'anchorEl'。

none 模式值得注意：在 getPositioningStyle 中，当 anchorReference === 'none' 时组件直接返回 top: null, left: null 并只设置 transformOrigin，即不计算绝对位置，由你自己通过 CSS 完全控制浮层位置（常用于全局居中弹窗等场景）。

窗口边缘自动避让：marginThreshold 的源码实现

marginThreshold（默认 16，可传 null 关闭）指定了浮层距离视口边缘的最小距离。在 getPositioningStyle 中（Popover.js）：

1. 先按公式 top = anchorOffset.top - elemTransformOrigin.vertical（left 同理）计算初始位置；
2. 若 top < marginThreshold，把差值同时从 top 中减去并补偿到 transformOrigin.vertical 上——注意它同步修正了变换原点，这样后续 Grow 动画仍会从正确的点缩放；
3. bottom 超过 innerHeight - marginThreshold、或 right 超过 innerWidth - marginThreshold 时做同样的反向修正；
4. 非生产环境下，若浮层高度仍超出可视区域，会 console.error 提示考虑加 max-height（第 248–260 行）。

这套"位置 + 变换原点联动修正"是 Popover 无需任何 Popper.js 类依赖就能贴边不溢出的关键，也是它与基于 @popperjs/core 的 Popper 组件实现路线的根本差异。

用 anchorPosition 锚定到任意屏幕坐标

将 anchorReference 设为 'anchorPosition' 后，组件不再参考 anchorEl，而是使用你提供的 anchorPosition（{ top, left }，坐标相对应用客户区）定位。官方 playground 示例中的用法：

<Popover
  anchorReference="anchorPosition"
  anchorPosition={{ top: 200, left: 400 }}
  ...
/>

源码中 getAnchorOffset 对该分支有明确的开发期校验：使用了 anchorPosition 却没传该属性时，会输出 MUI: You need to provide a 'anchorPosition' prop when using <Popover anchorReference="anchorPosition" />. 的错误。这个模式适用于"锚点是一个画布上的坐标点"、"在视频时间轴某处弹出"等 DOM 元素之外需要定位的场景。

另外，anchorEl 还接受返回元素的函数（() => Element）。类型定义见 Popover.d.ts，实现见 resolveAnchorEl，类型测试用例见 Popover.spec.tsx。这在锚点元素由 ref 持有、且需要在打开瞬间重新取值时很有用。

鼠标悬停触发：mouseenter / mouseleave 模式

官方 Mouse hover interaction 示例（MouseHoverPopover.js）展示了如何用 mouseenter / mouseleave 事件实现悬停弹出，完整代码如下：

const [anchorEl, setAnchorEl] = React.useState(null);

const handlePopoverOpen = (event) => {
  setAnchorEl(event.currentTarget);
};

const handlePopoverClose = () => {
  setAnchorEl(null);
};

const open = Boolean(anchorEl);

return (
  <div>
    <Typography
      aria-owns={open ? 'mouse-over-popover' : undefined}
      aria-haspopup="true"
      onMouseEnter={handlePopoverOpen}
      onMouseLeave={handlePopoverClose}
    >
      Hover with a Popover.
    </Typography>
    <Popover
      id="mouse-over-popover"
      sx={{ pointerEvents: 'none' }}
      open={open}
      anchorEl={anchorEl}
      anchorOrigin={{
        vertical: 'bottom',
        horizontal: 'left',
      }}
      transformOrigin={{
        vertical: 'top',
        horizontal: 'left',
      }}
      onClose={handlePopoverClose}
      disableRestoreFocus
    >
      <Typography sx={{ p: 1 }}>I use Popover.</Typography>
    </Popover>
  </div>
);

这个模式里有三个容易踩坑的细节：

• sx={{ pointerEvents: 'none' }}：让浮层本身不接收鼠标事件，否则指针从触发词移入浮层时会先触发触发词的 mouseleave 造成闪烁；
• disableRestoreFocus：关闭时不把焦点归还给触发元素，避免悬停场景中焦点被反复抢占；
• aria-owns / aria-haspopup：悬停场景下用 aria-owns 而非 aria-describedby 更贴切地描述"触发元素拥有浮层内容"的语义。

如果内容本身需要交互（如包含按钮），则不能简单用 pointerEvents: 'none'，需要自行管理"指针进入浮层后延迟关闭"的逻辑。

虚拟元素（Virtual Element）：为选中文本、任意矩形定位

anchorEl 的取值不仅可以是真实 DOM 元素，还可以是一个虚拟元素——一个满足如下接口的对象（文档原文接口定义）：

interface PopoverVirtualElement {
  nodeType: 1;
  getBoundingClientRect: () => DOMRect;
}

官方 Virtual element 示例（VirtualElementPopover.js）演示了"划选一段文字后在选区上方弹出 Popover"：

const handleMouseUp = () => {
  const selection = window.getSelection();

  // Skip if selection has a length of 0
  if (!selection || selection.anchorOffset === selection.focusOffset) {
    return;
  }

  const getBoundingClientRect = () => {
    return selection.getRangeAt(0).getBoundingClientRect();
  };

  setOpen(true);
  setAnchorEl({ getBoundingClientRect, nodeType: 1 });
};

随后 <Popover open={open} anchorEl={anchorEl} anchorOrigin={{ vertical: 'bottom', horizontal: 'left' }} onClose={handleClose} disableAutoFocus /> 即可渲染在选区位置。

从源码看，虚拟元素能走通定位流程是因为锚点解析链路只依赖两样东西：nodeType === 1 的判断（getAnchorOffset 中 resolvedAnchorEl.nodeType === 1）和 getBoundingClientRect() 的返回值。PropTypes 校验（Popover.js）同样只对 nodeType 与包围盒做检查。

注意（文档原文警告）：Popover 的虚拟元素必须提供 nodeType 属性；这与 Popper 和 Tooltip 的虚拟元素不同，后两者不要求该属性。跨组件迁移代码时这一点最容易导致 Popover 定位回退到 document.body 而"飘"到左上角。

过渡动画：默认 Grow 与 slots.transition 定制

文档明确指出：Popover 默认使用 Grow 过渡；要替换过渡或向其传参，使用 slots.transition 与 slotProps.transition。

源码中过渡由 useSlot('transition', { elementType: Grow, ... }) 解析（Popover.js），组件在此处做了两件关键的事：

• 注入 onEntering：过渡进入阶段回调 setPositioningStyles()，确保 top/left/transformOrigin 在动画开始前已计算到位（首次定位未完成时，Paper 会以 opacity: 0 隐藏，避免闪烁，见第 428 行）；
• 注入 onExited：重置 isPositioned 状态，为下一次打开重新定位。

transitionDuration 默认值为 'auto'，含义是根据浮层高度自动计算动画时长；若你通过 slots.transition 替换成不支持 auto 的自定义过渡组件（其 muiSupportAuto 不为真），源码会主动把 transitionDuration 置为 undefined（第 382–384 行），避免把非法值传给过渡组件。

四个可定制槽位（root、paper、transition、backdrop）的完整类型见 Popover.d.ts；其中 backdrop 默认被强制合并 invisible: true（第 402–411 行），所以 Popover 虽然基于 Modal，背景却不遮罩。类型层面的用法与 mergeSlotProps 正确包装 transition 回调的写法，可参考 Popover.spec.tsx 中的 Custom / Custom2 用例。

定位的持续刷新：resize、scroll 与 updatePosition()

Popover 打开期间，位置不是一次性算好的：

• 窗口 resize：打开时注册防抖的 resize 监听器，调用 setPositioningStyles() 重算（Popover.js），并取锚点所在 window（ownerWindow(resolveAnchorEl(anchorEl))），以便在 iframe 锚点场景下监听正确的窗口；
• 滚动：Modal 默认锁定滚动，所以 Popover 打开期间页面通常不会滚。但设置 disableScrollLock 后，组件会改为监听 window 的 scroll 事件持续跟随锚点重定位（第 303–308 行）；
• 命令式刷新：通过 action ref，组件在打开时暴露 updatePosition()（第 324–335 行），当锚点内容高度因异步渲染变化（如图片加载、内容动态增长）时，可手动触发一次重新定位；
• 挂载容器：container 的默认策略（第 386–390 行）是"有 container 用 container；否则若提供了 anchorEl，挂载到锚点元素所在文档的 body；再否则交给 Modal 自行选择"。这对多文档（iframe）应用尤其重要。

状态管理进阶：material-ui-popup-state

文档的 Supplementary projects 部分推荐了第三方包 material-ui-popup-state，用于在多数场景下托管 Popover 的开关状态（open、anchorEl、onClose 样板代码）。官方示例（PopoverPopupState.js）：

import PopupState, { bindTrigger, bindPopover } from 'material-ui-popup-state';

export default function PopoverPopupState() {
  return (
    <PopupState variant="popover" popupId="demo-popup-popover">
      {(popupState) => (
        <div>
          <Button variant="contained" {...bindTrigger(popupState)}>
            Open Popover
          </Button>
          <Popover
            {...bindPopover(popupState)}
            anchorOrigin={{ vertical: 'bottom', horizontal: 'center' }}
            transformOrigin={{ vertical: 'top', horizontal: 'center' }}
          >
            <Typography sx={{ p: 2 }}>The content of the Popover.</Typography>
          </Popover>
        </div>
      )}
    </PopupState>
  );
}

PopupState 以 variant="popover" 声明场景，bindTrigger 自动处理点击开/关并绑定 anchorEl，bindPopover 注入 open 与 onClose，从而把基础示例中手写 state 的十行代码收敛成声明式绑定。该包为仓库外的可选依赖，按需安装后使用即可。

类名与主题定制

Popover 暴露的 utility class 只有两个（popoverClasses.ts）：

类名	作用
MuiPopover-root	应用于根元素（即 Modal 层）
MuiPopover-paper	应用于 Paper 浮层纸面

样式定制优先使用 slotProps（如 slotProps={{ paper: { elevation: 12, sx: { ... } } }}），配合 sx 系统 prop 或主题 components: { MuiPopover: {...} } 覆盖默认值。elevation 默认为 8，可通过同名 prop 直接调整阴影层级。

关键 Props 速查

以下默认值均取自 Popover.js 源码解构与 PropTypes 注释：

Prop	类型 / 可选值	默认值	说明
open	boolean（必传）	—	是否显示组件
onClose	(event, reason) => void	—	请求关闭时回调；reason 可区分关闭来源（如 clickaway、escapeKeyDown）
anchorEl	Element | PopoverVirtualElement | (() => …)	—	锚点元素或虚拟元素；无效时会告警并回退到 body
anchorReference	'anchorEl' | 'anchorPosition' | 'none'	'anchorEl'	定位参考来源
anchorPosition	{ top: number, left: number }	—	anchorReference='anchorPosition' 时必需，坐标相对客户区
anchorOrigin	{ vertical, horizontal }，取值 top/center/bottom（或 left/center/right）或 px 数字	{ vertical: 'top', horizontal: 'left' }	锚点上的附着点
transformOrigin	同 anchorOrigin	{ vertical: 'top', horizontal: 'left' }	浮层自身对位点兼变换原点
marginThreshold	number | null	16	距窗口边缘最小距离；null 时不做视口约束
elevation	number	8	Paper 阴影层级
transitionDuration	'auto' | number | { appear, enter, exit }	'auto'	过渡时长，'auto' 按高度自动计算
disableScrollLock	boolean	false	关闭滚动锁，改为监听 scroll 跟随定位
disableAutoFocus	boolean	false	打开时不自动聚焦，文档明确不推荐（影响读屏器体验）
action	Ref<PopoverActions>	—	命令式句柄，目前仅支持 updatePosition()
container	Element | (() => Element)	锚点所在文档的 body	透传给 Modal 的挂载容器
slots / slotProps	root / paper / transition / backdrop 四槽位	Modal / Paper / Grow / 不可见 Backdrop	组件与 props 级别的可替换结构

参考文件索引

内容	路径
官方文档主体	popover.md
基础示例	BasicPopover.tsx
锚点 playground	AnchorPlayground.js
悬停交互示例	MouseHoverPopover.js
虚拟元素示例	VirtualElementPopover.js
popup-state 示例	PopoverPopupState.js
组件实现	Popover.js
类型定义（slots / 虚拟元素 / actions）	Popover.d.ts
类名	popoverClasses.ts
类型测试用例	Popover.spec.tsx

适用前提：本文所述行为以当前仓库中 @mui/material 的 Popover 源码为准；slots/slotProps 四槽位模型、虚拟元素接口与 transitionDuration: 'auto' 的语义依赖仓库当前版本实现，升级大版本后建议对照最新 API 文档复核。