FxPopover 弹出框

点击 / 悬停触发元素时弹出的内容浮层。不依赖任何 UI 框架，基于 FxTooltip 浮层。

基础用法

trigger 控制触发方式（hover / click / focus / contextmenu，默认 hover），title 与 content 设置内容，也可用插槽。

<template>
  <div class="flex flex-wrap gap-3">
    <FxPopover
      placement="top-start"
      title="标题"
      :width="200"
      trigger="hover"
      content="hover 触发的内容"
    >
      <FxBtn>Hover 触发</FxBtn>
    </FxPopover>
    <FxPopover
      placement="bottom"
      title="标题"
      :width="200"
      trigger="click"
      content="click 触发的内容"
    >
      <FxBtn>Click 触发</FxBtn>
    </FxPopover>
    <FxPopover
      placement="right"
      title="标题"
      :width="200"
      trigger="focus"
      content="focus 触发的内容"
    >
      <FxBtn>Focus 触发</FxBtn>
    </FxPopover>
    <FxPopover
      title="标题"
      :width="200"
      trigger="contextmenu"
      content="右键触发的内容"
    >
      <FxBtn>右键触发</FxBtn>
    </FxPopover>
    <FxPopover
      :visible="visible"
      placement="bottom"
      title="标题"
      :width="200"
      content="手动控制的内容"
    >
      <FxBtn @click="visible = !visible">手动触发</FxBtn>
    </FxPopover>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"
import { FxPopover } from "@fx/components"

const visible = ref(false)
</script>

出现位置

placement 控制弹出方向（top/bottom/left/right + start/end 方向）。

<template>
  <div class="popover-base-box">
    <div class="row center">
      <FxPopover title="标题" content="Top Left prompts info" placement="top-start">
        <template #reference><FxBtn>top-start</FxBtn></template>
      </FxPopover>
      <FxPopover title="标题" content="Top Center prompts info" placement="top">
        <template #reference><FxBtn>top</FxBtn></template>
      </FxPopover>
      <FxPopover title="标题" content="Top Right prompts info" placement="top-end">
        <template #reference><FxBtn>top-end</FxBtn></template>
      </FxPopover>
    </div>
    <div class="row">
      <FxPopover title="标题" content="Left Top prompts info" placement="left-start">
        <template #reference><FxBtn>left-start</FxBtn></template>
      </FxPopover>
      <FxPopover title="标题" content="Right Top prompts info" placement="right-start">
        <template #reference><FxBtn>right-start</FxBtn></template>
      </FxPopover>
    </div>
    <div class="row">
      <FxPopover title="标题" content="Left Center prompts info" placement="left">
        <template #reference><FxBtn class="mt-3 mb-3">left</FxBtn></template>
      </FxPopover>
      <FxPopover title="标题" content="Right Center prompts info" placement="right">
        <template #reference><FxBtn>right</FxBtn></template>
      </FxPopover>
    </div>
    <div class="row">
      <FxPopover title="标题" content="Left Bottom prompts info" placement="left-end">
        <template #reference><FxBtn>left-end</FxBtn></template>
      </FxPopover>
      <FxPopover title="标题" content="Right Bottom prompts info" placement="right-end">
        <template #reference><FxBtn>right-end</FxBtn></template>
      </FxPopover>
    </div>
    <div class="row center">
      <FxPopover title="标题" content="Bottom Left prompts info" placement="bottom-start">
        <template #reference><FxBtn>bottom-start</FxBtn></template>
      </FxPopover>
      <FxPopover title="标题" content="Bottom Center prompts info" placement="bottom">
        <template #reference><FxBtn>bottom</FxBtn></template>
      </FxPopover>
      <FxPopover title="标题" content="Bottom Right prompts info" placement="bottom-end">
        <template #reference><FxBtn>bottom-end</FxBtn></template>
      </FxPopover>
    </div>
  </div>
</template>

<script setup lang="ts">
import { FxPopover } from "@fx/components"
</script>

<style scoped>
.popover-base-box {
  width: 600px;
}
.popover-base-box .row {
  display: flex;
  align-items: center;
  justify-content: space-between;
}
.popover-base-box .center {
  justify-content: center;
}
</style>

嵌套信息

content 插槽可渲染任意复杂内容（表格、表单等）。

<template>
  <div class="flex items-center" style="gap: 16px">
    <FxPopover placement="right" :width="400" trigger="click">
      <template #reference>
        <FxBtn style="margin-right: 16px">点击查看</FxBtn>
      </template>
      <template #content>
        <table class="nested-table">
          <thead>
            <tr>
              <th style="width: 150px">日期</th>
              <th style="width: 100px">姓名</th>
              <th>地址</th>
            </tr>
          </thead>
          <tbody>
            <tr v-for="row in gridData" :key="row.date">
              <td>{{ row.date }}</td>
              <td>{{ row.name }}</td>
              <td>{{ row.address }}</td>
            </tr>
          </tbody>
        </table>
      </template>
    </FxPopover>

    <FxPopover :width="300" :popper-style="cardStyle">
      <template #reference>
        <div class="avatar">FX</div>
      </template>
      <template #content>
        <div class="card">
          <div class="card-avatar">FX</div>
          <p class="card-name">Fx Components</p>
          <p class="card-mention">@fx/components</p>
          <p class="card-desc">
            一套不依赖任何 UI 框架的通用 Vue 3 组件库。
          </p>
        </div>
      </template>
    </FxPopover>
  </div>
</template>

<script setup lang="ts">
import type { CSSProperties } from "vue"
import { FxPopover } from "@fx/components"

