更新记录

1.0.0（2026-10-08）下载此版本

首个版本，实现组件基础能力，支持 Vue2 / Vue3、全平台（App / H5 / 各家小程序）。

平台兼容性

uni-app(4.01)

Vue2	Vue3	Chrome	Safari	app-vue	app-nvue	Android	iOS	鸿蒙
-	-	√	√	√	√	-	-	-

微信小程序	支付宝小程序	抖音小程序	百度小程序	快手小程序	京东小程序	鸿蒙元服务	QQ小程序	飞书小程序	小红书小程序	快应用-华为	快应用-联盟
√	√	√	√	√	√	-	√	√	-	-	-

e-popup 弹出层

弹出层组件，支持五种弹出位置、遮罩与过渡动画、安全区适配，可用于弹窗、底部选择器、确认框等场景。

特性

五种位置：top / bottom / left / right / center
遮罩透明度可调，点击遮罩可关闭
平滑的进出场动画（位移动画 + 透明度过渡）
底部安全区自动适配（iPhone 全面屏）
内容区可选择是否允许滚动

基本用法

<template>
  <view>
    <button @click="show = true">打开弹窗</button>

    <!-- 底部弹出 -->
    <e-popup v-model="show" mode="bottom" height="600rpx">
      <view class="popup-body">
        <text>这里是底部弹出内容</text>
      </view>
    </e-popup>

    <!-- 居中弹窗 -->
    <e-popup v-model="showCenter" mode="center" width="560rpx">
      <view class="dialog">
        <text class="dialog-title">提示</text>
        <text class="dialog-content">确认要删除这条记录吗？</text>
        <view class="dialog-footer">
          <text @click="showCenter = false">取消</text>
          <text class="primary" @click="confirm">确定</text>
        </view>
      </view>
    </e-popup>
  </view>
</template>

<script>
export default {
  data() {
    return {
      show: false,
      showCenter: false
    }
  },
  methods: {
    confirm() {
      this.showCenter = false
    }
  }
}
</script>

属性

属性名	类型	默认值	说明
`modelValue`	Boolean	`false`	是否显示，支持 `v-model`
`mode`	String	`bottom`	弹出位置：`top` / `bottom` / `left` / `right` / `center`
`mask`	Boolean	`true`	是否显示遮罩
`maskClickClose`	Boolean	`true`	点击遮罩是否关闭
`maskOpacity`	Number	`0.5`	遮罩透明度，取值 0~1
`width`	String	`auto`	内容宽度，`left` / `right` / `center` 模式生效
`height`	String	`auto`	内容高度，`top` / `bottom` 模式生效
`radius`	String	`16rpx`	圆角大小
`safeArea`	Boolean	`true`	是否适配底部安全区
`duration`	Number	`300`	动画时长（毫秒）
`scrollable`	Boolean	`true`	内容区是否允许滚动
`zIndex`	Number \| String	`999`	层级

事件

事件名	说明
`open`	打开时触发
`close`	关闭动画结束后触发
`maskClick`	点击遮罩时触发
`change`	显示状态变化，参数 `{ show: Boolean }`

实现说明

为什么要三个状态变量？

e-popup 内部用 showPopup / visible / isShow 三个状态协同工作，这是弹出层最容易踩坑的地方：

showPopup 控制 v-if，决定 DOM 是否存在
visible 控制遮罩透明度过渡
isShow 控制内容的位移/缩放过渡

打开流程：showPopup = true → 等 DOM 挂载 → 下一帧设置 visible 与 isShow
（如果同时设置，浏览器会把「初始态」和「目标态」合并成一次计算，过渡动画就不会触发）

关闭流程：先把 visible / isShow 置 false 触发动画 → 等 duration 毫秒后销毁 DOM
（如果立刻销毁，动画会闪断；如果不销毁，会残留一个透明遮罩拦截页面所有点击）

duration 需要和 CSS 保持一致

CSS 里的 transition-duration 由内联样式写入，取的就是 duration 属性值，所以调大 duration 时动画与销毁时机是同步的，不需要额外改样式。

使用提示

内容超长怎么办？

bottom / top 模式下建议显式设置 height，并在内容外层用 scroll-view：

<e-popup v-model="show" mode="bottom" height="70vh">
  <scroll-view scroll-y style="height: 100%;">
    <!-- 长内容 -->
  </scroll-view>
</e-popup>

表单弹窗被键盘顶起

center 模式在键盘弹起时可能被遮挡。这种情况建议改用 bottom 模式，键盘弹起时内容会随之上移。

平台兼容

App (vue / nvue)、H5、全平台小程序均支持。

隐私与权限

纯前端渲染组件，不申请任何权限，不采集、不上传任何数据。