Popover 弹出框

在触发元素附近展示补充信息或轻量操作。

命令行安装

npx @loongship-kit/ui add popover button input

组件结构

角色	组件	职责	使用条件
根组件	Popover	管理显示状态和焦点行为	必需
触发与锚点	PopoverTrigger、PopoverAnchor	打开浮层或指定定位锚点	按交互方式选用
内容结构	PopoverPortal、PopoverContent	传送、定位并承载浮层内容	内容组件必需
关闭与装饰	PopoverClose、PopoverArrow	关闭浮层或展示定位箭头	按需

基础用法

查看代码

<script setup lang="ts">
import { Button } from '@/components/loongship/button'
import {
  Popover,
  PopoverArrow,
  PopoverContent,
  PopoverPortal,
  PopoverTrigger
} from '@/components/loongship/popover'
</script>

<template>
  <Popover>
    <PopoverTrigger as-child>
      <Button variant="outline">查看船舶状态</Button>
    </PopoverTrigger>
    <PopoverPortal>
      <PopoverContent>
        <strong>EVER GIVEN</strong>
        <p>IMO 9811000 · 航行中</p>
        <PopoverArrow />
      </PopoverContent>
    </PopoverPortal>
  </Popover>
</template>

轻量表单

查看代码

<template>
  <Popover>
    <PopoverTrigger as-child><Button>修改目的港</Button></PopoverTrigger>
    <PopoverPortal>
      <PopoverContent align="start">
        <label class="popover-demo-form"><span>目的港</span><Input v-model="destination" /></label>
        <div class="popover-demo-actions">
          <PopoverClose as-child><Button size="sm">保存</Button></PopoverClose>
        </div>
        <PopoverArrow />
      </PopoverContent>
    </PopoverPortal>
  </Popover>
</template>

受控状态

Open: false

查看代码

<template>
  <div class="vp-demo-showcase-column">
    <Popover v-model:open="open">
      <PopoverTrigger as-child><Button variant="outline">打开提醒</Button></PopoverTrigger>
      <span>Open: {{ open }}</span>
      <PopoverPortal>
        <PopoverContent side="right">
          该船预计在 24 小时内抵达目的港。
          <div class="popover-demo-actions">
            <PopoverClose as-child><Button size="sm">知道了</Button></PopoverClose>
          </div>
          <PopoverArrow />
        </PopoverContent>
      </PopoverPortal>
    </Popover>
  </div>
</template>

API

Popover（主组件）

属性

属性	类型	默认值	说明
v-model:open	boolean	-	受控显示状态
defaultOpen	boolean	false	非受控模式的初始状态
modal	boolean	false	是否禁用外部交互

事件

事件	参数	说明
update:open	value: boolean	显示状态改变时触发

插槽

插槽	参数	说明
default	{ open: boolean, close: () => void }	浮层结构

子组件

PopoverTrigger / PopoverClose / PopoverAnchor — 触发、关闭与定位锚点

属性

属性	类型	默认值	说明
as	string | Component	-	渲染元素
asChild	boolean	false	合并到唯一子元素

插槽

组件	插槽	参数	说明
PopoverTrigger	default	—	打开按钮内容
PopoverClose	default	—	关闭按钮内容
PopoverAnchor	default	—	自定义锚点

PopoverPortal — 浮层传送容器

属性

属性	类型	默认值	说明
to	string | HTMLElement	'body'	Teleport 目标
disabled	boolean	false	是否禁用 Teleport
defer	boolean	false	是否延迟解析目标

插槽

插槽	参数	说明
default	—	浮层传送内容

PopoverContent — 浮层内容与定位

属性

属性	类型	默认值	说明
side	'top' | 'right' | 'bottom' | 'left'	'bottom'	展开方向
sideOffset	number	4	与锚点的距离
align	'start' | 'center' | 'end'	'center'	对齐方式
alignOffset	number	0	对齐偏移
avoidCollisions	boolean	true	是否自动避让视口边缘
collisionPadding	number | object	0	碰撞检测边距
sticky	'partial' | 'always'	'partial'	锚点离屏时的定位策略
hideWhenDetached	boolean	false	锚点完全离屏时是否隐藏
forceMount	boolean	false	关闭时仍挂载，便于自定义动画
disableOutsidePointerEvents	boolean	false	是否禁用外部指针交互
class	ClassValue	-	自定义类名

事件

事件	参数	说明
escapeKeyDown	KeyboardEvent	按下 Escape 时触发
pointerDownOutside	PointerDownOutsideEvent	在内容外按下指针时触发
focusOutside	FocusOutsideEvent	焦点移到内容外时触发
interactOutside	PointerDownOutsideEvent | FocusOutsideEvent	在内容外发生交互时触发
openAutoFocus	Event	打开后自动聚焦前触发
closeAutoFocus	Event	关闭后恢复焦点前触发

插槽

插槽	参数	说明
default	—	浮层内容

PopoverArrow — 定位箭头

属性

属性	类型	默认值	说明
width	number	10	箭头宽度
height	number	5	箭头高度
rounded	boolean	false	是否使用圆角
as	string | Component	'svg'	渲染元素
asChild	boolean	false	合并到唯一子元素
class	ClassValue	-	自定义类名

插槽

插槽	参数	说明
default	—	自定义箭头内容