做过音乐播放器的同学一定遇到过——底部迷你播放器要跨页面常驻悬浮弹窗又得盖在它上面。API 12终于给出了官方方案OverlayManager浮层管理器——这篇把浮层OverlayManager与悬浮控件的完整方案讲清楚。OverlayManager的层级与获取OverlayManager在Page之上、Dialog/Popup/Menu之下适用常驻悬浮UI。层级Toast Dialog/Popup OverlayManager Page Navigation。通过UIContext获取实例import{ComponentContent,OverlayManager}fromkit.ArkUIEntryComponentV2struct LayerDemoPage{privateoverlayMgr:OverlayManagerthis.getUIContext().getOverlayManager()build(){Column({space:12}){Text(Page层).fontSize(20)Text(OverlayManager在Page之上).fontSize(14).fontColor(#999999)}.width(100%).height(100%).backgroundColor(#f5f5f5)}}在struct成员变量初始化时通过this.getUIContext().getOverlayManager()获取确保build之前拿到实例。安全区域和键盘避让与Page一致。关键区别OverlayManager不是Dialog替代品。模态交互用Dialog常驻悬浮用OverlayManager。Dialog层级更高。ComponentContent与wrapBuilder往OverlayManager添加内容必须先把Builder包装成ComponentContent——ArkUI的组件内容封装机制。import{ComponentContent,OverlayManager}fromkit.ArkUIclassTipParams{message:stringconstructor(message:string){this.messagemessage}}BuilderfunctiontipBuilder(params:TipParams){Column(){Text(params.message).fontSize(14).fontColor(Color.White)}.padding(12).backgroundColor(#333333).borderRadius(8)}EntryComponentV2struct ComponentContentPage{privateoverlayMgr:OverlayManagerthis.getUIContext().getOverlayManager()build(){Column({space:12}){Button(显示提示).onClick((){lettipContent:ComponentContentTipParamsnewComponentContent(this.getUIContext(),wrapBuilder[TipParams](tipBuilder),newTipParams(操作成功))this.overlayMgr.addComponentContent(tipContent)})}}}步骤1.定义参数class2.写Builder3.wrapBuilder包装4.new ComponentContent传入UIContext、wrapped builder和参数。注意wrapBuilder泛型必须与Builder参数类型匹配。wrapBuilder[TipParams]对应tipBuilder的params类型写错会编译报错。add与remove浮层addComponentContent添加节点removeComponentContent删除节点——最基础的操作对。import{ComponentContent,OverlayManager}fromkit.ArkUIclassFabParams{icon:stringonFabClick:()void(){}constructor(icon:string,onFabClick:()void){this.iconiconthis.onFabClickonFabClick}}BuilderfunctionfabBuilder(params:FabParams){Column(){Text(params.icon).fontSize(28).fontColor(Color.White)}.width(56).height(56).borderRadius(28).backgroundColor(#007DFF).justifyContent(FlexAlign.Center).onClick((){params.onFabClick()}).position({x:80%,y:85%})}EntryComponentV2struct FabPage{privateoverlayMgr:OverlayManagerthis.getUIContext().getOverlayManager()LocalfabContent:ComponentContentFabParams|undefinedundefinedbuild(){Column({space:12}){Button(显示FAB).onClick((){letfab:ComponentContentFabParamsnewComponentContent(this.getUIContext(),wrapBuilder[FabParams](fabBuilder),newFabParams(,(){console.info(FAB clicked)}))this.fabContentfabthis.overlayMgr.addComponentContent(fab)})Button(移除FAB).onClick((){if(this.fabContent!undefined){this.overlayMgr.removeComponentContent(this.fabContent)this.fabContentundefined}})}}}add默认居中位置用position控制。remove必须传add时的同一个实例。注意同一ComponentContent add多次只保留最后一次。需要多个浮层就new多个实例。show/hide浮层可见性临时隐藏用showComponentContent/hideComponentContent比remove再add性能好。import{ComponentContent,OverlayManager}fromkit.ArkUIObservedV2classMiniPlayerState{TracesongName:string未播放TraceisPlaying:booleanfalseplay(song:string):void{this.songNamesongthis.isPlayingtrue}pause():void{this.isPlayingfalse}}BuilderfunctionminiPlayerBuilder(params:MiniPlayerState){Row({space:8}){Text(params.isPlaying?▶:⏸).fontSize(20)Text(params.songName).fontSize(14).maxLines(1).textOverflow({overflow:TextOverflow.Ellipsis}).layoutWeight(1)}.width(90%).height(56).padding({left:16,right:16}).backgroundColor(#ffffff).borderRadius(12).shadow({radius:8,color:#1a000000,offsetY:-2}).position({x:5%,y:90%})}EntryComponentV2struct MiniPlayerPage{privateoverlayMgr:OverlayManagerthis.getUIContext().getOverlayManager()LocalplayerState:MiniPlayerStatenewMiniPlayerState()LocalplayerContent:ComponentContentMiniPlayerState|undefinedundefinedaboutToAppear():void{this.playerContentnewComponentContent(this.getUIContext(),wrapBuilder[MiniPlayerState](miniPlayerBuilder),this.playerState)this.overlayMgr.addComponentContent(this.playerContent)}build(){Column({space:12}){Text(音乐播放页)Button(播放).onClick((){this.playerState.play(夜曲)})Button(暂停).onClick((){this.playerState.pause()})Button(隐藏).onClick((){if(this.playerContent!undefined){this.overlayMgr.hideComponentContent(this.playerContent)}})Button(显示).onClick((){if(this.playerContent!undefined){this.overlayMgr.showComponentContent(this.playerContent)}})}}}hide视觉隐藏但节点还在show快速恢复。关键区别remove彻底移除节点再显示要重新addhide只隐藏show快速恢复——适合频繁切换显隐。Overlay Index层级控制多浮层堆叠时index参数控制层级——index越大越靠上同index后add的更高。import{ComponentContent,OverlayManager}fromkit.ArkUIclassLayerParams{text:stringcolor:string#007DFFconstructor(text:string,color:string){this.texttextthis.colorcolor}}BuilderfunctionlayerBuilder(params:LayerParams){Column(){Text(params.text).fontSize(16).fontColor(Color.White)}.width(200).height(80).backgroundColor(params.color).borderRadius(8).justifyContent(FlexAlign.Center)}EntryComponentV2struct IndexPage{privateoverlayMgr:OverlayManagerthis.getUIContext().getOverlayManager()build(){Column({space:12}){Button(底层(index0)).onClick((){letc:ComponentContentLayerParamsnewComponentContent(this.getUIContext(),wrapBuilder[LayerParams](layerBuilder),newLayerParams(底层,#4CAF50))this.overlayMgr.addComponentContent(c,0)})Button(顶层(index10)).onClick((){letc:ComponentContentLayerParamsnewComponentContent(this.getUIContext(),wrapBuilder[LayerParams](layerBuilder),newLayerParams(顶层,#F44336))this.overlayMgr.addComponentContent(c,10)})}}}index 0或undefined时添加到最高层index 0时值越大层级越高同index后添加的层级更高。注意同一ComponentContent add多次只保留最后一次。需要多个同内容浮层就创建多个实例。事件穿透与HitTestMode悬浮浮层需要点击穿透到下层Page时用HitTestMode.Transparent。import{ComponentContent,OverlayManager}fromkit.ArkUIclassOverlayTipParams{tipText:stringconstructor(tipText:string){this.tipTexttipText}}BuilderfunctionoverlayTipBuilder(params:OverlayTipParams){Column(){Column(){Text(params.tipText).fontSize(14).fontColor(Color.White)}.padding({left:12,right:12,top:8,bottom:8}).backgroundColor(#cc000000).borderRadius(4)}.width(100%).height(100%).hitTestBehavior(HitTestMode.Transparent).justifyContent(FlexAlign.Top).padding({top:60})}EntryComponentV2struct HitTestPage{privateoverlayMgr:OverlayManagerthis.getUIContext().getOverlayManager()LocalclickCount:number0build(){Column({space:12}){Text(点击次数:${this.clickCount}).fontSize(20)Button(点击计数).onClick((){this.clickCount1})Button(显示提示).onClick((){lettip:ComponentContentOverlayTipParamsnewComponentContent(this.getUIContext(),wrapBuilder[OverlayTipParams](overlayTipBuilder),newOverlayTipParams(提示文字点击穿透))this.overlayMgr.addComponentContent(tip)})}}}Transparent让浮层不拦截触摸事件点击穿透到下层——引导提示、悬浮标签场景常用。关键区别Transparent完全穿透None不响应也不穿透事件丢弃Default正常拦截。完整实战可拖动悬浮控件组合所有API实现可拖动FAB——拖动改位置点击执行操作生命周期自动管理。import{ComponentContent,OverlayManager}fromkit.ArkUIObservedV2classDragFabState{TraceposX:number300TraceposY:number600onAction:()void(){}constructor(onAction:()void){this.onActiononAction}}BuilderfunctiondragFabBuilder(params:DragFabState){Column(){Text().fontSize(28).fontColor(Color.White)}.width(56).height(56).borderRadius(28).backgroundColor(#007DFF).justifyContent(FlexAlign.Center).position({x:params.posX,y:params.posY}).gesture(PanGesture().onActionUpdate((event:GestureEvent){params.posXevent.offsetX params.posYevent.offsetY})).onClick((){params.onAction()})}EntryComponentV2struct DragFabPage{privateoverlayMgr:OverlayManagerthis.getUIContext().getOverlayManager()LocalfabState:DragFabStatenewDragFabState((){console.info(FAB clicked)})LocalfabContent:ComponentContentDragFabState|undefinedundefinedaboutToAppear():void{this.fabContentnewComponentContent(this.getUIContext(),wrapBuilder[DragFabState](dragFabBuilder),this.fabState)this.overlayMgr.addComponentContent(this.fabContent)}aboutToDisappear():void{if(this.fabContent!undefined){this.overlayMgr.removeComponentContent(this.fabContent)}}build(){Column({space:12}){Text(拖动浮层实战).fontSize(24).fontWeight(FontWeight.Bold)Text(可拖动的FAB浮在页面上).fontColor(#999999)}.width(100%).height(100%)}}aboutToAppear创建添加aboutToDisappear移除。PanGestureTrace的posX/posY实现拖动实时更新。注意OverlayManager相关属性推荐用AppStorage全局存储浮层position是窗口绝对坐标。踩坑清单问题原因解决getOverlayManager()返回undefined组件未创建就调用成员变量初始化时获取add后看不到默认居中Builder内设positionremove无效传了新实例保存add时的实例同一内容add多次只显示一次同实例只保留最后new多个实例浮层挡住页面点击默认拦截事件HitTestMode.Transparent切页后浮层属性异常属性随页面销毁AppStorage存属性aboutToAppear中add报错UIContext未就绪成员变量初始化时操作Dialog盖不住浮层Dialog层级更高正常层级关系wrapBuilder泛型报错泛型与Builder参数不匹配严格对应参数类型 
长河君 · 2026/8/4 0:33:09 · 阅读 1.2k HarmonyOS 6.0 浮层OverlayManager与悬浮控件——Page之上的常驻UI层管理方案
做过音乐播放器的同学一定遇到过——底部迷你播放器要跨页面常驻悬浮弹窗又得盖在它上面。API 12终于给出了官方方案OverlayManager浮层管理器——这篇把浮层OverlayManager与悬浮控件的完整方案讲清楚。OverlayManager的层级与获取OverlayManager在Page之上、Dialog/Popup/Menu之下适用常驻悬浮UI。层级Toast Dialog/Popup OverlayManager Page Navigation。通过UIContext获取实例import{ComponentContent,OverlayManager}fromkit.ArkUIEntryComponentV2struct LayerDemoPage{privateoverlayMgr:OverlayManagerthis.getUIContext().getOverlayManager()build(){Column({space:12}){Text(Page层).fontSize(20)Text(OverlayManager在Page之上).fontSize(14).fontColor(#999999)}.width(100%).height(100%).backgroundColor(#f5f5f5)}}在struct成员变量初始化时通过this.getUIContext().getOverlayManager()获取确保build之前拿到实例。安全区域和键盘避让与Page一致。关键区别OverlayManager不是Dialog替代品。模态交互用Dialog常驻悬浮用OverlayManager。Dialog层级更高。ComponentContent与wrapBuilder往OverlayManager添加内容必须先把Builder包装成ComponentContent——ArkUI的组件内容封装机制。import{ComponentContent,OverlayManager}fromkit.ArkUIclassTipParams{message:stringconstructor(message:string){this.messagemessage}}BuilderfunctiontipBuilder(params:TipParams){Column(){Text(params.message).fontSize(14).fontColor(Color.White)}.padding(12).backgroundColor(#333333).borderRadius(8)}EntryComponentV2struct ComponentContentPage{privateoverlayMgr:OverlayManagerthis.getUIContext().getOverlayManager()build(){Column({space:12}){Button(显示提示).onClick((){lettipContent:ComponentContentTipParamsnewComponentContent(this.getUIContext(),wrapBuilder[TipParams](tipBuilder),newTipParams(操作成功))this.overlayMgr.addComponentContent(tipContent)})}}}步骤1.定义参数class2.写Builder3.wrapBuilder包装4.new ComponentContent传入UIContext、wrapped builder和参数。注意wrapBuilder泛型必须与Builder参数类型匹配。wrapBuilder[TipParams]对应tipBuilder的params类型写错会编译报错。add与remove浮层addComponentContent添加节点removeComponentContent删除节点——最基础的操作对。import{ComponentContent,OverlayManager}fromkit.ArkUIclassFabParams{icon:stringonFabClick:()void(){}constructor(icon:string,onFabClick:()void){this.iconiconthis.onFabClickonFabClick}}BuilderfunctionfabBuilder(params:FabParams){Column(){Text(params.icon).fontSize(28).fontColor(Color.White)}.width(56).height(56).borderRadius(28).backgroundColor(#007DFF).justifyContent(FlexAlign.Center).onClick((){params.onFabClick()}).position({x:80%,y:85%})}EntryComponentV2struct FabPage{privateoverlayMgr:OverlayManagerthis.getUIContext().getOverlayManager()LocalfabContent:ComponentContentFabParams|undefinedundefinedbuild(){Column({space:12}){Button(显示FAB).onClick((){letfab:ComponentContentFabParamsnewComponentContent(this.getUIContext(),wrapBuilder[FabParams](fabBuilder),newFabParams(,(){console.info(FAB clicked)}))this.fabContentfabthis.overlayMgr.addComponentContent(fab)})Button(移除FAB).onClick((){if(this.fabContent!undefined){this.overlayMgr.removeComponentContent(this.fabContent)this.fabContentundefined}})}}}add默认居中位置用position控制。remove必须传add时的同一个实例。注意同一ComponentContent add多次只保留最后一次。需要多个浮层就new多个实例。show/hide浮层可见性临时隐藏用showComponentContent/hideComponentContent比remove再add性能好。import{ComponentContent,OverlayManager}fromkit.ArkUIObservedV2classMiniPlayerState{TracesongName:string未播放TraceisPlaying:booleanfalseplay(song:string):void{this.songNamesongthis.isPlayingtrue}pause():void{this.isPlayingfalse}}BuilderfunctionminiPlayerBuilder(params:MiniPlayerState){Row({space:8}){Text(params.isPlaying?▶:⏸).fontSize(20)Text(params.songName).fontSize(14).maxLines(1).textOverflow({overflow:TextOverflow.Ellipsis}).layoutWeight(1)}.width(90%).height(56).padding({left:16,right:16}).backgroundColor(#ffffff).borderRadius(12).shadow({radius:8,color:#1a000000,offsetY:-2}).position({x:5%,y:90%})}EntryComponentV2struct MiniPlayerPage{privateoverlayMgr:OverlayManagerthis.getUIContext().getOverlayManager()LocalplayerState:MiniPlayerStatenewMiniPlayerState()LocalplayerContent:ComponentContentMiniPlayerState|undefinedundefinedaboutToAppear():void{this.playerContentnewComponentContent(this.getUIContext(),wrapBuilder[MiniPlayerState](miniPlayerBuilder),this.playerState)this.overlayMgr.addComponentContent(this.playerContent)}build(){Column({space:12}){Text(音乐播放页)Button(播放).onClick((){this.playerState.play(夜曲)})Button(暂停).onClick((){this.playerState.pause()})Button(隐藏).onClick((){if(this.playerContent!undefined){this.overlayMgr.hideComponentContent(this.playerContent)}})Button(显示).onClick((){if(this.playerContent!undefined){this.overlayMgr.showComponentContent(this.playerContent)}})}}}hide视觉隐藏但节点还在show快速恢复。关键区别remove彻底移除节点再显示要重新addhide只隐藏show快速恢复——适合频繁切换显隐。Overlay Index层级控制多浮层堆叠时index参数控制层级——index越大越靠上同index后add的更高。import{ComponentContent,OverlayManager}fromkit.ArkUIclassLayerParams{text:stringcolor:string#007DFFconstructor(text:string,color:string){this.texttextthis.colorcolor}}BuilderfunctionlayerBuilder(params:LayerParams){Column(){Text(params.text).fontSize(16).fontColor(Color.White)}.width(200).height(80).backgroundColor(params.color).borderRadius(8).justifyContent(FlexAlign.Center)}EntryComponentV2struct IndexPage{privateoverlayMgr:OverlayManagerthis.getUIContext().getOverlayManager()build(){Column({space:12}){Button(底层(index0)).onClick((){letc:ComponentContentLayerParamsnewComponentContent(this.getUIContext(),wrapBuilder[LayerParams](layerBuilder),newLayerParams(底层,#4CAF50))this.overlayMgr.addComponentContent(c,0)})Button(顶层(index10)).onClick((){letc:ComponentContentLayerParamsnewComponentContent(this.getUIContext(),wrapBuilder[LayerParams](layerBuilder),newLayerParams(顶层,#F44336))this.overlayMgr.addComponentContent(c,10)})}}}index 0或undefined时添加到最高层index 0时值越大层级越高同index后添加的层级更高。注意同一ComponentContent add多次只保留最后一次。需要多个同内容浮层就创建多个实例。事件穿透与HitTestMode悬浮浮层需要点击穿透到下层Page时用HitTestMode.Transparent。import{ComponentContent,OverlayManager}fromkit.ArkUIclassOverlayTipParams{tipText:stringconstructor(tipText:string){this.tipTexttipText}}BuilderfunctionoverlayTipBuilder(params:OverlayTipParams){Column(){Column(){Text(params.tipText).fontSize(14).fontColor(Color.White)}.padding({left:12,right:12,top:8,bottom:8}).backgroundColor(#cc000000).borderRadius(4)}.width(100%).height(100%).hitTestBehavior(HitTestMode.Transparent).justifyContent(FlexAlign.Top).padding({top:60})}EntryComponentV2struct HitTestPage{privateoverlayMgr:OverlayManagerthis.getUIContext().getOverlayManager()LocalclickCount:number0build(){Column({space:12}){Text(点击次数:${this.clickCount}).fontSize(20)Button(点击计数).onClick((){this.clickCount1})Button(显示提示).onClick((){lettip:ComponentContentOverlayTipParamsnewComponentContent(this.getUIContext(),wrapBuilder[OverlayTipParams](overlayTipBuilder),newOverlayTipParams(提示文字点击穿透))this.overlayMgr.addComponentContent(tip)})}}}Transparent让浮层不拦截触摸事件点击穿透到下层——引导提示、悬浮标签场景常用。关键区别Transparent完全穿透None不响应也不穿透事件丢弃Default正常拦截。完整实战可拖动悬浮控件组合所有API实现可拖动FAB——拖动改位置点击执行操作生命周期自动管理。import{ComponentContent,OverlayManager}fromkit.ArkUIObservedV2classDragFabState{TraceposX:number300TraceposY:number600onAction:()void(){}constructor(onAction:()void){this.onActiononAction}}BuilderfunctiondragFabBuilder(params:DragFabState){Column(){Text().fontSize(28).fontColor(Color.White)}.width(56).height(56).borderRadius(28).backgroundColor(#007DFF).justifyContent(FlexAlign.Center).position({x:params.posX,y:params.posY}).gesture(PanGesture().onActionUpdate((event:GestureEvent){params.posXevent.offsetX params.posYevent.offsetY})).onClick((){params.onAction()})}EntryComponentV2struct DragFabPage{privateoverlayMgr:OverlayManagerthis.getUIContext().getOverlayManager()LocalfabState:DragFabStatenewDragFabState((){console.info(FAB clicked)})LocalfabContent:ComponentContentDragFabState|undefinedundefinedaboutToAppear():void{this.fabContentnewComponentContent(this.getUIContext(),wrapBuilder[DragFabState](dragFabBuilder),this.fabState)this.overlayMgr.addComponentContent(this.fabContent)}aboutToDisappear():void{if(this.fabContent!undefined){this.overlayMgr.removeComponentContent(this.fabContent)}}build(){Column({space:12}){Text(拖动浮层实战).fontSize(24).fontWeight(FontWeight.Bold)Text(可拖动的FAB浮在页面上).fontColor(#999999)}.width(100%).height(100%)}}aboutToAppear创建添加aboutToDisappear移除。PanGestureTrace的posX/posY实现拖动实时更新。注意OverlayManager相关属性推荐用AppStorage全局存储浮层position是窗口绝对坐标。踩坑清单问题原因解决getOverlayManager()返回undefined组件未创建就调用成员变量初始化时获取add后看不到默认居中Builder内设positionremove无效传了新实例保存add时的实例同一内容add多次只显示一次同实例只保留最后new多个实例浮层挡住页面点击默认拦截事件HitTestMode.Transparent切页后浮层属性异常属性随页面销毁AppStorage存属性aboutToAppear中add报错UIContext未就绪成员变量初始化时操作Dialog盖不住浮层Dialog层级更高正常层级关系wrapBuilder泛型报错泛型与Builder参数不匹配严格对应参数类型