X-Next

Appearance

Popover 气泡卡片 ​

围绕触发元素展示一块非模态浮动卡片，适合承载简短详情、辅助信息或轻量操作。

何时使用 ​

  • 需要点击、悬浮、聚焦或右键触发一块贴近目标元素的内容。
  • 需要展示比 Tooltip 更丰富的标题、说明或操作。
  • 需要控制浮层位置、箭头、挂载容器或受控显隐状态。

组件选择 ​

需求推荐组件
富内容浮动卡片Popover
纯文字说明Tooltip
操作菜单Dropdown
二次确认Popconfirm
封装新的浮层组件Trigger

Trigger 是底层触发定位 primitive，不建议普通业务直接使用。

基础用法 ​

vue
<template>
  <x-popover title="项目进度" content="当前任务已完成 62%，还有 3 个待处理节点。">
    <x-button type="primary">查看进度</x-button>
  </x-popover>
</template>

自定义内容 ​

vue
<template>
  <x-popover show-arrow>
    <x-button>查看详情</x-button>
    <template #title>节点详情</template>
    <template #content>
      <div>
        <span>负责人：产品运营组</span>
        <span>预计完成：今天 18:00</span>
        <x-button size="small" type="primary">进入任务</x-button>
      </div>
    </template>
  </x-popover>
</template>

触发方式 ​

vue
<template>
  <x-popover trigger="hover" content="鼠标移入触发元素时显示。">
    <x-button>悬浮</x-button>
  </x-popover>

  <x-popover trigger="focus" content="获得焦点时显示，失焦后关闭。">
    <x-button>聚焦</x-button>
  </x-popover>

  <x-popover trigger="contextMenu" align-point content="右键位置触发。">
    <x-button>右键</x-button>
  </x-popover>
</template>

弹出位置 ​

vue
<template>
  <x-popover position="top" content="上方弹出">
    <x-button>Top</x-button>
  </x-popover>
  <x-popover position="right" content="右侧弹出">
    <x-button>Right</x-button>
  </x-popover>
</template>

箭头和偏移 ​

vue
<template>
  <x-popover
    show-arrow
    :popup-offset="12"
    title="带箭头的浮层"
    content="通过 popupOffset 控制与触发元素的距离。"
  >
    <x-button>带箭头</x-button>
  </x-popover>
</template>

受控显隐 ​

当前：隐藏
vue
<template>
  <x-button @click="visible = !visible">
    {{ visible ? '关闭' : '打开' }}
  </x-button>
  <x-popover
    v-model:popup-visible="visible"
    trigger="click"
    title="受控 Popover"
    content="外部按钮和触发器都可以同步显隐状态。"
  >
    <x-button type="primary">受控触发器</x-button>
  </x-popover>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const visible = ref(false);
</script>

局部容器 ​

vue
<template>
  <div id="popover-local-container" style="position: relative; min-height: 180px;">
    <x-popover
      popup-container="#popover-local-container"
      show-arrow
      title="局部挂载"
      content="局部挂载内容"
    >
      <x-button>挂载到容器</x-button>
    </x-popover>
  </div>
</template>

保持挂载 ​

vue
<template>
  <x-popover
    v-model:popup-visible="visible"
    :unmount-on-close="false"
    title="保留 DOM"
    content="关闭后保留浮层节点"
  >
    <x-button>切换保留浮层</x-button>
  </x-popover>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const visible = ref(false);
</script>

与 Popup 的关系 ​

Popover 是后续推荐使用的通用浮动卡片组件。Popup 是早期命名，已放入即将废弃分组，当前仅作为迁移期兼容入口保留。

按需导入 ​

ts
import { Popover } from 'x-next';

Props ​

参数说明类型默认值
popupVisible弹出层是否可见，支持 v-model:popup-visiblebooleanundefined
defaultPopupVisible默认是否显示，非受控模式booleanfalse
trigger触发方式'hover' | 'click' | 'focus' | 'contextMenu' | array'click'
position弹出位置'top' | 'tl' | 'tr' | 'bottom' | 'bl' | 'br' | 'left' | 'lt' | 'lb' | 'right' | 'rt' | 'rb''bottom'
title标题内容string | number-
content正文内容string | number-
disabled是否禁用触发booleanfalse
popupOffset弹出层与触发元素的距离number8
popupTranslate在原位置基础上的偏移量[number, number] | object-
showArrow是否显示箭头booleanfalse
alignPoint是否跟随鼠标点定位，常用于右键菜单booleanfalse
popupHoverStayhover 触发时移入浮层是否保持显示booleantrue
blurToClosefocus 触发时失焦是否关闭booleantrue
clickToClose点击触发器时是否允许关闭booleantrue
clickOutsideToClose点击外部区域是否关闭booleantrue
unmountOnClose关闭后是否卸载浮层节点booleantrue
contentClass弹出内容类名string | array | object-
contentStyle弹出内容样式CSSProperties-
arrowClass箭头类名string | array | object-
arrowStyle箭头样式CSSProperties-
popupStyle弹出层定位节点样式CSSProperties-
animationName动画名称string'x-zoom-in-fade-out'
duration动画时长number | { enter: number; leave: number }-
mouseEnterDelaymouseenter 延迟触发时间，单位毫秒number100
mouseLeaveDelaymouseleave 延迟关闭时间，单位毫秒number100
focusDelayfocus 延迟触发时间，单位毫秒number0
autoFitPopupWidth是否将浮层宽度设为触发器宽度booleanfalse
autoFitPopupMinWidth是否将浮层最小宽度设为触发器宽度booleanfalse
autoFixPosition触发器尺寸变化时是否重新计算位置booleantrue
popupContainer弹出层挂载容器string | HTMLElement-
updateAtScroll容器滚动时是否更新浮层位置booleanfalse
autoFitPosition是否自动调整位置以适应视口booleantrue
renderToBody是否挂载到 body 体系下booleantrue
preventFocus是否阻止浮层内元素点击时获得焦点booleanfalse
scrollToClose滚动时是否关闭浮层booleanfalse
scrollToCloseDistance滚动关闭阈值number0

Events ​

事件名说明回调参数
update:popupVisible显隐状态更新时触发visible: boolean
popup-visible-change显隐状态变化时触发visible: boolean
show显示动画结束后触发-
hide隐藏动画结束后触发-

Slots ​

插槽名说明
default触发元素
title标题内容
content正文内容