UI
本页目录

组件 · 数据展示

Popover 气泡卡片

点击/受控打开的内容浮层，含 Header/Title/Body/Footer 等语义槽。

入口 @selrux/ui/popover · 源码 src/components/popover/index.ts · 11 个组件 · 发布状态 preview

使用建议

  • 避免：用 Popover 代替 Dialog 做阻断确认
  • 限制：属性与导出以 @selrux/ui 对应子路径 d.ts/源码为准，禁止臆造

引入

tsx
import {
  Popover,
  PopoverArrow,
  PopoverBody,
  PopoverClose,
  PopoverContent,
  PopoverDescription,
  // …共 16 个导出
} from '@selrux/ui/popover';

演练场

调节下方可实现的字面量属性，实时预览真实组件。函数、Portal、样式逃生口等见代码演示与 API 表。

默认关闭；点击触发器打开。

代码演示

基础用法

点击触发器打开浮层，可包含标题、正文与操作。

悬停触发与位置

trigger="hover"，placement 指定方位。

受控与关闭策略

open / onOpenChange 受控；closeOnEscape、closeOnOutsidePress 控制关闭方式；beforeClose 返回 false 可拦截关闭；modal 阻止背景指针。

open = false

尺寸、宽度与延迟

size 控制内容字号；width="trigger" 与触发器等宽；openDelay / closeDelay 只影响 hover；disabled 禁止打开；defaultOpen 为非受控初始值。

虚拟锚点

anchorX / anchorY 以视口坐标定位（如右键菜单），点击区域内任意位置打开。

点击此区域任意位置

API

属性覆盖：示例用到 20 / 20 个自有属性（100%）

由 scripts/demo-coverage.mjs 统计，不含 className / style / 原生透传属性与纯转发事件。

  • Popover.styles：语义 slot 内联样式，与 className/style 同类的样式逃生口，不单独演示
  • Popover.initialFocusRef：焦点目标 ref，效果不可见；行为见“无障碍”
  • Popover.returnFocusRef：焦点目标 ref，效果不可见；行为见“无障碍”
  • PopoverPortal.container：Portal 挂载目标，默认 body；文档页无需更换挂载点

Popover

Popover 根。无布局 DOM。

属性说明类型默认值
size内容字号与间距档位；省略取 Provider → md。"xs" | "sm" | "md" | "lg" | "xl" | "2xl"-
classNames语义结构 class；部件自身 className 拼接其后。PopoverClassNamesInput-
styles语义结构 style；部件自身 style 覆盖同名键。PopoverStylesInput-
trigger触发方式；默认 'hover'；数组去重；纯 manual 不自动开。PopoverTriggerInput'hover'
openDelay仅 hover 打开延迟（ms），有限非负；focus/click 不延迟。默认 100。number100
closeDelay仅 hover 关闭宽限（ms）；指针在安全通道内维持。默认 100。number100
disabled为真时禁止打开并立即抑制可见层。boolean-
closeOnEscape顶层 Esc 是否进入关闭流程。默认 true。booleantrue
closeOnOutsidePress外部主指针是否进入关闭流程。默认 true。booleantrue
modal指针屏蔽：阻止背景指针穿透并约束焦点在层内；不锁滚动。默认 false。booleanfalse
beforeClose关闭前拦截；false/Promise<false> 取消，void/true 允许，reject 取消。PopoverBeforeClose-
initialFocusRef打开时初始焦点目标（优先于首个可 Tab 控件）。RefObject<HTMLElement | null>-
returnFocusRef适用关闭路径的返回焦点目标。RefObject<HTMLElement | null>-
anchorX虚拟锚点视口 X（CSS px）；与 anchorY 同时有限时启用。number-
anchorY虚拟锚点视口 Y（CSS px）；与 anchorX 同时有限时启用。number-
open受控打开；与 defaultOpen 互斥。boolean-
defaultOpen非受控默认打开；挂载时读取一次。boolean-
onOpenChange请求变更；不强改父状态。((open: boolean, details: OverlayChangeDetails) => void)-
children复合子树：Trigger / Portal 等。ReactNode-

PopoverArrow

PopoverArrow。

属性说明类型默认值
children装饰内容；默认空。ReactNode-

另有 278 项原生属性与事件继承自 HTMLAttributes，原样透传。

PopoverBody

PopoverBody。

属性说明类型默认值
children区域子树。ReactNode-

另有 279 项原生属性与事件继承自 HTMLAttributes，原样透传。

PopoverClose

PopoverClose。

属性说明类型默认值
render与 children 互斥；传 render 时禁用。ReactElement<unknown, string | JSXElementConstructor<any>>-
children不传 render 时的按钮内容。ReactNode-

