Popover 气泡卡片
点击 / 悬停 / 聚焦触发，可承载标题、正文与自定义内容的浮层面板。支持 12 向放置、双轴偏移、开合动画、portal、modal 化与嵌套浮层。
基础用法
点击触发
放置方向
placement 支持 12 向：四基向 top / bottom / left / right 各配 -start / -end 交叉轴对齐（bottom-start 面板左缘对齐触发元素左缘，是最常见形态）。空间不足沿主轴翻转时对齐后缀保留（bottom-start → top-start），对齐后仍做视口夹取。
四个方向
12 向放置（-start / -end）
触发方式
trigger 控制触发方式：click（默认）/ hover / focus / contextmenu / manual，空格分隔可多选（如 "click hover"）。hover 触发时 hover-delay / hover-hide-delay 控制开合防抖延时（默认 150 / 100ms，无延时 hover 会闪开闪关）；悬停区域为触发元素 + 浮层面板（跨间隙移动不闪关）。manual 模式不绑定任何宿主事件，显隐完全由宿主 open 控制。
悬停触发
自定义开合延时
通用显隐延迟（open-delay / close-delay）
禁用
disabled 禁用整个 popover：点击 / 悬停 / 聚焦 / 右键 / 按键触发均不响应，宿主降饱和（opacity .6）并同步 aria-disabled。禁用触发元素（如原生 disabled button）不会派发鼠标事件，可在外层包一层 span 再挂 popover（B12 兼容方案）。
整体禁用
宽度定制
width 控制面板宽度：数字（px）、"trigger"（与触发元素同宽）或任意 CSS 值（如 50%）。width="trigger" 适合「面板与触发控件等宽」的下拉选择形态。
宽度定制（width）
偏移与碰撞细调
offset 双轴偏移："主轴距离" 或 "主轴距离, 交叉轴偏移"（默认 8, 0）。碰撞细调：collision-padding 视口夹取边距（默认 4px）；fallback-placements 自定义回退序列（请求放不下时按序列逐一尝试）；hide-when-detached 锚点完全脱离视口时隐藏面板。
双轴偏移（offset）
碰撞细调（collision-padding / fallback-placements / hide-when-detached）
初始焦点与键盘
focus-on-open 打开时焦点移入面板内首个可聚焦元素；initial-focus 指定选择器精确聚焦（优先级更高，解析不到回落 focus-on-open）。trigger-keys 指定按键在触发元素聚焦时切换开合（空格分隔多键）。
指定初始焦点（initial-focus）
打开后焦点直接进入下面的输入框：
按键打开（trigger-keys）
Portal 挂载点
append-to 把面板移到宿主容器之外（body 或选择器），避免被宿主容器的 overflow: hidden / clip 裁剪；定位基于视口坐标，移出后不受影响。面板移出 shadow 后点击面板内部仍不触发外部点击关闭。
Portal 挂载（append-to）
箭头与视口自动调整
默认显示指向触发元素边缘的箭头；arrow="false" 隐藏箭头；arrow-point-at-center 让箭头指向触发元素中心（视口边缘避让导致面板偏移时，箭头仍指向锚点中心）。默认空间不足时自动沿主轴翻转并避让视口边缘；auto-adjust-overflow="false" 关闭自动调整，面板保持声明 placement（可能溢出视口）。
箭头显隐与指向
箭头与角融合（arrow-merge）
关闭自动调整
自定义内容
自定义内容（slot=content）
slot="content" 可以放置任意自定义内容。 关闭按钮与声明式关层
closable 在面板右上角显示关闭按钮（part="close"），点击关闭并还原焦点。内容里任意元素加 data-popover="close" 即声明式关层——点击它关闭 popover（适合「确定 / 知道了」类操作按钮）。
关闭按钮与声明式关层
颜色变体
color 语义色变体：primary / success / warning / danger——面板 tint 底 + 语义色描边（含箭头），全部由 token 派生（dark 主题自动适配）。
颜色变体（color）
开合动画
面板打开 / 关闭播放 fade + scale 动画，transform-origin 随放置方向感知（从「对着触发元素的那条边」向外展开，-start/-end 贴到对齐边）。prefers-reduced-motion 下自动停用动画。
开合动画（方向感知）
内容实时与自动关闭
默认（无 fresh）关闭时内容冻结、打开时写入最新值；fresh 开启后关闭状态也持续同步内容（受控内容场景防闪烁）。auto-close 打开后超时自动关闭（引导提示 / onboarding 场景）。
fresh：关闭时内容持续更新
auto-close：超时自动关闭
嵌套浮层
浮层内容里可以再打开子浮层（popover / tooltip）：子浮层从父浮层内容触发，层级与定位自动正确；父层关闭时子层一并关闭；Esc 逐层关闭并逐层还原焦点。
嵌套浮层（卡片内再弹）
父面板内再触发子浮层：
虚拟触发
virtual 模式没有真实锚点（同 tooltip）：由宿主通过 virtual-x / virtual-y（视口坐标）或 virtual-anchor（锚点元素选择器）指定位置，适合图表、画布上的坐标提示；设置 open 控制显隐。虚拟模式下点击触发元素与外部点击都不改变状态，生命周期完全由宿主控制。
虚拟触发（画布坐标跟随）
移动鼠标查看坐标提示
虚拟触发（锚点坐标定位）
虚拟触发（锚点元素跟随）
Modal 化
modal 把 popover 变成模态浮层：全屏遮罩 + 焦点陷阱（Tab / Shift+Tab 在面板内循环，焦点逃逸拉回，仅最上层 modal 接管）+ 滚动锁（拦截 wheel / 滚动方向键，滚动条保持可见）+ aria-modal。点击遮罩关闭并还原焦点。
Modal 化（遮罩 + 焦点锁 + 滚动锁）
焦点被锁在面板内：
受控显示
open 属性受控：外部按钮设置 / 移除 open 控制显隐（点击外部 / Esc 仍会关闭）。
受控显示（open 属性）
API
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
append-to | portal 挂载点：打开时面板移入目标容器（body 或 CSS 选择器），关闭移回宿主 shadow；适合面板被宿主容器裁剪（overflow）的场景 | string | — |
arrow | 是否显示箭头（默认 true；arrow="false" 隐藏，箭头元素与 ::part(arrow) 保留） | string | true |
arrow-merge | 箭头与面板角融合（C1）：直角三角与面板角共边融合——直角贴角点、直角边与面板两边共线（描边与面板描边共带续接），尖端正交指向锚点，对应角圆角归零；仅 -start/-end 位置生效，center placement 不触发 | boolean | — |
arrow-point-at-center | 箭头指向触发元素中心（默认指向触发元素边缘；视口边缘避让导致面板偏移时箭头仍指向锚点中心） | — | — |
auto-adjust-overflow | 视口边缘自动翻转与避让（默认 true；"false" 关闭，保持声明 placement，可能溢出视口） | string | true |
auto-close | 打开后超时自动关闭（毫秒），如 auto-close="3000"；未设置不自动关闭 | string | — |
closable | 面板右上角显示关闭按钮（part="close"），点击关闭并还原焦点到触发元素 | boolean | — |
close-delay | 通用关闭延迟（毫秒，默认 0；非 hover 触发路径生效，hover 路径优先 hover-hide-delay） | string | — |
collision-padding | 视口边缘夹取边距（px，默认 4），面板贴边避让时保留的间距 | string | — |
color | 颜色变体：primary / success / warning / danger（面板 tint 底 + 语义色描边，走 token 派生变量含 dark 变体）；未设置或非法值保持默认中性面板 | string | — |
content | 正文文本 | string | — |
disabled | 整体禁用：click / hover / focus / contextmenu / trigger-keys 触发均不响应，宿主降饱和并同步 aria-disabled | boolean | — |
fallback-placements | 自定义回退序列（逗号或空格分隔，如 "left, right"）：请求 placement 放不下时按序列逐一尝试 fit，首个 fit 者胜出，全不 fit 取序列末位并夹取；未设置走默认主轴翻转 | string | — |
focus-on-open | 打开时焦点移入面板内首个可聚焦元素 | boolean | — |
fresh | 关闭时也持续更新内容（默认关闭态冻结内容，打开时写入最新值；fresh 开启后关闭态同步写入） | boolean | — |
hide-when-detached | 锚点完全脱离视口时隐藏面板（打开语义保留，避免孤悬屏外） | boolean | — |
hover-delay | hover 触发时打开防抖延时（毫秒，默认 150；未设置回落 open-delay） | string | — |
hover-hide-delay | hover 触发时关闭防抖延时（毫秒，默认 100；未设置回落 close-delay） | string | — |
initial-focus | 打开时聚焦指定选择器元素（宿主 light DOM 优先，含 slot 内容；解析不到回落 focus-on-open），优先级高于 focus-on-open | string | — |
modal | modal 化：全屏遮罩 + 焦点陷阱（Tab 面板内循环）+ 滚动锁 + aria-modal；点击遮罩关闭 | boolean | — |
offset | 双轴偏移："主轴距离" 或 "主轴距离, 交叉轴偏移"（px，默认 8, 0），如 offset="12, 20" | — | — |
open | 受控显示（布尔属性，存在即显示） | boolean | — |
open-delay | 通用打开延迟（毫秒，默认 0；非 hover 触发路径生效，hover 路径优先 hover-delay） | string | — |
placement | 浮层位置（12 向：四基向 top/bottom/left/right 各配 -start/-end 交叉轴对齐） | string | top |
title | 标题文本 | string | — |
trigger | 触发方式：click（默认）/ hover / focus / contextmenu / manual，空格分隔可多选（如 "click hover"） | string | click |
trigger-keys | 指定按键在触发元素聚焦时切换开合（空格分隔，如 "Enter Space"）；未设置无按键绑定 | string | — |
virtual | 虚拟触发模式（同 tooltip，不依赖锚点元素） | boolean | — |
virtual-anchor | 虚拟锚点元素选择器（virtual-x/virtual-y 未设置时生效） | — | — |
virtual-x | 虚拟锚点 x（视口坐标，px） | — | — |
virtual-y | 虚拟锚点 y（视口坐标，px） | — | — |
width | 面板宽度：数字（px）/ "trigger"（与触发元素同宽）/ 任意 CSS 值（如 50%、240px）；未设置保持默认 | string | — |
事件
| 事件 | 说明 |
|---|---|
oas-open-change | open 状态变化，detail: { open } |
插槽
| 名称 | 说明 |
|---|---|
| 默认 | — |
content | — |
点击触发元素切换显隐，点击外部或按 Esc 关闭；role="dialog"。嵌套浮层：父关闭时级联关闭子层，Esc 逐层关闭并还原焦点到触发元素。