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
Popup API
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| show | boolean | — | 是否显示弹层(v-model:show 受控) |
| position | 'center' | 'bottom' | 'top' | 'left' | 'right' | 'center' | 弹层位置:center 居中 / bottom 底部 / top 顶部 / left 左侧 / right 右侧,锚定模式(传 anchor)时忽略 |
| zIndex | number | — | 显式指定 z-index;不传时由全局分配器自动递增 |
| overlay | boolean | true | 是否显示遮罩层,默认 true;锚定模式设为 false 时点击可穿透到下层 |
| closeOnClickOverlay | boolean | true | 点击遮罩(弹层外部)是否关闭,默认 true;锚定模式下点击 anchor 本身不关闭 |
| closeOnEsc | boolean | true | 按 ESC 关闭,默认 true |
| showClose | boolean | false | 是否显示右上角关闭按钮,默认 false |
| anchor | HTMLElement | — | 相对定位的锚点元素,传入后 popup 将相对于该元素定位 |
| placement | 'bottom' | 'top' | 'left' | 'right' | 'bottom' | 相对锚点的位置,默认 'bottom' |
| align | 'start' | 'center' | 'end' | 'center' | 锚定轴上的对齐方式,默认 'center' |
| offset | number | 8 | 与锚点的间距(px),默认 8 |
| boundary | HTMLElement | — | 边界约束元素,传入后 popup 将被限制在该元素范围内 |
| group | string | — | 互斥分组:同一 group 内同时只能有一个 popup 打开,打开新的会自动关闭其他的 |
| fullscreen | boolean | false | 全高档位(opt-in,仅 position="bottom" 且非锚定模式生效): 弹层拉满视口高度(100dvh + safe-top),突破 bottom 形态默认的 80dvh 上限; 用于移动端选人/重交互场景。默认 false,不影响其他 bottom 使用方。 |
| shell | boolean | true | 内容外壳(背景/边框/圆角/阴影),默认 true。 设为 false 时弹层外壳透明,由内部组件自行承担视觉外壳(如名片卡片的圆角与阴影)。 |
| to | string | HTMLElement | — | Teleport 目标(默认 'body')。嵌套弹层容器(如 demo 手机壳)场景传入 壳内元素选择器/元素,弹层随壳定位(配合壳的 transform 包含块)。 |
Events
| 事件名 | 参数 | 说明 |
|---|---|---|
update:show | value: boolean | 弹层关闭时触发(ESC/点击遮罩/关闭按钮/互斥分组关闭),负载 false,供 v-model:show 双向同步 |
close | — | 弹层关闭时触发(与 update:show(false) 同时发出),供业务侧感知关闭 |
