Skip to content

HoverCard 悬停卡片

hover / 聚焦触发,浮层可悬停不闪关的富内容预览卡片。支持 12 向放置、显隐延迟分离、箭头(含贴角融合)、双轴偏移、碰撞细调、挂载容器定制、延迟组与受控显示。

基础用法

悬停或聚焦触发器显示预览卡片。

悬停触发

悬停查看

富内容插槽

slot="content" 插槽承载任意 HTML 预览(链接 / 按钮 / 图片等)。浮层可悬停:指针从触发器移到卡片内不关闭,卡片内的链接与按钮可交互(悬停区域 = 触发器 + 浮层面板)。

富内容预览(浮层可悬停)

悬停查看用户
O
欧阳小雨
前端工程师 · 杭州
关注开源与 Web Components,写代码与写文章两不误。
发消息个人主页

放置方向

12 向放置:top / bottom / left / right × start / 中心 / end。

12 向放置

上-左上-右下-左下-右左-上左-下右-上右-下

显隐延迟

open-delay / close-delay 分离配置:悬停约 800ms 后出现,移出后 300ms 关闭。delay 为兼容别名(未分别设置时同时作用于显隐)。

延迟分离(open-delay / close-delay)

分离延迟delay 别名

箭头

箭头默认显示;arrow="false" 隐藏;arrow-point-at-center 让箭头始终指向触发器中心。

箭头(默认 / 隐藏 / 指向中心)

默认箭头隐藏箭头指向中心

箭头贴角融合

arrow-merge:*-start / *-end 位置下箭头与面板圆角融合成直角三角。

箭头贴角(arrow-merge)

下-左下-右

双轴偏移

offset 主轴距离(面板与触发器间距),skidding 交叉轴偏移。

双轴偏移(offset / skidding)

offset=20skidding=24

宽度定制

width 数值(px)或 trigger / target(与触发器同宽)。

宽度定制(width)

width=320width=trigger

挂载容器

append-to:卡片改为绝对定位在指定容器内(容器提升为定位上下文),适合嵌入自定义面板 / 弹层区域。

append-to 定位容器

悬停查看

碰撞细调

collision-padding 视口夹取边距;fallback-placements 自定义回退序列;hide-when-detached 锚点滚出视口时隐藏卡片;auto-adjust-overflow="false" 关闭自动调整。

碰撞细调

碰撞边距回退序列脱离隐藏关自动调整

禁用

disabled:hover / focus 不再触发显示(受控 open 仍可显隐)。

禁用(disabled)

悬停无效

延迟组

相同 group 值的多个触发器共享延迟:指针在组内成员间连续移动时,后一个跳过 open-delay 立即打开、前一个立即关闭。

延迟组(group)

用户 A用户 B用户 C

受控显示与事件

open 属性受控显隐;显隐变化派发 oas-open-changedetail: { open })。hover / focus 触发仍叠加生效。

受控显示(open + oas-open-change)

显示隐藏open: false触发元素

API

属性

属性说明类型默认值
append-to定位容器选择器(如 #panel):设置后卡片改为绝对定位在该容器内(容器提升为相对定位上下文),坐标随容器换算;未设置时走 position: fixed 视口坐标string
arrow是否显示箭头,默认 true;arrow="false" 隐藏,箭头元素与 ::part(arrow) 保留stringtrue
arrow-merge箭头贴角融合模式:-start/-end 位置下直角三角与面板角共边融合——直角贴角点、直角边与面板两边共线(描边与面板描边共带续接),尖端正交指向锚点,对应角圆角归零;居中位置不生效boolean
arrow-point-at-center箭头指向触发器中心(面板被视口避让偏移后仍指向锚点);默认箭头保持面板中心boolean
auto-adjust-overflow视口边缘自动调整(翻转/夹取),默认 true;"false" 关闭,按声明 placement 严格定位(浮层可越出视口)stringtrue
close-delay关闭延迟(毫秒),与 open-delay 分离;未设置时回退 delay 别名,再回退默认 150
collision-padding视口夹取边距(px),默认 4
content内容文本string
delay显隐延迟(毫秒),兼容别名:open-delay/close-delay 未设置时同时作用于打开与关闭;分别设置时以各自为准
disabled禁用浮层显示:hover/focus 触发不再打开;受控 open 属性仍可显隐boolean
fallback-placements自定义回退序列(逗号分隔基向,如 left,top):请求 placement 空间不足时按序列依次尝试;缺省默认翻转到对向
group延迟组名:同 group 值的组件共享延迟,指针在组内成员间连续移动时后一个跳过 open-delay 立即打开、前一个立即关闭
hide-when-detached锚点滚出视口(完全脱离)时隐藏卡片,保留 open 语义,滚动回来自动恢复boolean
offset主轴距离(px,面板与触发器的间距),默认 8
open受控显示(布尔属性,存在即显示)boolean
open-delay打开延迟(毫秒),与 close-delay 分离;未设置时回退 delay 别名,再回退默认 300
placement浮层位置,12 向:top/bottom/left/right × start/中心/end(如 bottom-startstringtop
skidding交叉轴偏移(px),沿垂直于主轴的轴平移
title标题文本string
width宽度定制:数值(px)或 trigger/target(与触发器同宽);未设置走 CSS min-width

事件

事件说明
oas-open-changeopen 状态变化(显示/关闭)时派发,detail: { open }

插槽

名称说明
默认触发器(首个非 slot="content" 子元素),hover/focus 触发
content富内容插槽:卡片内的自由 HTML 预览(链接/按钮等,可交互)

基于 MIT OR Apache-2.0 双许可发布