更新记录

1.0.0（2026-02-21） 下载此版本

1.0.0（2026-02-21）

• 首次发布
• 支持 5 个弹出方向：top / bottom / center / left / right
• 支持 3 个类型别名：message / dialog / share，兼容 uni-popup 用法
• 纯 CSS transition 驱动动画，transitionend 回调 + setTimeout 兜底
• v-model:show 双向绑定，声明式 + 命令式双模式
• round 快捷圆角，根据方向自动计算圆角位置
• closeable 内置关闭图标，支持四角定位
• before-close 异步拦截关闭，支持 Promise / Boolean
• opened / closed 动画完成事件
• z-index 全局自增，多弹窗叠加层级正确
• 四方向手势滑动关闭，阈值可配
• 滚动穿透锁定（touchmove + H5 body overflow）
• CSS Variables 主题定制
• provide/inject 子组件通信
• Promise 化 API，open()/close() 返回 Promise
• 底部安全区自动适配
• ESC 键关闭（H5）
• keep-alive 支持
• Vue2 / Vue3 双兼容
• 全端兼容：H5、App、微信/支付宝/百度/抖音/QQ 小程序

平台兼容性

uni-app(4.0)

其他

ay-popup 高级弹出层

高性能 uni-app 弹出层组件，解决 uni-popup 核心痛点，全端兼容。

为什么选择 ay-popup

ay-popup 逐一解决这些痛点：

特性一览

• 纯 CSS transition 驱动动画，transitionend 精确回调 + setTimeout 兜底
• 5 个弹出方向：top / bottom / center / left / right
• 3 个类型别名：message(top) / dialog(center) / share(bottom)，兼容 uni-popup 用法
• v-model:show 双向绑定，声明式 + 命令式双模式
• round 快捷圆角，根据方向自动计算圆角位置
• closeable 内置关闭图标，支持四角定位
• before-close 异步拦截关闭，支持 Promise / Boolean
• opened / closed 动画完成事件（区别于 open / close 立即事件）
• z-index 全局自增，多弹窗叠加层级正确
• 四方向手势滑动关闭，阈值可配
• 滚动穿透锁定（touchmove + H5 body overflow）
• CSS Variables 主题定制
• provide/inject 子组件通信
• Promise 化 API，open()/close() 均返回 Promise
• 底部安全区自动适配
• ESC 键关闭（H5）
• keep-alive 支持
• Vue2 / Vue3 双兼容
• 全端兼容：H5、App、微信/支付宝/百度/抖音/QQ 小程序

安装

在 HBuilderX 中，从插件市场导入即可使用，无需额外配置。

快速开始

命令式调用

<template>
  <ay-popup ref="popup" type="bottom" round background="#fff">
    <view style="padding: 40rpx;">
      <text>底部弹窗内容</text>
      <button @click="$refs.popup.close()">关闭</button>
    </view>
  </ay-popup>
  <button @click="$refs.popup.open()">打开弹窗</button>
</template>

声明式调用（v-model）

<template>
  <ay-popup v-model:show="visible" type="center" round>
    <view style="padding: 40rpx;">
      <text>居中弹窗</text>
      <button @click="visible = false">关闭</button>
    </view>
  </ay-popup>
  <button @click="visible = true">打开弹窗</button>
</template>

<script>
export default {
  data() {
    return { visible: false }
  }
}
</script>

五个方向

<!-- 居中弹窗 -->
<ay-popup ref="center" type="center" round>
  <view class="content">居中</view>
</ay-popup>

<!-- 底部弹窗 -->
<ay-popup ref="bottom" type="bottom" round background="#fff">
  <view class="content">底部</view>
</ay-popup>

<!-- 顶部弹窗 -->
<ay-popup ref="top" type="top" round background="#fff">
  <view class="content">顶部</view>
</ay-popup>

<!-- 左侧抽屉 -->
<ay-popup ref="left" type="left" background="#fff">
  <view style="width: 500rpx; height: 100%; padding: 40rpx;">左侧</view>
</ay-popup>

<!-- 右侧抽屉 -->
<ay-popup ref="right" type="right" background="#fff">
  <view style="width: 500rpx; height: 100%; padding: 40rpx;">右侧</view>
</ay-popup>

圆角模式

round 属性会根据弹出方向自动计算圆角位置，无需手动设置 border-radius。

