跳到正文

Popup 弹层 ​

通用弹层组件,支持五种位置、锚点定位与分组互斥,是 ActionSheet / Modal 等组件的底层能力。

使用方式 ​

组件以 EmPopup 为名导出,全局注册后可直接使用:

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

const show = ref(false)
</script>

<template>
  <em-button @click="show = true">打开弹层</em-button>
  <em-popup v-model:show="show" position="bottom">
    弹层内容
  </em-popup>
</template>

弹出位置 ​

锚点定位 ​

分组互斥 ​

API ​

Props ​

属性类型默认值说明
showboolean—是否显示弹层(v-model:show 受控)
position'center' | 'bottom' | 'top' | 'left' | 'right''center'弹层位置:center 居中 / bottom 底部 / top 顶部 / left 左侧 / right 右侧,锚定模式(传 anchor)时忽略
zIndexnumber—显式指定 z-index;不传时由全局分配器自动递增
overlaybooleantrue是否显示遮罩层,默认 true;锚定模式设为 false 时点击可穿透到下层
closeOnClickOverlaybooleantrue点击遮罩(弹层外部)是否关闭,默认 true;锚定模式下点击 anchor 本身不关闭
closeOnEscbooleantrue按 ESC 关闭,默认 true
showClosebooleanfalse是否显示右上角关闭按钮,默认 false
anchorHTMLElement—相对定位的锚点元素,传入后 popup 将相对于该元素定位
placement'bottom' | 'top' | 'left' | 'right''bottom'相对锚点的位置,默认 'bottom'
align'start' | 'center' | 'end''center'锚定轴上的对齐方式,默认 'center'
offsetnumber8与锚点的间距(px),默认 8
boundaryHTMLElement—边界约束元素,传入后 popup 将被限制在该元素范围内
groupstring—互斥分组:同一 group 内同时只能有一个 popup 打开,打开新的会自动关闭其他的
fullscreenbooleanfalse全高档位(opt-in,仅 position="bottom" 且非锚定模式生效):
弹层拉满视口高度(100dvh + safe-top),突破 bottom 形态默认的 80dvh 上限;
用于移动端选人/重交互场景。默认 false,不影响其他 bottom 使用方。
shellbooleantrue内容外壳(背景/边框/圆角/阴影),默认 true。
设为 false 时弹层外壳透明,由内部组件自行承担视觉外壳(如名片卡片的圆角与阴影)。
tostring | HTMLElement—Teleport 目标(默认 'body')。嵌套弹层容器(如 demo 手机壳)场景传入
壳内元素选择器/元素,弹层随壳定位(配合壳的 transform 包含块)。

Events ​

事件名参数说明
update:showvalue: boolean弹层关闭时触发(ESC/点击遮罩/关闭按钮/互斥分组关闭),负载 false,供 v-model:show 双向同步
close—弹层关闭时触发(与 update:show(false) 同时发出),供业务侧感知关闭