在开发过程中,常需在当前组件上叠加显示遮罩文本或自定义内容(如提示标签、水印、操作浮层等)。虽然Stack组件可通过层级嵌套实现此类效果,但过度使用嵌套结构会导致组件树层级过深,增加渲染开销,影响页面性能。
相比之下,使用浮层(OverlayManager)可在不增加组件层级的前提下,将浮层内容直接挂载至目标组件之上,有效减少一层Stack节点的嵌套。该方案在实现视觉效果的同时,显著优化了渲染性能与结构简洁性。
浮层(OverlayManager)用于在页面(Page)之上展示自定义的UI内容,位于Dialog、Popup、Menu、BindSheet、BindContentCover和Toast等组件之下,展示范围为当前窗口的安全区内,适用于常驻悬浮等场景。
可以通过使用UIContext中的getOverlayManager方法获取当前UI上下文关联的OverlayManager对象,再通过该对象调用对应方法。

使用OverlayManager传入ComponentContent添加浮层实现在页面顶部固定公告,示例代码如下:
export class Params {
text: string = '';
offset: Position;
overlayContent: ComponentContent<Params>[];
overlayNode: OverlayManager;
constructor(text: string, overlayContent: ComponentContent<Params>[],
overlayNode: OverlayManager, offset: Position) {
this.text = text;
this.offset = offset;
this.overlayContent = overlayContent;
this.overlayNode = overlayNode;
}
} @Builder
export function OverlayNode(params: Params) {
Row({ space: 5 }) {
Text(params.text)
.fontWeight(400)
.lineHeight(16)
.fontSize(14)
.maxLines(1)
.textOverflow({ overflow: TextOverflow.Ellipsis })
.layoutWeight(1);
Text('查看详情')
.fontSize(12)
.fontColor('#0A59F7');
Text('>')
.fontSize(12)
.fontColor('#0A59F7');
}
.alignItems(VerticalAlign.Center)
.justifyContent(FlexAlign.SpaceBetween)
.onClick(() => {
let componentContent = params.overlayContent[0];
params.overlayNode.hideComponentContent(componentContent);
})
.position({
x: params.offset.x,
y: params.offset.y
})
.expandSafeArea([SafeAreaType.KEYBOARD])
.width('100%')
.padding({
top: 16,
bottom: 16,
left: 16,
right: 16
})
.backgroundColor('#f1f3f5')
.hitTestBehavior(HitTestMode.Transparent); // 配置浮层不阻塞交互
} aboutToAppear(): void {
let componentContent = new ComponentContent(
this.uiContext, wrapBuilder<[Params]>(OverlayNode), this.params
);
this.overlayNode.addComponentContent(componentContent, 0);
this.overlayContent.push(componentContent);
} aboutToDisappear(): void {
let componentContent = this.overlayContent.pop();
this.overlayNode.removeComponentContent(componentContent);
} 完整示例参考如下:
import { ComponentContent, OverlayManager } from '@kit.ArkUI';
export class Params {
text: string = '';
offset: Position;
overlayContent: ComponentContent<Params>[];
overlayNode: OverlayManager;
constructor(text: string, overlayContent: ComponentContent<Params>[],
overlayNode: OverlayManager, offset: Position) {
this.text = text;
this.offset = offset;
this.overlayContent = overlayContent;
this.overlayNode = overlayNode;
}
}
@Builder
export function OverlayNode(params: Params) {
Row({ space: 5 }) {
Text(params.text)
.fontWeight(400)
.lineHeight(16)
.fontSize(14)
.maxLines(1)
.textOverflow({ overflow: TextOverflow.Ellipsis })
.layoutWeight(1);
Text('查看详情')
.fontSize(12)
.fontColor('#0A59F7');
Text('>')
.fontSize(12)
.fontColor('#0A59F7');
}
.alignItems(VerticalAlign.Center)
.justifyContent(FlexAlign.SpaceBetween)
.onClick(() => {
let componentContent = params.overlayContent[0];
params.overlayNode.hideComponentContent(componentContent);
})
.position({
x: params.offset.x,
y: params.offset.y
})
.expandSafeArea([SafeAreaType.KEYBOARD])
.width('100%')
.padding({
top: 16,
bottom: 16,
left: 16,
right: 16
})
.backgroundColor('#f1f3f5')
.hitTestBehavior(HitTestMode.Transparent); // 配置浮层不阻塞交互
}
@Entry
@Component
struct MainPage {
text: string = '下周一下午15:00开例会,主要过一下本周的项目进度和接下来的项目安排。';
componentOffset: Position = { x: 0, y: 1 };
private uiContext: UIContext = this.getUIContext();
private overlayNode: OverlayManager = this.uiContext.getOverlayManager();
private overlayContent: ComponentContent<Params>[] = [];
@Provide params: Params =
new Params(this.text, this.overlayContent, this.overlayNode, this.componentOffset);
aboutToAppear(): void {
let componentContent = new ComponentContent(
this.uiContext, wrapBuilder<[Params]>(OverlayNode), this.params
);
this.overlayNode.addComponentContent(componentContent, 0);
this.overlayContent.push(componentContent);
}
aboutToDisappear(): void {
let componentContent = this.overlayContent.pop();
this.overlayNode.removeComponentContent(componentContent);
}
build() {
Column() {
}
.backgroundColor('#ffffff');
}
} 想要实现固定公告、悬浮层可以使用overlay属性。使用OverlayManager实现文本浮层比Stack组件嵌套方式少了一层Stack节点。使用CustomBuilder设置浮层时,浮层中的内容会在页面刷新时销毁并重新创建,存在一定的性能损耗,页面频繁刷新的场景推荐使用ComponentContent方式设置浮层。