Popover 弹出框
用于在不打断用户流程的情况下展示补充信息和操作内容。支持标题 / 富文本内容 / 不同触发方式与位置控制。
何时使用
- 需要在不打断用户流程的情况下展示补充信息和操作内容
- 支持标题、富文本内容、不同触发方式与位置控制
- 需要展示比 Tooltip 更复杂的内容和操作
基本使用
最简单的用法，默认点击触发显示弹出框。
悬停触发
trigger="hover" 鼠标悬停时显示弹出框。
自定义内容与标题插槽
#title / #content slot 可插入任意 VNode，常用于带操作按钮的富文本浮层。
12 个出现位置
通过 placement 控制方位。
自定义背景色 color
color 优先于 effect，接受任意 CSS color 字符串，常用于品牌色 / 警告色 / 渐变。
显隐箭头 show-arrow
通过 show-arrow 控制箭头显示/隐藏。
弹层宽度 width
width 控制弹层固定宽度，常用于复杂内容场景避免内容塌缩。
触发方式
hover / click / focus / manual / contextmenu 五种。
延迟显示 / 隐藏
通过 show-after / hide-after 控制显隐延迟（ms）。
受控显示 v-model:visible
visible 配合 v-model:visible 双向同步。
ref 调用 hide 方法
通过 ref 拿到组件实例后调用 hide() 可以在事件回调内主动关闭浮层，常用于「点确认后关闭」流程。
自动关闭
auto-close 设置毫秒数，弹层在指定时间后自动隐藏；常用于 toast-like 提示场景。
虚拟触发
virtual-triggering 配合 virtual-ref，让浮层挂在外部任意元素上，常用于「触发节点和声明位置分离」的场景。
业务场景：用户卡片 hover
用户列表上 hover 头像 / 名字时展示完整用户卡，是 IM / 协作工具最常见的悬浮卡片范式。
API
Popover Props
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 标题文本，也可以通过 slot#title 传入 | string | — |
| content | 显示的内容，也可以通过 slot#content 传入 | string | — |
| placement | Popover 的出现位置 | 12 种方位字符串 | bottom |
| effect | 默认提供的主题 | 'dark' | 'light' | light |
| visible / v-model:visible | 受控显示状态 | boolean | false |
| disabled | Popover 是否可用 | boolean | false |
| color | 自定义背景色（覆盖 effect） | string | — |
| show-arrow | 是否显示箭头 | boolean | true |
| trigger | 触发方式 | 'hover' | 'focus' | 'click' | 'manual' | 'contextmenu' | click |
| show-after | 鼠标进入显示延迟（ms） | number | 0 |
| hide-after | 鼠标离开隐藏延迟（ms） | number | 200 |
| popper-class | 浮层根节点 class | string | — |
| fresh | 关闭后是否销毁内部内容 | boolean | false |
| destroyTooltipOnHide | 隐藏时销毁弹层节点 | boolean | false |
| autoAdjustOverflow | 自动调整方向避免溢出 | boolean | true |
| align | floating-ui 微调对象 | object | — |
| offset | 出现位置的偏移量 | number | 4 |
| raw-content | 是否将 content 作为 HTML 字符串处理 | boolean | false |
| enterable | 鼠标是否可进入到 popover 中 | boolean | true |
| hide-on-click-outside | 是否在点击外部时隐藏 | boolean | true |
| close-on-esc | 是否支持 ESC 键关闭 | boolean | true |
| aria-label | 屏幕阅读器标签 | string | — |
| width | 弹层宽度 | number | string | — |
| transition | 定义渐变动画 | string | ccui-popover-fade |
| auto-close | 自动关闭时间，单位毫秒 | number | 0 |
| tabindex | Popover 组件的 tabindex | number | string | 0 |
| teleported | 是否 Teleport 到 body | boolean | true |
| persistent | 是否持久化 | boolean | true |
| virtual-triggering | 是否启用虚拟触发器 | boolean | false |
| virtual-ref | 虚拟触发器的参照元素 | HTMLElement | — |
| trigger-keys | 键盘触发按键 | string[] | ['Enter', 'Space'] |
Popover Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| before-show | 显示前触发 | — |
| show | 显示时触发 | — |
| before-hide | 隐藏前触发 | — |
| hide | 隐藏时触发 | — |
| update:visible | v-model:visible 同步 | visible |
| before-enter | 显示动画播放前触发 | — |
| after-enter | 显示动画播放后触发 | — |
| before-leave | 隐藏动画播放前触发 | — |
| after-leave | 隐藏动画播放后触发 | — |
Popover Slots
| 插槽名 | 说明 |
|---|---|
| default | Popover 触发 & 引用的元素 |
| title | 自定义标题 |
| content | 自定义内容 |
Popover Exposes
| 方法名 | 说明 | 类型 |
|---|---|---|
| hide | 隐藏弹出框 | () => void |