<!-- 底部弹窗：左上 + 右上圆角 -->
<ay-popup type="bottom" round />

<!-- 顶部弹窗：左下 + 右下圆角 -->
<ay-popup type="top" round />

<!-- 居中弹窗：四角圆角 -->
<ay-popup type="center" round />

<!-- 左侧抽屉：右上 + 右下圆角 -->
<ay-popup type="left" round />

<!-- 也可以自定义圆角 -->
<ay-popup type="bottom" border-radius="20px 20px 0 0" />

关闭图标

<ay-popup type="bottom" round closeable>
  <view style="padding: 60rpx 40rpx 40rpx;">
    内置关闭图标，默认右上角
  </view>
</ay-popup>

<!-- 自定义位置 -->
<ay-popup type="bottom" round closeable close-icon-position="top-left">
  <view>关闭图标在左上角</view>
</ay-popup>

关闭拦截（before-close）

<ay-popup ref="popup" :before-close="onBeforeClose">
  <view>关闭前会触发拦截</view>
</ay-popup>

<script>
export default {
  methods: {
    // 方式一：返回 Promise
    onBeforeClose() {
      return new Promise(resolve => {
        // resolve(true) 允许关闭，resolve(false) 阻止关闭
        uni.showModal({
          title: '确认关闭？',
          success: res => resolve(res.confirm)
        })
      })
    }
    // 方式二：直接返回 Boolean
    // onBeforeClose() { return false }
  }
}
</script>

注意：H5 端如果 uni.showModal 被 ay-popup 遮罩遮挡，建议用另一个 ay-popup 实例做确认弹窗，z-index 自增机制会确保它在最上层。

手势滑动关闭

<ay-popup type="bottom" round :swipe-close="true" :swipe-threshold="80">
  <view style="min-height: 60vh; padding: 40rpx;">
    向下拖拽超过 80px 自动关闭
  </view>
</ay-popup>

支持四个方向的手势关闭：底部弹窗下滑、顶部弹窗上滑、左侧抽屉左滑、右侧抽屉右滑。

多层叠加

<ay-popup ref="layer1" type="center" round>
  <view>
    <text>第一层</text>
    <button @click="$refs.layer2.open()">打开第二层</button>
  </view>
</ay-popup>

<ay-popup ref="layer2" type="bottom" round closeable>
  <view>第二层，z-index 自动高于第一层</view>
</ay-popup>

Promise API

// open() 在动画结束后 resolve
await this.$refs.popup.open()
console.log('弹窗已完全打开')

// close() 在动画结束后 resolve（受 before-close 拦截）
await this.$refs.popup.close()
console.log('弹窗已完全关闭')

自定义遮罩

<ay-popup
  mask-background="rgba(0,0,0,0.7)"
  overlay-class="my-overlay"
  :overlay-style="{ backdropFilter: 'blur(4px)' }"
>
  <view>自定义遮罩样式</view>
</ay-popup>

子组件通信

子组件可通过 inject 获取 ay-popup 实例，直接调用 close() 等方法。

export default {
  inject: ['ayPopup'],
  methods: {
    handleConfirm() {
      // 处理业务逻辑后关闭弹窗
      this.ayPopup.close()
    }
  }
}

CSS Variables 主题定制

/* 在页面或全局样式中覆盖 */
page {
  --ay-popup-bg: #fff;                                        /* 内容区背景 */
  --ay-popup-overlay-bg: rgba(0, 0, 0, 0.4);                  /* 遮罩背景 */
  --ay-popup-round-radius: 32rpx;                              /* round 圆角大小 */
  --ay-popup-timing: cubic-bezier(0.36, 0.66, 0.04, 1);       /* 动画曲线 */
  --ay-popup-close-size: 60rpx;                                /* 关闭图标区域大小 */
  --ay-popup-close-font-size: 32rpx;                           /* 关闭图标字号 */
  --ay-popup-close-color: #969799;                             /* 关闭图标颜色 */
}

Props

Methods

通过 ref 调用：

Events

CSS Variables

兼容性

从 uni-popup 迁移

ay-popup 兼容 uni-popup 的 type 别名，迁移成本低：

主要差异：

• ay-popup 额外支持 v-model:show 声明式用法
• open() / close() 返回 Promise
• 新增 round、closeable、before-close、swipe-close 等属性
• 新增 opened、closed 动画完成事件

许可

MIT License