Vant

繁體中文

简体中文
English

繁體中文

简体中文
English

Appearance

Popup 弹出层 - Vant 4

📱 Popup 弹出层 ​

🎯 介绍 ​

弹出层容器，用于展示弹窗、信息提示等内容，支持多个弹出层叠加展示，就像舞台上的幕布，为内容提供完美的展示空间 🎭

📦 引入 ​

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

js
import { createApp } from 'vue';
import { Popup } from 'vant';

const app = createApp();
app.use(Popup);

🚀 代码演示 ​

🔧 基础用法 ​

通过 v-model:show 控制弹出层是否展示，简单直观的显示控制 ✨

html
<van-cell is-link @click="showPopup">展示弹出层</van-cell>
<van-popup v-model:show="show" :style="{ padding: '64px' }">内容</van-popup>
js
import { ref } from 'vue';

export default {
  setup() {
    const show = ref(false);
    
    // 显示弹出层，开启内容展示 🎬
    const showPopup = () => {
      show.value = true;
    };

    return {
      show,
      showPopup,
    };
  },
};

🧭 弹出位置 ​

通过 position 属性设置弹窗的弹出位置，默认为居中弹出，可以设置为 top、bottom、left、right，就像指挥家指挥乐团一样精准定位 🎼

  • 当弹窗从顶部或底部弹出时，默认宽度与屏幕宽度保持一致，弹窗高度取决于内容的高度 📏
  • 当弹窗从左侧或右侧弹出时，默认不设置宽度和高度，弹窗的宽高取决于内容的宽高 📐
html
<van-cell-group>
  <van-cell is-link @click="showPopup('top')">顶部弹出</van-cell>
  <van-cell is-link @click="showPopup('bottom')">底部弹出</van-cell>
  <van-cell is-link @click="showPopup('left')">左侧弹出</van-cell>
  <van-cell is-link @click="showPopup('right')">右侧弹出</van-cell>
</van-cell-group>

<van-popup
  v-model:show="show.top"
  position="top"
  :style="{ height: '30%' }"
/>
<van-popup
  v-model:show="show.bottom"
  position="bottom"
  :style="{ height: '30%' }"
/>
<van-popup
  v-model:show="show.left"
  position="left"
  :style="{ width: '30%', height: '100%' }"
/>
<van-popup
  v-model:show="show.right"
  position="right"
  :style="{ width: '30%', height: '100%' }"
/>
js
import { reactive } from 'vue';

export default {
  setup() {
    // 多个弹出层状态管理，井然有序 🎯
    const show = reactive({
      top: false,
      bottom: false,
      left: false,
      right: false,
    });
    
    const showPopup = (position) => {
      show[position] = true;
    };

    return {
      show,
      showPopup,
    };
  },
};

❌ 关闭图标 ​

设置 closeable 属性后，会在弹出层的右上角显示关闭图标，并且可以通过 close-icon 属性自定义图标，使用 close-icon-position 属性可以自定义图标位置，让用户轻松找到退出方式 🚪

html
<van-cell is-link @click="showPopup">关闭图标</van-cell>
<van-popup
  v-model:show="show"
  closeable
  position="bottom"
  :style="{ height: '30%' }"
/>

<!-- 自定义图标 -->
<van-popup
  v-model:show="show"
  closeable
  close-icon="close"
  position="bottom"
  :style="{ height: '30%' }"
/>

<!-- 图标位置 -->
<van-popup
  v-model:show="show"
  closeable
  close-icon-position="top-left"
  position="bottom"
  :style="{ height: '30%' }"
/>
js
import { ref } from 'vue';

export default {
  setup() {
    const show = ref(false);
    
    // 显示带关闭图标的弹出层 ❌
    const showPopup = () => {
      show.value = true;
    };

    return {
      show,
      showPopup,
    };
  },
};

🔘 圆角弹窗 ​

设置 round 属性后，弹窗会根据弹出位置添加不同的圆角样式，打造更加柔和的视觉效果 🌙

html
<van-cell is-link @click="showPopup">圆角弹窗</van-cell>
<van-popup
  v-model:show="show"
  round
  position="bottom"
  :style="{ height: '30%' }"
/>
js
import { ref } from 'vue';

export default {
  setup() {
    const show = ref(false);
    
    // 显示圆角弹窗，更加美观 🎨
    const showPopup = () => {
      show.value = true;
    };

    return {
      show,
      showPopup,
    };
  },
};

👆 监听点击事件 ​

Popup 支持以下点击事件，提供丰富的交互反馈 🎮

  • click: 点击弹出层时触发，内容区域交互 📱
  • click-overlay: 点击遮罩层时触发，背景区域交互 🎭
  • click-close-icon: 点击关闭图标时触发，关闭按钮交互 ❌
html
<van-cell is-link @click="showPopup">监听点击事件</van-cell>
<van-popup
  v-model:show="show"
  closeable
  position="bottom"
  :style="{ height: '30%', padding: '16px' }"
  @click="showToast('click')"
  @click-overlay="onClickOverlay"
  @click-close-icon="onClickCloseIcon"
>
  点击弹出层
</van-popup>
js
import { ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    const show = ref(false);
    
    // 点击遮罩层的处理函数 🎭
    const onClickOverlay = () => {
      showToast('click-overlay');
    };
    
    // 点击关闭图标的处理函数 ❌
    const onClickCloseIcon = () => {
      showToast('click-close-icon');
    };

    return {
      show,
      showToast,
      onClickOverlay,
      onClickCloseIcon,
    };
  },
};

📡 监听显示事件 ​

