FxOverlay 遮罩层
全屏固定定位的遮罩底层组件，提供遮罩背景 + 点击关闭能力。主要被 FxDialog / FxDrawer / FxMsgBox 内部消费，也可独立使用。
通常不需要直接使用 FxOverlay。需要模态弹层时，优先使用
FxDialog（居中弹窗）、FxDrawer（侧边抽屉）或FxMsgBox（消息框），它们内部已集成遮罩。
基础用法
mask 控制是否显示半透明遮罩背景；z-index 控制层叠顺序。点击遮罩触发 click 事件。
vue
<template>
<div>
<FxBtn @click="visible = true">显示遮罩</FxBtn>
<FxOverlay v-if="visible" :z-index="2000" @click="visible = false">
<div class="demo-box">
<p>点击遮罩关闭</p>
<FxBtn size="small" @click.stop="visible = false">关闭</FxBtn>
</div>
</FxOverlay>
</div>
</template>
<script setup lang="ts">
import { ref } from "vue"
import { FxOverlay, FxBtn } from "@fx/components"
const visible = ref(false)
</script>
<style scoped>
.demo-box {
position: fixed;
top: 50%;
left: 50%;
transform: translate(-50%, -50%);
background: var(--fx-bg-color);
padding: 24px;
border-radius: var(--fx-border-radius-base);
box-shadow: var(--fx-box-shadow-card);
display: flex;
flex-direction: column;
align-items: center;
gap: 12px;
pointer-events: auto;
}
</style>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
vue
<FxOverlay :z-index="1000" @click="handleClick">
<div style="position:fixed;top:50%;left:50%;transform:translate(-50%,-50%)">
遮罩上的内容
</div>
</FxOverlay>1
2
3
4
5
2
3
4
5
自定义遮罩类名
通过 overlayClass 为遮罩添加自定义 CSS 类。
vue
<template>
<div>
<FxBtn @click="visible = true">自定义遮罩样式</FxBtn>
<FxOverlay
v-if="visible"
:z-index="2000"
overlay-class="custom-overlay-demo"
@click="visible = false"
>
<div class="demo-box">
<p>遮罩使用了自定义样式</p>
<FxBtn size="small" @click.stop="visible = false">关闭</FxBtn>
</div>
</FxOverlay>
</div>
</template>
<script setup lang="ts">
import { ref } from "vue"
import { FxOverlay, FxBtn } from "@fx/components"
const visible = ref(false)
</script>
<style>
.custom-overlay-demo {
background-color: rgba(0, 0, 0, 0.7) !important;
}
</style>
<style scoped>
.demo-box {
position: fixed;
top: 50%;
left: 50%;
transform: translate(-50%, -50%);
background: var(--fx-bg-color);
padding: 24px;
border-radius: var(--fx-border-radius-base);
box-shadow: var(--fx-box-shadow-card);
display: flex;
flex-direction: column;
align-items: center;
gap: 12px;
pointer-events: auto;
}
</style>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
自定义遮罩事件
customMaskEvent 为 true 时禁用内置点击关闭逻辑，由消费方自行监听处理。
vue
<template>
<div>
<FxBtn @click="visible = true">自定义遮罩点击处理</FxBtn>
<FxOverlay
v-if="visible"
:z-index="2000"
custom-mask-event
@click="onOverlayClick"
>
<div class="demo-box">
<p>遮罩点击由消费方自行处理（customMaskEvent）</p>
<FxBtn size="small" @click.stop="visible = false">关闭</FxBtn>
</div>
</FxOverlay>
</div>
</template>
<script setup lang="ts">
import { ref } from "vue"
import { FxOverlay, FxBtn } from "@fx/components"
const visible = ref(false)
const onOverlayClick = (evt: MouseEvent) => {
// 自定义处理逻辑（如判断点击目标、添加确认等）
console.log("overlay clicked", evt)
visible.value = false
}
</script>
<style scoped>
.demo-box {
position: fixed;
top: 50%;
left: 50%;
transform: translate(-50%, -50%);
background: var(--fx-bg-color);
padding: 24px;
border-radius: var(--fx-border-radius-base);
box-shadow: var(--fx-box-shadow-card);
display: flex;
flex-direction: column;
align-items: center;
gap: 12px;
pointer-events: auto;
}
</style>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
API
Attributes
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| mask | 是否显示遮罩（半透明背景）。false 时渲染透明占位层 | boolean | true |
| custom-mask-event | 是否由消费方自行处理遮罩点击事件 | boolean | false |
| overlay-class | 遮罩自定义类名 | string | string[] | Record<string, boolean> | — |
| z-index | 层叠顺序 | string | number | — |
Events
| 名称 | 说明 | 类型 |
|---|---|---|
| click | 点击遮罩时触发（custom-mask-event 为 true 时不触发） | (evt: MouseEvent) => void |
Slots
| 名称 | 说明 |
|---|---|
| default | 遮罩层上渲染的内容 |
实现说明
两种渲染模式
| 模式 | mask | 行为 |
|---|---|---|
| 遮罩模式 | true（默认） | 渲染带 .fx-overlay 类名 + 半透明背景的遮罩层，使用 useSameTarget 处理点击（确保 mousedown/mouseup 在同一元素才触发 click，防止拖拽误关） |
| 占位模式 | false | 渲染透明、无背景的全屏 fixed 层，仅提供 z-index 层叠上下文 |
点击处理
内置 useSameTarget 逻辑：只有 mousedown 和 mouseup 在同一个元素上时，才触发 click 事件。当 customMaskEvent 为 true 时，该逻辑被绕过，消费方需自行处理 click / mousedown / mouseup。
样式 token
遮罩背景色使用 --color-mask（CSS 变量，定义于 @fx/styles 的 _popup.scss），亮色模式为 rgba(0,0,0,0.5)，暗色模式为 rgba(0,0,0,0.85)。
局部引入
ts
import { FxOverlay } from "@fx/components"1