使用场景
提供可组合的基础遮罩容器。
局部遮罩与点击关闭
点击遮罩关闭，点击内容停止事件。
局部遮罩与点击关闭
vue
<template>
<div class="stage">
<AsamButton type="default" native-type="button" @click="open = true"
>显示局部遮罩</AsamButton
>
<AsamOverlay
v-if="open"
v-bind="{ overlayClass: 'local-overlay', zIndex: 1 }"
@click="open = false"
>
<div class="panel" @click.stop>
<p class="example-paragraph">自定义浮层内容</p>
<AsamButton type="default" native-type="button" @click="open = false"
>关闭局部遮罩</AsamButton
>
</div>
</AsamOverlay>
</div>
</template>
<script lang="ts" setup>
defineOptions({ name: 'AsamOverlayBasicDemo' });
import { ref } from 'vue';
import { AsamButton, AsamOverlay } from '@asam-ui/ui';
const open = ref(false);
</script>
<style scoped>
.stage {
position: relative;
height: 180px;
isolation: isolate;
}
.stage .local-overlay {
position: absolute;
display: grid;
place-items: center;
}
.panel {
background: var(--asam-color-surface);
padding: var(--asam-space-lg);
}
</style>
<style scoped>
p:where(.example-paragraph) {
margin-block: 16px;
line-height: 1.8;
overflow-wrap: anywhere;
}
</style>vue
<template>
<div class="stage">
<AsamButton type="default" native-type="button" @click="open = true"
>显示局部遮罩</AsamButton
>
<AsamOverlay
v-if="open"
v-bind="{ overlayClass: 'local-overlay', zIndex: 1 }"
@click="open = false"
>
<div class="panel" @click.stop>
<p class="example-paragraph">自定义浮层内容</p>
<AsamButton type="default" native-type="button" @click="open = false"
>关闭局部遮罩</AsamButton
>
</div>
</AsamOverlay>
</div>
</template>
<script setup>
defineOptions({ name: 'AsamOverlayBasicDemo' });
import { ref } from 'vue';
import { AsamButton, AsamOverlay } from '@asam-ui/ui';
const open = ref(false);
</script>
<style scoped>
.stage {
position: relative;
height: 180px;
isolation: isolate;
}
.stage .local-overlay {
position: absolute;
display: grid;
place-items: center;
}
.panel {
background: var(--asam-color-surface);
padding: var(--asam-space-lg);
}
</style>
<style scoped>
p:where(.example-paragraph) {
margin-block: 16px;
line-height: 1.8;
overflow-wrap: anywhere;
}
</style>使用约定
mask 控制遮罩，overlayClass 与 zIndex 配置外观和层级。click 事件接收遮罩交互；customMaskEvent 用于由宿主接管遮罩事件。default 插槽放内容。它不自动提供 Dialog 的关闭流程、焦点管理或滚动锁定；宿主自行管理显隐，本例用局部定位避免遮住整个官网。
组合职责与生命周期
底层遮罩提供 mask、overlayClass、zIndex 和 default 插槽，click 转发真实 MouseEvent。它只绘制遮罩，不建立业务 Dialog、焦点陷阱或滚动锁；这些职责必须由组合的宿主管理。
全屏遮罩与关闭操作
默认遮罩覆盖视口，使用 Teleport 挂载到 body。宿主管理显隐和 Esc 关闭；遮罩本身不接管焦点和滚动。
全屏遮罩与关闭操作
vue
<template>
<AsamButton type="default" @click="open = true">显示全屏遮罩</AsamButton>
<Teleport to="body"
><AsamOverlay v-if="open" :z-index="3500" @click="open = false"
><div class="fullscreen-content" @click.stop>
<p class="example-paragraph">全屏遮罩内容；点击遮罩、关闭按钮或按 Esc 关闭。</p>
<AsamButton type="default" @click="open = false">关闭全屏遮罩</AsamButton>
</div></AsamOverlay
></Teleport
>
</template>
<script lang="ts" setup>
import { ref, onMounted, onBeforeUnmount } from 'vue';
import { AsamButton, AsamOverlay } from '@asam-ui/ui';
const open = ref(false);
const onKey = (event: KeyboardEvent) => {
if (event.key === 'Escape') open.value = false;
};
onMounted(() => document.addEventListener('keydown', onKey));
onBeforeUnmount(() => document.removeEventListener('keydown', onKey));
</script>
<style scoped>
.fullscreen-content {
position: absolute;
top: 50%;
left: 50%;
transform: translate(-50%, -50%);
padding: var(--asam-space-lg);
background: var(--asam-color-surface);
border-radius: var(--asam-radius-control);
}
</style>
<style scoped>
p:where(.example-paragraph) {
margin-block: 16px;
line-height: 1.8;
overflow-wrap: anywhere;
}
</style>vue
<template>
<AsamButton type="default" @click="open = true">显示全屏遮罩</AsamButton>
<Teleport to="body"
><AsamOverlay v-if="open" :z-index="3500" @click="open = false"
><div class="fullscreen-content" @click.stop>
<p class="example-paragraph">全屏遮罩内容；点击遮罩、关闭按钮或按 Esc 关闭。</p>
<AsamButton type="default" @click="open = false">关闭全屏遮罩</AsamButton>
</div></AsamOverlay
></Teleport
>
</template>
<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue';
import { AsamButton, AsamOverlay } from '@asam-ui/ui';
const open = ref(false);
const onKey = (event) => {
if (event.key === 'Escape') open.value = false;
};
onMounted(() => document.addEventListener('keydown', onKey));
onBeforeUnmount(() => document.removeEventListener('keydown', onKey));
</script>
<style scoped>
.fullscreen-content {
position: absolute;
top: 50%;
left: 50%;
transform: translate(-50%, -50%);
padding: var(--asam-space-lg);
background: var(--asam-color-surface);
border-radius: var(--asam-radius-control);
}
</style>
<style scoped>
p:where(.example-paragraph) {
margin-block: 16px;
line-height: 1.8;
overflow-wrap: anywhere;
}
</style>API
属性 AsamOverlayProps
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
mask | — | boolean | undefined | true |
customMaskEvent | — | boolean | undefined | false |
overlayClass | — | string | string[] | Record<string, boolean> | undefined | undefined |
zIndex | 原生 CSS z-index 支持数字和 CSS 字符串。 | string | number | undefined | undefined |
事件 AsamOverlayEmits
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
click | — | [event: MouseEvent] | — |
插槽 AsamOverlaySlots
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
default | — | (() => unknown) | undefined | — |
关联组件
参数与事件补充说明
固定 2.14.7 公开参数；运行时默认值来自已安装组件。
参数与事件说明
mask
必填：否；声明来源：ASAM 声明。
mask 参数与事件数据
下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。
枚举：false / true
默认值与来源
true（已安装运行时；已安装组件）customMaskEvent
必填：否；声明来源：ASAM 声明。
customMaskEvent 参数与事件数据
下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。
枚举：false / true
默认值与来源
false（已安装运行时；已安装组件）overlayClass
必填：否；声明来源：ASAM 声明。
默认值与来源
undefined（已安装运行时；已安装组件）zIndex
必填：否；声明来源：ASAM 声明。
默认值与来源
undefined（已安装运行时；已安装组件）AsamOverlayProps 公开类型视图
ts
import type { AsamOverlayProps } from '@asam-ui/ui';
// AsamOverlayProps
type PublicContract = {
"mask"?: boolean | undefined;
"customMaskEvent"?: boolean | undefined;
"overlayClass"?: string | string[] | Record<string, boolean> | undefined;
"zIndex"?: string | number | undefined;
};参数与事件说明
click
必填：是；声明来源：ASAM 声明。
AsamOverlayEmits 公开类型视图
ts
import type { AsamOverlayEmits } from '@asam-ui/ui';
// AsamOverlayEmits
type PublicContract = {
"click": [event: MouseEvent];
};参数与事件说明
default
必填：否；声明来源：ASAM 声明。
default 参数与事件数据
下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。
事件参数：(): unknown
AsamOverlaySlots 公开类型视图
ts
import type { AsamOverlaySlots } from '@asam-ui/ui';
// AsamOverlaySlots
type PublicContract = {
"default"?: (() => unknown) | undefined;
};