当 Popup 被打开或关闭时，会触发以下事件，让你掌控每个时刻 ⏰

  • open: 打开弹出层时立即触发，开始显示 📂
  • opened: 打开弹出层且动画结束后触发，完全显示 ✨
  • close: 关闭弹出层时立即触发，开始隐藏 📁
  • closed: 关闭弹出层且动画结束后触发，完全隐藏 🎭
html
<van-cell is-link @click="showPopup">监听显示事件</van-cell>
<van-popup
  v-model:show="show"
  position="bottom"
  :style="{ height: '30%' }"
  @open="showToast('open')"
  @opened="showToast('opened')"
  @close="showToast('close')"
  @closed="showToast('closed')"
/>
js
import { ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    const show = ref(false);
    
    // 显示弹出层，触发各种生命周期事件 🎬
    const showPopup = () => {
      show.value = true;
    };

    return {
      show,
      showPopup,
      showToast,
    };
  },
};

🚀 指定挂载位置 ​

弹出层默认挂载到组件标签所在位置，可以通过 teleport 属性指定挂载位置，灵活控制渲染位置 🎯

html
<!-- 挂载到 body -->
<van-popup v-model:show="show" teleport="body" />

<!-- 挂载到 #app -->
<van-popup v-model:show="show" teleport="#app" />
js
import { ref } from 'vue';

export default {
  setup() {
    const show = ref(false);

    return {
      show,
    };
  },
};

📋 API ​

🎛️ Props ​

参数说明类型默认值
v-model:show是否显示弹出层，控制弹窗的显示状态 🎯booleanfalse
overlay是否显示遮罩层，提供背景遮挡效果 🎭booleantrue
position弹出位置，可选值为 top bottom right left，精准定位弹窗位置 🧭stringcenter
overlay-class自定义遮罩层类名，个性化遮罩样式 🎨string | Array | object-
overlay-style自定义遮罩层样式，灵活控制遮罩外观 ✨object-
duration动画时长，单位秒，控制弹窗动画速度 ⏱️number | string0.3
z-index将弹窗的 z-index 层级设置为一个固定值，控制层级关系 📚number | string2000+
round是否显示圆角，打造柔和视觉效果 🔘booleanfalse
lock-scroll是否锁定背景滚动，防止内容穿透 🔒booleantrue
lazy-render是否在显示弹层时才渲染节点，优化性能表现 🚀booleantrue
close-on-popstate是否在页面回退时自动关闭，提升用户体验 ⬅️booleantrue
close-on-click-overlay是否在点击遮罩层后关闭，便捷的关闭方式 👆booleantrue
closeable是否显示关闭图标，提供明确的关闭入口 ❌booleanfalse
close-icon关闭图标名称或图片链接，等同于 Icon 组件的 name 属性 🎯stringcross
close-icon-position关闭图标位置，可选值为 top-left top-right bottom-left bottom-right，灵活定位 📍stringtop-right
before-close关闭前的回调函数，返回 false 可阻止关闭，确认关闭操作 🛡️Function-
icon-prefix图标类名前缀，等同于 Icon 组件的 class-prefix 属性 🏷️stringvan-icon
transition动画类名，等价于 transition 的 name 属性 🎬string-
transition-appear是否在初始渲染时启用过渡动画，增强视觉体验 ✨booleanfalse
teleport指定挂载的节点，等同于 Teleport 组件的 to 属性 🎯string | Element-
safe-area-inset-top是否开启顶部安全区适配，适配刘海屏 📱booleanfalse
safe-area-inset-bottom是否开启底部安全区适配，适配底部操作区 📱booleanfalse

🎪 Events ​

事件名说明回调参数
click点击弹出层时触发，内容区域交互反馈 📱event: MouseEvent
click-overlay点击遮罩层时触发，背景区域交互反馈 🎭event: MouseEvent
click-close-icon点击关闭图标时触发，关闭按钮交互反馈 ❌event: MouseEvent
open打开弹出层时立即触发，开始显示动画 📂-
close关闭弹出层时立即触发，开始隐藏动画 📁-
opened打开弹出层且动画结束后触发，完全显示状态 ✨-
closed关闭弹出层且动画结束后触发，完全隐藏状态 🎭-

🎨 Slots ​

名称说明
default弹窗内容，展示主要信息和交互元素 📄
overlay自定义遮罩层，个性化背景效果 🎭

🏷️ 类型定义 ​

组件导出以下类型定义：

ts
import type {
  PopupProps,
  PopupPosition,
  PopupInstance,
  PopupThemeVars,
  PopupCloseIconPosition,
} from 'vant';

PopupInstance 是组件实例的类型，用法如下：

ts
import { ref } from 'vue';
import type { PopupInstance } from 'vant';

const popupRef = ref<PopupInstance>();

🎨 主题定制 ​

🎭 样式变量 ​

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称默认值描述
--van-popup-backgroundvar(--van-background-2)弹窗背景色，营造舒适的内容展示环境 🏠
--van-popup-transitiontransform var(--van-duration-base)弹窗过渡动画，流畅的显示隐藏效果 🎬
--van-popup-round-radius16px圆角弹窗的圆角大小，柔和的视觉边界 🔘
--van-popup-close-icon-size22px关闭图标的大小，清晰的操作标识 ❌
--van-popup-close-icon-colorvar(--van-gray-5)关闭图标的颜色，和谐的视觉层次 🎨
--van-popup-close-icon-margin16px关闭图标的外边距，合适的点击区域 📏
--van-popup-close-icon-z-index1关闭图标的层级，确保可点击性 📚

📚 相关文档 ​

🔗 相关组件 ​

基於Vant構建的企業級移動端解決方案

Copyright © 2025 siex.cn ｜ sitemap