更新记录

1.0.0（2025-12-07） 下载此版本

appx-popup 是基于 Uniapp + UTS 开发的通用弹窗组件，支持多方向弹出（上/右/下/中）、自定义样式、遮罩控制、安全区适配等能力

平台兼容性

uni-app x(4.87)

appx-popup 弹窗组件帮助文档

组件介绍

appx-popup 是基于 Uniapp + UTS 开发的通用弹窗组件，支持多方向弹出（上/右/下/中）、自定义样式、遮罩控制、安全区适配等能力，适用于各类弹窗交互场景，具备良好的动画过渡和可扩展性。

组件特性

• 支持 top/right/bottom/center 四种弹出方向，中心弹窗可配置缩放动画
• 自定义遮罩样式、透明度，支持点击遮罩关闭弹窗
• 内置关闭图标，支持多位置配置，hover 效果适配 H5 端
• 适配移动端安全区（顶部/底部），支持圆角、背景色自定义
• 动画过渡时长可配置，保证多端动画一致性

快速使用

基础用法

<template>
  <view>
    <button @click="showPopup = true">打开底部弹窗</button>
    <appx-popup
      :show="showPopup"
      mode="bottom"
      round="16"
      @close="showPopup = false"
    >
      <view class="popup-content">
        <text>这是底部弹出的弹窗内容</text>
        <button @click="showPopup = false">关闭弹窗</button>
      </view>
    </appx-popup>
  </view>
</template>

<script lang="uts" setup>
const showPopup = ref(false);
</script>

中心缩放弹窗

<appx-popup
  :show="showCenterPopup"
  mode="center"
  zoom
  round="12"
  bgColor="#fff"
  @close="showCenterPopup = false"
>
  <view style="width: 280px; padding: 20px;">
    <text>中心缩放弹窗</text>
  </view>
</appx-popup>

API 说明

Props

Events

样式自定义

1. 基础样式覆盖

通过 customStyle 直接覆盖弹窗容器样式：

<appx-popup
  :show="showPopup"
  :customStyle="{ width: '200px', padding: '15px' }"
/>

2. 遮罩样式自定义

<!-- 方式1：直接传样式对象 -->
<appx-popup :overlayStyle="{ backgroundColor: 'rgba(255, 255, 255, 0.8)' }" />

<!-- 方式2：传 cssText 字符串（兼容特殊样式） -->
<appx-popup :overlayStyle="{ cssText: 'background: #000; opacity: 0.6;' }" />

3. 关闭图标样式修改

组件内置关闭图标样式可通过 scoped 样式穿透修改：

<style scoped>
:deep(.popup-close-icon) {
  width: 40px;
  height: 40px;
}

:deep(.close-icon__inner) {
  font-size: 24px;
  color: #ff4400;
}
</style>

注意事项

1. overlayStyle 与 overlayOpacity 互斥，同时设置时 overlayStyle 优先级更高；
2. round 属性仅对 top/bottom/center 模式生效，right 模式不支持圆角；
3. 组件依赖 Uniapp 环境，需确保项目已配置 UTS 编译环境；
4. 安全区适配依赖 env(safe-area-inset-bottom/top)，需在项目根目录 pages.json 中配置 viewport-fit=cover；
5. 中心弹窗（center 模式）默认最大宽/高为 90%/80%，可通过 customStyle 覆盖。

常见问题

Q1：弹窗动画不生效？

A1：组件已在 onMounted 中强制触发重绘保证动画生效，若仍不生效，检查：

• show 参数是否为动态修改（需通过 ref 响应式变量控制）；
• 未覆盖弹窗容器的 transition 样式；
• 确保 duration 参数为合法数字（非字符串或负数）。

Q2：关闭图标不显示？

A2：需先设置 closeable="true"，同时检查 closeIconPos 配置是否合法，且弹窗内容容器有足够空间显示图标。

Q3：安全区适配无效？

A3：需在项目 pages.json 中配置：

{
  "globalStyle": {
    "viewportFit": "cover"
  }
}