const gridData = [
  { date: "2016-05-02", name: "Jack", address: "纽约" },
  { date: "2016-05-04", name: "Jack", address: "纽约" },
  { date: "2016-05-01", name: "Jack", address: "纽约" },
  { date: "2016-05-03", name: "Jack", address: "纽约" },
]

const cardStyle: CSSProperties = {
  boxShadow:
    "0 10px 38px -10px rgba(14, 18, 22, 0.35), 0 10px 20px -15px rgba(14, 18, 22, 0.2)",
  padding: "20px",
}
</script>

<style scoped>
.nested-table {
  width: 100%;
  border-collapse: collapse;
  font-size: 14px;
}
.nested-table th,
.nested-table td {
  padding: 8px 4px;
  border-bottom: 1px solid var(--fx-border-color);
  text-align: left;
}
.nested-table th {
  color: var(--fx-text-color-secondary);
  font-weight: 500;
}

.avatar {
  width: 40px;
  height: 40px;
  border-radius: 50%;
  background: var(--fx-color-primary);
  color: var(--fx-color-white);
  display: flex;
  align-items: center;
  justify-content: center;
  cursor: pointer;
}

.card {
  display: flex;
  flex-direction: column;
  gap: 12px;
}
.card-avatar {
  width: 60px;
  height: 60px;
  border-radius: 50%;
  background: var(--fx-color-primary);
  color: var(--fx-color-white);
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: 20px;
}
.card-name {
  margin: 0;
  font-weight: 500;
  color: var(--fx-text-color-primary);
}
.card-mention {
  margin: 0;
  font-size: 14px;
  color: var(--fx-text-color-secondary);
}
.card-desc {
  margin: 0;
  color: var(--fx-text-color-primary);
}
</style>

嵌套操作

配合 v-model:visible 可在 content 里放操作按钮，实现类似确认框的交互。

<template>
  <FxPopover :visible="visible" placement="top" :width="180" trigger="click">
    <template #content>
      <p style="margin: 0 0 8px">确认删除这项吗？</p>
      <div style="display: flex; justify-content: flex-end; gap: 8px; margin: 0">
        <FxBtn size="small" text @click="visible = false">取消</FxBtn>
        <FxBtn size="small" type="primary" @click="onConfirm">确定</FxBtn>
      </div>
    </template>
    <template #reference>
      <FxBtn @click="visible = true">删除</FxBtn>
    </template>
  </FxPopover>
</template>

<script setup lang="ts">
import { ref } from "vue"
import { FxPopover, fxMsg } from "@fx/components"

const visible = ref(false)
function onConfirm() {
  visible.value = false
  fxMsg.success("已删除")
}
</script>

虚拟触发

virtual-triggering + virtual-ref 可绑定外部任意元素作为触发源，无需用 reference 插槽包裹。

<template>
  <button ref="buttonRef" type="button" class="fx-virtual-trigger-btn">
    点我（虚拟触发）
  </button>

  <FxPopover
    :virtual-ref="buttonRef"
    virtual-triggering
    trigger="click"
    title="虚拟触发"
    :width="200"
  >
    <template #content>
      <span>通过 virtualRef 绑定的外部元素触发，无需包裹 reference。</span>
    </template>
  </FxPopover>
</template>

<script setup lang="ts">
import { ref } from "vue"
import { FxPopover } from "@fx/components"

const buttonRef = ref<HTMLElement | null>(null)
</script>

<style scoped>
.fx-virtual-trigger-btn {
  padding: 6px 14px;
  border: 1px solid var(--fx-border-color);
  border-radius: var(--fx-border-radius-base);
  background: var(--fx-bg-color);
  color: var(--fx-text-color-primary);
  font-size: 14px;
  cursor: pointer;
}
.fx-virtual-trigger-btn:hover {
  border-color: var(--fx-color-primary);
}
</style>

局部引入

import { FxPopover } from "@fx/components"

API

Attributes

名称	说明	类型	默认值
trigger	触发方式	'hover' | 'click' | 'focus' | 'contextmenu'	hover
title	标题	string	—
content	内容（也可用插槽）	string	—
placement	出现位置	Placement	bottom
width	宽度	string | number	min-content
disabled	是否禁用	boolean	false
visible (v-model:visible)	是否显示	boolean	—
offset	偏移	number	—
show-arrow	是否显示箭头	boolean	true
show-after / hide-after	显示 / 隐藏延时（ms）	number	0 / 200
auto-close	自动隐藏（ms）	number	0
enterable	鼠标是否可进入	boolean	true
effect	主题	'light' | 'dark'	light
teleported	是否 teleport	boolean	true
append-to	挂载目标	string | HTMLElement	body
persistent	是否持久化	boolean	true
popper-class / popper-style	自定义类名 / 样式	string | CSSProperties	—
transition	动画名	string	—
tabindex	tabindex	string | number	—
trigger-keys	键盘触发键（KeyboardEvent.code）	string[]	['Enter','NumpadEnter','Space']
popper-options	浮层定位配置（底层 @floating-ui）	Record<string, any>	—
virtual-triggering ^(fx 增强)	是否启用虚拟触发	boolean	false
virtual-ref ^(fx 增强)	虚拟触发元素，配合 virtual-triggering	Measurable	—

Slots

名称	说明
reference	触发元素
default	触发元素（reference 无时）
content	内容（覆盖 content prop，作用域参数 hide）

Events

名称	说明
before-enter / before-leave	进出场前
after-enter / after-leave	进出场后
update:visible	显隐变化

实现说明

• 浮层引擎基于 @floating-ui/dom，popper-options 为 floating-ui 的配置
• 虚拟触发通过 virtual-triggering + virtual-ref 实现，未提供指令语法糖
• 图标走 @fx-core/icon，样式走 @fx/styles token，亮暗自动跟随