组件 · 数据展示

HoverCard 悬停卡片

悬停触发的内容卡片；类型复用 Popover 部件 Props。

入口 @selrux/ui/hover-card · 源码 src/components/hover-card/index.ts · 8 个组件 · 发布状态 preview

使用建议

避免：把关键操作只放在 HoverCard 内导致触达不可用
限制：属性与导出以 @selrux/ui 对应子路径 d.ts/源码为准，禁止臆造

引入

tsx

123456789import {
  HoverCard,
  HoverCardArrow,
  HoverCardClose,
  HoverCardContent,
  HoverCardDescription,
  HoverCardPortal,
  // …共 8 个导出
} from '@selrux/ui/hover-card';

演练场

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

代码演示

基础用法

悬停链接或名称时预览详情。

方位与宽度

HoverCardContent 的 placement 十二方位、width、sideOffset、collisionPadding；HoverCard 的 size。

触发方式与延迟

trigger 可为 hover / focus / click 或其数组；openDelay、closeDelay 设定悬停延迟；disabled 禁用。

受控与关闭策略

open / onOpenChange 受控；closeOnEscape、closeOnOutsidePress、modal、beforeClose 控制关闭；defaultOpen 为非受控初始值；anchorX / anchorY 使用虚拟锚点。

open = false

API

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

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

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

UI HoverCard 根；默认 hover。

属性	说明	类型	默认值
`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。	`number`	`100`
`closeDelay`	仅 hover 关闭宽限（ms）；指针在安全通道内维持。默认 100。	`number`	`100`
`disabled`	为真时禁止打开并立即抑制可见层。	`boolean`	-
`closeOnEscape`	顶层 Esc 是否进入关闭流程。默认 true。	`boolean`	`true`
`closeOnOutsidePress`	外部主指针是否进入关闭流程。默认 true。	`boolean`	`true`
`modal`	指针屏蔽：阻止背景指针穿透并约束焦点在层内；不锁滚动。默认 false。	`boolean`	`false`
`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`	-

HoverCardArrow

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

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

HoverCardClose

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

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

HoverCardContent

内容沿用 Popover 样式并叠加 hover-card 类。

属性	说明	类型	默认值
`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。	`number`	`4`
`collisionPadding`	碰撞内边距（CSS px）；省略用库默认 8。	`number`	`8`
`onEscapeKeyDown`	Esc 按下时调用；preventDefault 取消关闭且跳过 beforeClose。	`((event: KeyboardEvent) => void)`	-
`width`	固定宽（正数 px）或 'trigger' 等宽；省略内容自适应。	`PopoverWidth`	-
`onPointerDownOutside`	外部主指针按下时调用；preventDefault 取消关闭且跳过 beforeClose。	`((event: Event) => void)`	-
`children`	卡片子树（Header/Body/Footer 等）。	`ReactNode`	-

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

HoverCardDescription

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

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

HoverCardPortal

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

HoverCardTitle

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