Overlay 遮罩层
创建一个遮罩层，用于强调特定的页面元素，并阻止用户对遮罩下层的内容进行操作。自带淡入淡出过渡，可在遮罩上方嵌入任意内容（弹块、面板、引导层等）；点击遮罩触发 click 事件，是否收起由使用方决定。
平台兼容性
| App(Android/iOS) | Web | 微信小程序 | 鸿蒙 |
|---|---|---|---|
| ✓ | ✓ | ✓ | ✓ |
基本使用
通过 show 控制显隐；遮罩被点击时发送 click 事件（示例中点击遮罩收起）：
html
<n-overlay :show="show" @click="show = false" />嵌入内容
通过默认插槽在遮罩上方嵌入任意内容；不想让内容的点击冒泡到遮罩（触发 click），给该元素加 @tap.stop：
html
<n-overlay :show="show" @click="show = false">
<view class="card" @tap.stop>
<text>遮罩上的浮层内容</text>
</view>
</n-overlay>遮罩样式
duration 控制淡入淡出时长（ms，0 为即显即隐）；opacity 控制遮罩不透明度（只作用于底色，插槽内容不受影响）；z-index 控制层级；absolute 用于容器内局部遮罩（相对最近的定位祖先铺满）：
html
<n-overlay :show="show" :duration="400" :z-index="1200" :opacity="0.3" absolute @click="show = false" />换遮罩底色
遮罩默认黑色系（rgba(0,0,0,opacity)，行内动态值）。需要白色等其它底色时用 custom-style 覆盖（底色是行内值，custom-class 的类压不过它）：
html
<n-overlay :show="show" custom-style="background-color:rgba(255,255,255,0.92)" @click="show = false" />API
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| show | 是否显示遮罩；false 时整根卸载，不占位、不拦截任何交互 | boolean | false |
| z-index | 遮罩层级；与本库弹层族同级（弹层类 1000、加载页与断网页 1100） | number | 1000 |
| duration | 淡入淡出时长（ms）；0 为即显即隐（无过渡、无卸载缓冲） | number | 300 |
| opacity | 遮罩不透明度（rgba 第四参），只作用于遮罩底色，插槽内容不受影响；换遮罩色用 custom-style 覆盖 background-color | number | 0.5 |
| absolute | 是否相对最近的定位祖先局部遮罩（覆盖指定容器）；false 时 fixed 全屏 | boolean | false |
| custom-class | 根节点自定义类；类须定义在组件样式表内（页面样式打不进组件），示例见组件样式表的圆角遮罩 n-overlay--rounded（absolute 局部遮罩下明显）；换遮罩底色不走本通道（底色是行内动态值，类覆盖不了），用 custom-style |
string | — |
| custom-style | 根节点行内样式，如 background-color:rgba(255,255,255,0.9)；拼接在内部样式之后，可覆盖层级与底色 |
string | — |
Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击遮罩时触发（打开态有效；插槽内容未 @tap.stop 阻断时冒泡同语义），是否收起由使用方在回调中决定 |
— |
Slots
| 名称 | 说明 |
|---|---|
| default | 遮罩上方嵌入的内容（纵排居中排布） |
实现说明
- 显隐机制：
show → enter（挂载，透明）→ 约 50ms 后切 open（播放 opacity 过渡）→ false → leave（过渡回透明）→ 时长 + 40ms 缓冲后卸载；duration=0即显即隐（无过渡、无缓冲）。挂载后等首帧渲染再上目标透明度，过渡才会真实播放；与弹层族（n-popup）同构。 - 根即遮罩：根节点承载视觉与点击，无包装层；
absolute ↔ fixed属结构位，切换时整根销毁重建（运行中的遮罩切换后以当前状态直接装配，无闪动）。 - 透明度只动底色：
opacity参与底色rgba(0,0,0,opacity)计算，插槽内容完全不透明；这与直接降低整个遮罩节点透明度的做法不同（后者内容会跟着变淡）。 - 点击语义：
click仅在打开态触发（过渡中点击防误触）；插槽内容未阻断时点击冒泡到根、与遮罩点击同语义——需要独立交互的内容加@tap.stop。 - 滚动穿透：根挂
@touchmove.stop.prevent，遮罩显示期间底层页面不可滚动。 - 层级约定：默认 1000 与弹层族同级；更高层级直接传
:z-index="1500"之类。 - 参考源差异取舍：参考形态的
background整色属性由opacity+custom-style组合承担（透明度可细调、换色有统一通道）；closable开关不收录（点击总是发click，使用方不监听即不动作，自行守卫更灵活）；nvue 专属的full不收录。