更新记录

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

• 初始版本，按 u-ui 目标标准（vant-* Vue3 TS + 独立 props.ts/scss + $uni-* 令牌）从零封装。
• 对齐 Vant 4 Popup API：v-model:show、position、overlay、duration、round、closeable + 关闭图标位置、close-on-click-overlay、safe-area-inset-bottom、overlay-class/overlay-style、z-index。
• 事件：update:show / open / close / click-overlay / opened / closed。
• 插槽：default（内容）、overlay（自定义遮罩）。
• 交互态：disabled（禁用不渲染交互）、loading（加载态 + 屏蔽关闭）。
• 关闭图标与加载 spinner 均为纯 CSS 绘制，零三方依赖。
• 迁移自遗留 uni-app x 风格空脚手架（vant-popup.vue 原为空模板）。

平台兼容性

uni-app(3.8.5)

uni-app x(3.8.5)

其他

vant-popup 弹出层

在页面上方弹出的浮层容器，用于菜单、弹窗、信息提示等场景。基于 Vant 4 Popup API 封装，零业务耦合、数据驱动。

引入

<vant-popup /> 经 easycom 自动注册，无需 import。如需显式引入：

import vantPopup from 'uni_modules/vant-popup/components/vant-popup/vant-popup.vue'

代码演示

基础用法

通过 v-model:show 控制显隐，默认从中心弹出。

<template>
  <vant-button text="打开弹出层" @click="show = true" />
  <vant-popup v-model:show="show">
    <view style="padding: 60rpx;">我是弹出层内容</view>
  </vant-popup>
</template>

<script setup lang="ts">
import { ref } from 'vue'
const show = ref(false)
</script>

弹出位置

通过 position 指定弹出方向：top / bottom / left / right / center。

<vant-popup v-model:show="show" position="bottom" :round="true">
  <view style="height: 400rpx; padding: 32rpx;">底部弹出 + 圆角</view>
</vant-popup>

关闭图标

设置 closeable 显示关闭按钮，close-icon-position 控制位置。

<vant-popup
  v-model:show="show"
  position="bottom"
  :round="true"
  :closeable="true"
  close-icon-position="top-right"
>
  <view style="padding: 32rpx;">带关闭图标的弹层</view>
</vant-popup>

禁用遮罩关闭 / 自定义遮罩

<!-- 点击遮罩不关闭 -->
<vant-popup v-model:show="show" :close-on-click-overlay="false" :closeable="true" />

<!-- 自定义遮罩内容（通过 #overlay 插槽） -->
<vant-popup v-model:show="show">
  <template #overlay>
    <view class="my-overlay-mask" />
  </template>
  <view style="padding: 32rpx;">自定义遮罩</view>
</vant-popup>

禁用与加载态

disabled 时弹层不响应（即便 show=true 也不渲染交互）；loading 时展示 loading 并屏蔽关闭。

<vant-popup v-model:show="show" :disabled="true" />
<vant-popup v-model:show="show" :loading="true" />

API

Props

Events

Slots

主题定制

通过覆盖宿主 uni.scss 的 $uni-* 令牌调整外观：

• $uni-bg-color-mask：遮罩背景色
• $uni-bg-color：弹出层背景色
• $uni-color-primary：加载态 spinner 主色
• $uni-text-color-grey：关闭图标颜色

弹出层圆角：在 vant-popup.scss 内定义为组件常量 $popup-radius，值为官方 $uni-border-radius-lg 的两倍（$uni-border-radius-lg * 2）。如需调整，直接改该常量即可，无需动宿主令牌。

常见问题

• Q：position 为 top/bottom 时 round 圆角在哪？ A：圆角作用于「弹出侧」的顶角（top 在底部两角、bottom 在顶部两角，依此类推），符合 Vant 视觉习惯。
• Q：小程序里背景还能滚动吗？ A：弹层打开时遮罩与内容层均拦截 touchmove（@touchmove.stop.prevent），默认锁定背景滚动；不需要可设 :lock-scroll="false"（交互层仍拦截，仅语义保留）。
• Q：disabled 与 loading 的区别？ A：disabled 让弹层整体不渲染交互（常用于权限/条件未满足）；loading 仍显示弹层但展示 loading 且屏蔽关闭，用于异步等待。