ExUI

Popover 气泡卡片 ​

点击/鼠标移入元素，弹出气泡式的卡片浮层。带有霓虹发光效果的赛博朋克主题气泡卡片组件。

基础用法 ​

最简单的用法，鼠标点击时显示气泡卡片。

vue
<template>
  <ExPopover content="这是一段内容" title="标题">
    <ExButton>点击显示</ExButton>
  </ExPopover>
</template>

不同位置 ​

通过 placement 属性可以设置气泡卡片的显示位置，支持 12 个方向。

vue
<template>
  <ExPopover content="Top 内容" title="Top" placement="top">
    <ExButton>上边</ExButton>
  </ExPopover>
  
  <ExPopover content="Bottom 内容" title="Bottom" placement="bottom">
    <ExButton>下边</ExButton>
  </ExPopover>
</template>

触发方式 ​

通过 trigger 属性可以设置不同的触发方式。

vue
<template>
  <ExPopover content="鼠标悬停触发" title="Hover" trigger="hover">
    <ExButton>悬停触发</ExButton>
  </ExPopover>
  
  <ExPopover content="点击触发" title="Click" trigger="click">
    <ExButton>点击触发</ExButton>
  </ExPopover>
  
  <ExPopover content="聚焦触发" title="Focus" trigger="focus">
    <ExButton>聚焦触发</ExButton>
  </ExPopover>
</template>

自定义内容 ​

通过插槽可以自定义气泡卡片的内容。

vue
<template>
  <ExPopover>
    <template #title>
      <div style="display: flex; align-items: center; gap: 8px;">
        <img src="icon.svg" alt="图标" width="16" height="16" />
        <span>自定义标题</span>
      </div>
    </template>
    <template #content>
      <div>
        <p>这是自定义的内容区域</p>
        <div>
          <ExButton size="small" type="primary">确定</ExButton>
          <ExButton size="small">取消</ExButton>
        </div>
      </div>
    </template>
    <ExButton type="primary">自定义内容</ExButton>
  </ExPopover>
</template>

自定义宽度 ​

通过 width 属性可以设置气泡卡片的宽度。

vue
<template>
  <ExPopover content="默认宽度的气泡卡片" title="默认宽度">
    <ExButton>默认宽度</ExButton>
  </ExPopover>
  
  <ExPopover :width="300" content="自定义宽度 300px 的气泡卡片" title="300px">
    <ExButton>宽度 300px</ExButton>
  </ExPopover>
</template>

手动控制 ​

通过 v-model 可以手动控制气泡卡片的显示和隐藏。

vue
<script setup>
import { ref } from 'vue'

const visible = ref(false)
</script>

<template>
  <ExButton @click="visible = true">显示</ExButton>
  <ExButton @click="visible = false">隐藏</ExButton>
  
  <ExPopover content="手动控制的气泡卡片" title="手动控制" v-model="visible" trigger="manual">
    <ExButton>目标元素</ExButton>
  </ExPopover>
</template>

赛博朋克主题示例 ​

展示赛博朋克场景中的气泡卡片应用。

vue
<template>
  <ExPopover placement="top" :width="280">
    <template #title>
      <div style="display: flex; align-items: center; gap: 8px;">
        <img src="icon.svg" alt="玩家" width="16" height="16" />
        <span>玩家信息</span>
      </div>
    </template>
    <template #content>
      <div>
        <div style="display: flex; align-items: center; gap: 12px;">
          <ExAvatar size="large">P1</ExAvatar>
          <div>
            <div>Player001</div>
            <div>等级 50 • 战士</div>
          </div>
        </div>
      </div>
    </template>
    <ExButton type="primary">玩家信息</ExButton>
  </ExPopover>
</template>

API ​

Popover Props ​

参数说明类型默认值
title标题string—
content内容string—
placement出现位置'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end''top'
trigger触发方式'hover' | 'click' | 'focus' | 'manual''click'
show-arrow是否显示箭头booleantrue
disabled是否禁用booleanfalse
offset偏移量（像素）number12
width宽度string | number'auto'
transition过渡动画名称string'ex-popover-fade'
open-delay延迟显示（毫秒）number0
close-delay延迟隐藏（毫秒）number200
custom-class自定义类名string—
z-index层级number2000
v-model手动控制显示boolean—
aria-label无障碍标签string—

Popover Events ​

事件名说明类型
update:model-value显示状态变化时触发（配合 v-model）(value: boolean) => void
show显示时触发() => void
hide隐藏时触发() => void

Popover Slots ​

插槽名说明
default触发元素
title自定义标题
content自定义内容

Popover Methods ​

方法名说明类型
show显示气泡卡片() => void
hide隐藏气泡卡片() => void
updatePosition更新位置() => void

与 Tooltip 的区别 ​

  • Tooltip：轻量级，用于简短的文字提示，默认悬停触发
  • Popover：功能更丰富，可以承载复杂内容（如表单、列表等），默认点击触发

无障碍支持 ​

  • 使用 role="dialog" 标记气泡卡片
  • 完整的 ARIA 属性支持
  • 支持键盘导航
  • 支持屏幕阅读器
  • 点击外部自动关闭

受控 / 非受控 ​

默认由 trigger（click / hover / focus）非受控地控制显隐，也支持 v-model 手动控制：

vue
<template>
  <ExPopover v-model="open" title="标题" content="内容">
    <ExButton>点我</ExButton>
  </ExPopover>
</template>

<script setup>
import { ref } from 'vue'
const open = ref(false)
</script>

常见问题 ​

Q：trigger="focus" 不生效？ 已修复。组件监听会冒泡的 focusin/focusout，聚焦插槽内可聚焦元素即触发。

Q：气泡会超出屏幕吗？ 内置主轴翻转 + 视口夹取，空间不足时自动翻到对侧并收拢到可视区域内。

Q：点击气泡内部会关闭吗？ 不会。仅点击触发器外部（click 触发时）才关闭，气泡内部交互不受影响。

Q：和 Tooltip 怎么选？ 简短文字提示用 Tooltip；需要标题、富文本或可交互内容用 Popover。

最佳实践 ​

  • 承载可交互内容（菜单、表单、说明卡片）是 Popover 的主场；纯文字提示用 Tooltip。
  • 默认点击触发更符合"展开面板"语义；hover 触发适合预览类内容。
  • 用 width 约束内容宽度，避免长文本撑满屏幕。
  • 触发元素保持可聚焦，以支持键盘与读屏。

主题定制 ​

Popover 不定义独立的组件级变量，而是消费 ExUI 全局设计令牌。定制方式：

  • 单个实例：用 custom-class / custom-style 定制。
  • 全局：覆盖其消费的全局令牌：
css
:root {
  --ex-color-bg-elevated: #11151c;    /* 气泡背景 */
  --ex-color-border-primary: #1f2a37; /* 边框 */
  --ex-shadow-xl: 0 12px 32px rgba(0, 0, 0, 0.55); /* 投影 */
}