另有 288 项原生属性与事件继承自 ButtonHTMLAttributes / HTMLAttributes，原样透传。

PopoverContent

PopoverContent。

属性说明类型默认值
style普通样式；受管定位/aria 不可被绕过失效。CSSProperties-
placement十二向 placement；默认 top。"top-start" | "top" | "top-end" | "bottom-start" | "bottom" | "bottom-end" | "left" | "right" | "left-start" | "left-end" | "right-start" | "right-end"top
sideOffset侧向间距（CSS px）；省略用库默认 4。number4
collisionPadding碰撞内边距（CSS px）；省略用库默认 8。number8
onEscapeKeyDownEsc 按下时调用；preventDefault 取消关闭且跳过 beforeClose。((event: KeyboardEvent) => void)-
width固定宽（正数 px）或 'trigger' 等宽；省略内容自适应。PopoverWidth-
onPointerDownOutside外部主指针按下时调用；preventDefault 取消关闭且跳过 beforeClose。((event: Event) => void)-
children卡片子树（Header/Body/Footer 等）。ReactNode-

另有 277 项原生属性与事件继承自 HTMLAttributes，原样透传。

PopoverDescription

PopoverDescription。

属性说明类型默认值
children说明内容。ReactNode-

另有 279 项原生属性与事件继承自 HTMLAttributes，原样透传。

PopoverFooter

PopoverFooter。

属性说明类型默认值
children区域子树。ReactNode-

另有 279 项原生属性与事件继承自 HTMLAttributes，原样透传。

PopoverHeader

PopoverHeader。

属性说明类型默认值
children区域子树。ReactNode-

另有 279 项原生属性与事件继承自 HTMLAttributes，原样透传。

PopoverPortal

PopoverPortal。

属性说明类型默认值
container挂载目标；省略默认 body；显式 null 等待就绪。PortalContainerInputbody
childrenPortal 子树。ReactNode-

PopoverTitle

PopoverTitle。

属性说明类型默认值
children标题内容。ReactNode-

另有 279 项原生属性与事件继承自 HTMLAttributes，原样透传。

PopoverTrigger

PopoverTrigger。

属性说明类型默认值
render与 children 互斥；传 render 时禁用。ReactElement<unknown, string | JSXElementConstructor<any>>-
children不传 render 时的按钮内容。ReactNode-

另有 284 项原生属性与事件继承自 ButtonHTMLAttributes / HTMLAttributes，原样透传。

导出类型：OverlayAlign、OverlayChangeDetails、OverlayChangeReason、OverlaySide、PopoverArrowProps、PopoverBeforeClose、PopoverClassNamesInput、PopoverCloseProps、PopoverContentProps、PopoverDescriptionProps、PopoverPlacement、PopoverPortalProps、PopoverProps、PopoverSectionProps、PopoverSemanticSlot、PopoverSize、PopoverStylesInput、PopoverTitleProps、PopoverTriggerInput、PopoverTriggerMode、PopoverTriggerProps、PopoverWidth、PortalContainerInput、ResolvedPopoverClassNames、ResolvedPopoverSemanticStyles、ResolvedPopoverStyles、ResolvePopoverSemanticStylesInput

函数与常量

名称说明签名 / 类型
mergePopoverClassName合并语义 class 与部件自身 className。(slot: string | undefined, own: string | undefined) => string | undefined
mergePopoverStyle合并语义 style 与部件自身 style；部件显式键覆盖语义键。(slot: CSSProperties | undefined, own: CSSProperties | undefined) => CSSProperties | undefined
popoverSizes合法尺寸集合。Set<PopoverSize>
resolvePopoverSemanticStyles解析语义样式映射；非法函数结果回退为空对象。(input: ResolvePopoverSemanticStylesInput) => ResolvedPopoverSemanticStyles
resolvePopoverSize按显式值、最近 Provider、md 的顺序解析尺寸。(size: PopoverSize | undefined, configured: PopoverSize | undefined) => PopoverSize

无障碍

摘自源码 JSDoc。

  • Popover.closeOnEscape：顶层 Esc 是否进入关闭流程。
  • Popover.modal：指针屏蔽：阻止背景指针穿透并约束焦点在层内；不锁滚动。
  • Popover.initialFocusRef：打开时初始焦点目标（优先于首个可 Tab 控件）。
  • Popover.returnFocusRef：适用关闭路径的返回焦点目标。
  • PopoverContent.onEscapeKeyDown：Esc 按下时调用；preventDefault 取消关闭且跳过 beforeClose。