Popover

何时用

click 触发的轻量浮层，承载标题/描述/少量操作（确认、快捷设置、表单片段），点外部或 Esc 关闭。需要纯文本提示用 Tooltip（hover 触发）；需要 hover 展开富内容卡片用 HoverCard；需要遮罩 + 焦点锁定的强中断流程用 Dialog。

导入

Props

PopoverContent：

plain / arrow：内容自带外观的贴边浮层

PopoverContent 默认把 children 包进一层 text-sm text-foreground 的皮肤 div，并在有 title 或 description 时加 mt-2 与其拉开距离。浮层里装的是一整块自带外观、要贴边铺满的内容（顶部搜索行 + 标签列表、Calendar 面板、当贴边菜单用的浮层）时，配 className="p-0" 加 plain：

p-0 只清得掉浮层自己的内边距，清不掉内层皮肤 div —— className 落在浮层上、够不着内层，所以别用 [&>div]:mt-0 这类任意变体选择器去压它，那等于把库内结构写成外部契约。

arrow 与 plain 是两个独立开关：箭头指的是浮层与触发器的关系，不是内容的皮肤。贴边菜单一般两个都关，但「无标题的纯文字提示」只需要 plain、「铺满型面板仍想指明来源」只需要留着箭头。

同名的 plain 在 Card 的 variant="plain" 与 Accordion / Collapsible 的 Panel 上语义一致：内容自带外观时，要的不是改皮肤而是没有皮肤。

anchor：触发点是一个坐标，不是一个元素

DOCX / canvas 上算出来的标注点、右键位置、地图上的经纬度 —— 这类「触发点」只有一个矩形，没有可以当触发器的 DOM 节点，PopoverTrigger 接不住。给 anchor 一个只需实现 getBoundingClientRect() 的虚拟元素即可，触发器整个省掉、open 自己控：

边界翻转、视口 clamp、焦点管理、Esc 与点外部关闭、aria-expanded 仍然全由组件负责 —— 这正是不该自绘的部分（自绘版通常先漏掉的就是焦点与 aria）。

坐标变化时换一个新对象（或改用 () => virtualEl 的函数形态），别原地改同一个对象的字段：定位按 anchor 的 identity 变化重算，改字段不换对象浮层不会动。

同名 anchor 在 HoverCard 上语义一致，只是那里触发器不可省（卡片是 hover 打开的）。

Slots

PopoverContent：

PopoverTrigger / PopoverClose 用 render prop 接管自定义触发/关闭元素（如 render={<Button>…</Button>}）。

禁忌 / 坑

• 触发/关闭走 render prop 注入元素，别再在 PopoverTrigger 里二次嵌套交互元素，避免 <button> 套 <button>。
• 锚到坐标用 anchor，别自己 createPortal 手写 left/top：手写那条路要连边界翻转、视口 clamp、点外部关闭、Esc、焦点管理一起重造，而焦点与 aria-expanded 正是自绘版最常漏掉的两样。
• 浮层内容自带内边距/边框/正文色时加 plain（通常再配 className="p-0"），别用 [&>div]:mt-0 之类的任意变体选择器去压库内那层皮肤 div。
• 若手搓 hover 开 + focus 关叠加在这类 focus-managing popover 上会无限闪烁，见 [[hovercard-on-focus-managing-popover-flickers-set-initial-final-focus-false]]：popover 打开时把焦点移入浮层会触发 trigger 的 onBlur 关闭，关闭又把焦点还给 trigger 触发 onFocus 打开 → ping-pong。本组件默认 click 语义不踩，但若改造成 hover 触发需把 initialFocus/finalFocus 设 false。

相关

Dialog · Modal · AlertDialog · Drawer · Tooltip · HoverCard