XtfOverlay
组件说明
xtf-overlay 是全屏遮罩基础组件，适用于弹窗、加载和需要阻断背景操作的场景。它只负责遮罩与动画，前景内容应以更高 z-index 的同级节点渲染。
基础用法
1. 受控显示
使用 show 控制遮罩可见性。
vue
<template>
<view>
<xtf-button label="打开" @click="show = true" /><xtf-overlay :show="show" @click="show = false"
/></view>
</template>
<script>
export default {
data() {
return { show: false }
}
}
</script>1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
2. 点击关闭
通过 update:show 同步关闭动画完成后的状态。
vue
<template>
<view>
<xtf-button label="显示遮罩" @click="show = true" /><xtf-overlay
:show="show"
:opacity="0.6"
@click="close"
@update:show="show = $event"
/></view>
</template>
<script>
export default {
data() {
return { show: false }
},
methods: {
close() {
this.show = false
uni.showToast({ title: '开始关闭', icon: 'none' })
}
}
}
</script>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
3. 加载浮层组合
遮罩不提供插槽，加载内容需作为同级节点叠放。
vue
<template>
<view>
<xtf-button label="提交" @click="show = true" /><xtf-overlay :show="show" :z-index="100" /><view
v-if="show"
class="panel"
><xtf-loading text="提交中" /><xtf-button
size="sm"
label="完成"
@click="show = false" /></view>
</view>
</template>
<script>
export default {
data() {
return { show: false }
}
}
</script>
<style>
.panel {
position: fixed;
top: 45%;
left: 25%;
right: 25%;
z-index: 101;
padding: 30rpx;
background: #fff;
}
</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
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
全部属性
| 属性 | 类型 | 默认值 | 作用描述 | 适用范围 |
|---|---|---|---|---|
show | Boolean | false | 控制显示状态 | 必填状态控制 |
zIndex | Number | 1 | 遮罩层级 | 与前景层协调时 |
duration | Number | String | 300 | 淡入淡出时长，单位 ms | 调整动画节奏 |
opacity | Number | 0.5 | 可见时不透明度 | 轻重遮罩 |
lockScroll | Boolean | true | 标记锁定背景滚动，H5 有效 | 弹层场景 |
customClass | String | '' | 自定义类名 | 局部定制 |
customStyle | String | Object | '' | 自定义样式 | 局部定制 |
事件
| 事件名称 | 触发时机 | 回调参数 | 参数说明 |
|---|---|---|---|
click | 点击遮罩时 | () | 不会自动关闭，需由业务更新 show |
update:show | 关闭动画结束且遮罩卸载时 | (value: Boolean) | 固定为 false |
事件使用示例
vue
<template><xtf-overlay :show="show" @click="show = false" @update:show="afterClose" /></template>
<script>
export default {
data() {
return { show: true }
},
methods: {
afterClose(value) {
console.log('overlay visible:', value)
}
}
}
</script>1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
方法
1. open() — 立即渲染并播放打开动画
无参数，返回值为 void。可通过 ref 在声明式控制之外手动打开。
vue
<template>
<view>
<xtf-button label="打开" @click="$refs.overlay.open()" /><xtf-overlay ref="overlay"
/></view>
</template>
<script>
export default {}
</script>1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
2. close() — 播放关闭动画并卸载遮罩
无参数，返回值为 void；动画结束后触发 update:show(false)。
vue
<template>
<view>
<xtf-button label="关闭" @click="$refs.overlay.close()" /><xtf-overlay
ref="overlay"
:show="true"
/></view>
</template>
<script>
export default {}
</script>1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
主题说明
- 遮罩底色使用
var(--xtf-color-overlay, rgba(15, 23, 42, 0.38))。 opacity写入var(--xtf-overlay-opacity)，层级写入var(--xtf-overlay-z-index)。- 在
xtf-config-provider或全局样式覆盖--xtf-color-overlay可统一调整主题。