Overlay 遮罩层 - Vant 4

🎭 Overlay 遮罩层

🎯 介绍

Overlay 组件创建一个遮罩层，用于强调特定的页面元素，并阻止用户进行其他操作。让页面焦点更加突出！

📦 引入

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

import { createApp } from'vue'; import { Overlay } from'vant'; const app = createApp(); app.use(Overlay);

🎯 代码演示

🔧 基础用法

最简单的遮罩层，就像给页面蒙上一层神秘面纱 🎭

<template>
  <div>
    <van-button type="primary" @click="show = true">显示遮罩层</van-button>
    <van-overlay :show="show" @click="show = false" />
  </div>
</template>

<script setup>
import { ref } from 'vue';

const show = ref(false);
</script>

📦 嵌入内容

在遮罩层上放置任何内容，让重要信息脱颖而出 ✨

<template>
  <div>
    <van-button type="primary" @click="show = true">嵌入内容</van-button>
    <van-overlay :show="show" @click="show = false">
      <div class="wrapper">
        <div class="block" @click.stop>
          <h3>这是嵌入的内容 📝</h3>
          <p>点击遮罩层外部可以关闭</p>
          <van-button type="primary" @click="show = false">关闭</van-button>
        </div>
      </div>
    </van-overlay>
  </div>
</template>

<script setup>
import { ref } from 'vue';

const show = ref(false);
</script>

<style>
.wrapper {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 100%;
}

.block {
  width: 120px;
  height: 120px;
  background-color: #fff;
  border-radius: 8px;
  padding: 20px;
  text-align: center;
}
</style>

🔢 设置 z-index

控制遮罩层的显示层级，让它在合适的位置出现 📚

<template>
  <div>
    <van-button type="primary" @click="show = true">高层级遮罩</van-button>
    <van-overlay :show="show" :z-index="100" @click="show = false">
      <div class="wrapper">
        <div class="block" @click.stop>
          <p>z-index: 100 🔝</p>
          <van-button size="small" @click="show = false">关闭</van-button>
        </div>
      </div>
    </van-overlay>
  </div>
</template>

<script setup>
import { ref } from 'vue';

const show = ref(false);
</script>

<style>
.wrapper {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 100%;
}

.block {
  width: 120px;
  height: 80px;
  background-color: #fff;
  border-radius: 8px;
  padding: 20px;
  text-align: center;
}
</style>

API

Props

参数	说明	类型	默认值
show	是否展示遮罩层，控制遮罩的显示隐藏 👁️	boolean	false
z-index	z-index 层级，控制遮罩的显示层次 📚	number | string	1
duration	动画时长，单位秒，设置为 0 可以禁用动画 ⏱️	number | string	0.3
class-name	自定义类名，添加个性化样式 🎨	string	-
custom-style	自定义样式，直接设置样式对象 ✨	object	-
lock-scroll	是否锁定背景滚动，锁定时蒙层里的内容也将无法滚动 🔒	boolean	true
lazy-render	是否在显示时才渲染节点，优化性能 🚀	boolean	true
teleport	指定挂载的节点，等同于 Teleport 组件的 to 属性 🎯	string | Element	-

Events

事件名	说明	回调参数
click	点击时触发，处理遮罩层点击事件 👆	event: MouseEvent

Slots

名称	说明
default	默认插槽，用于在遮罩层上方嵌入内容 📦

类型定义

组件导出以下类型定义，让 TypeScript 开发更顺畅 📝

importtype { OverlayProps } from'vant';

主题定制

样式变量

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

名称	默认值	描述
--van-overlay-z-index	1	遮罩层级 📚
--van-overlay-background	rgba(0, 0, 0, 0.7)	遮罩背景色 🎨

📚 相关文档

弹出类组件

• Popup 弹出层 - 功能强大的弹出层组件，支持多种弹出位置 📱
• Dialog 弹出框 - 对话框和确认框组件，用户交互必备 💬
• ActionSheet 动作面板 - 底部动作选择面板，操作选项清晰 📋
• Popover 气泡弹出框 - 轻量级的气泡提示组件 💭

反馈类组件

• Toast 轻提示 - 轻量级的消息提示组件 🍞
• Notify 消息通知 - 顶部消息通知栏组件 📢
• Loading 加载 - 加载状态指示器，提升用户体验 ⏳

导航类组件

• NavBar 导航栏 - 页面顶部导航栏组件 🧭
• Tabbar 标签栏 - 底部标签栏导航组件 📱
• Sidebar 侧边导航 - 侧边栏导航组件 📋