HarmonyOS FoldStatus 与 FoldDisplayMode 枚举深度解析:折叠屏开发不再难 文章目录一、前言二、工具函数方法一览三、状态查询方法详解3.1 isFoldable() — 检测是否可折叠设备3.2 getFoldStatus() — 获取折叠状态3.3 getFoldDisplayMode() — 获取折叠显示模式四、监听方法详解4.1 折叠状态变化监听4.2 折叠角度变化监听五、完整演示代码5.1 状态查询5.2 监听器注册与注销5.3 UI 渲染六、生命周期中正确管理监听器七、实际应用场景场景 1折叠屏布局自适应场景 2根据角度触发特效八、小结一、前言近期发现一款很有意思的HarmonyOS 三方库, 地址 pura/harmony-utils(V1.4.0) , 作者是桃花镇童长老, 我这里也是直接通过该作者公布的源码进行案例编写进行,写了到目前写了一部分demo ,感觉确实很有帮助,这里呢也是开始写一个系列的演示demo 供大家参考。如有帮助可以在OpenHarmony中进行下载安装进行使用哦案例demo导航展示↓↓↓↓↓↓接下来言归正传 ↓↓↓↓HarmonyOS 生态中有华为 Mate X 系列等折叠屏设备。折叠屏设备有多种独特的显示状态完全展开、完全折叠、半折叠悬停态还有多种显示模式全屏、主屏、子屏、双屏协同……DisplayUtil提供了检测折叠状态的方法以及监听折叠状态/角度变化的事件接口。本文详细讲解这些能力并结合DisplayUtilDemoPage.ets中的完整演示代码进行说明。二、工具函数方法一览// 检查设备是否可折叠staticisFoldable():boolean// 获取当前折叠状态展开/折叠/半折叠staticgetFoldStatus():display.FoldStatus// 获取当前折叠显示模式全屏/主屏/子屏/协同staticgetFoldDisplayMode():display.FoldDisplayMode// 监听折叠状态变化staticonFoldStatusChange(callback:Callbackdisplay.FoldStatus):void// 取消监听折叠状态变化staticoffFoldStatusChange(callback?:Callbackdisplay.FoldStatus):void// 监听折叠角度变化0~180°staticonFoldAngleChange(callback:CallbackArraynumber):void// 取消监听折叠角度变化staticoffFoldAngleChange(callback?:CallbackArraynumber):void三、状态查询方法详解3.1isFoldable()— 检测是否可折叠设备源码staticisFoldable():boolean{returndisplay.isFoldable();}说明返回true表示是折叠屏设备false表示普通屏幕。这是一切折叠屏适配的前提判断——在非折叠设备上调用折叠相关 API 没有意义。注意需要SystemCapability.Window.SessionManager若系统不支持会抛出BusinessError 1400003。3.2getFoldStatus()— 获取折叠状态源码staticgetFoldStatus():display.FoldStatus{returndisplay.getFoldStatus();}display.FoldStatus枚举值说明枚举值数字含义FOLD_STATUS_UNKNOWN0折叠状态未知FOLD_STATUS_EXPANDED1完全展开FOLD_STATUS_FOLDED2完全折叠FOLD_STATUS_HALF_FOLDED3半折叠悬停态适合桌面模式Demo 中的枚举转换getFoldStatusLabel(status:display.FoldStatus):string{switch(status){casedisplay.FoldStatus.FOLD_STATUS_UNKNOWN:return未知 (FOLD_STATUS_UNKNOWN0);casedisplay.FoldStatus.FOLD_STATUS_EXPANDED:return完全展开 (FOLD_STATUS_EXPANDED1);casedisplay.FoldStatus.FOLD_STATUS_FOLDED:return折叠 (FOLD_STATUS_FOLDED2);casedisplay.FoldStatus.FOLD_STATUS_HALF_FOLDED:return半折叠 (FOLD_STATUS_HALF_FOLDED3);default:return未知 (${status});}}3.3getFoldDisplayMode()— 获取折叠显示模式源码staticgetFoldDisplayMode():display.FoldDisplayMode{returndisplay.getFoldDisplayMode();}display.FoldDisplayMode枚举值说明枚举值数字含义FOLD_DISPLAY_MODE_UNKNOWN0显示模式未知FOLD_DISPLAY_MODE_FULL1全屏展开后使用整个大屏FOLD_DISPLAY_MODE_MAIN2主屏幕显示内屏FOLD_DISPLAY_MODE_SUB3子屏幕显示外屏FOLD_DISPLAY_MODE_COORDINATION4双屏协同内外屏同时工作Demo 中的枚举转换getFoldDisplayModeLabel(mode:display.FoldDisplayMode):string{switch(mode){casedisplay.FoldDisplayMode.FOLD_DISPLAY_MODE_UNKNOWN:return未知 (FOLD_DISPLAY_MODE_UNKNOWN0);casedisplay.FoldDisplayMode.FOLD_DISPLAY_MODE_FULL:return全屏 (FOLD_DISPLAY_MODE_FULL1);casedisplay.FoldDisplayMode.FOLD_DISPLAY_MODE_MAIN:return主屏 (FOLD_DISPLAY_MODE_MAIN2);casedisplay.FoldDisplayMode.FOLD_DISPLAY_MODE_SUB:return子屏 (FOLD_DISPLAY_MODE_SUB3);casedisplay.FoldDisplayMode.FOLD_DISPLAY_MODE_COORDINATION:return双屏协同 (FOLD_DISPLAY_MODE_COORDINATION4);default:return未知 (${mode});}}四、监听方法详解4.1 折叠状态变化监听源码staticonFoldStatusChange(callback:Callbackdisplay.FoldStatus){display.on(foldStatusChange,callback);}staticoffFoldStatusChange(callback?:Callbackdisplay.FoldStatus){display.off(foldStatusChange,callback);}说明onFoldStatusChange注册监听当折叠状态改变时如从展开折叠、折叠展开回调函数会被触发。offFoldStatusChange注销监听。callback参数可选若不传则注销所有折叠状态监听器。4.2 折叠角度变化监听源码staticonFoldAngleChange(callback:CallbackArraynumber){display.on(foldAngleChange,callback);}staticoffFoldAngleChange(callback?:CallbackArraynumber){display.off(foldAngleChange,callback);}说明回调函数接收一个Arraynumber每个元素是对应折轴的角度0~180 度。单折轴设备返回长度为 1 的数组双折轴设备如三折屏返回长度为 2 的数组第一个值是折轴一的角度第二个是折轴二的角度。折叠角度在用户手动调整屏幕折叠程度时会持续变化。五、完整演示代码5.1 状态查询loadFoldInfo(){// isFoldable()constfoldableDisplayUtil.isFoldable();this.isFoldableResultfoldable?可折叠设备:非折叠设备;this.addLog(Fold,isFoldable() ${foldable},info);// getFoldStatus()constfoldStatusDisplayUtil.getFoldStatus();this.foldStatusValuefoldStatus.toString();this.foldStatusLabelthis.getFoldStatusLabel(foldStatus);this.addLog(Fold,getFoldStatus() ${this.foldStatusLabel},info);// getFoldDisplayMode()constfoldModeDisplayUtil.getFoldDisplayMode();this.foldDisplayModeValuefoldMode.toString();this.foldDisplayModeLabelthis.getFoldDisplayModeLabel(foldMode);this.addLog(Fold,getFoldDisplayMode() ${this.foldDisplayModeLabel},info);}5.2 监听器注册与注销registerFoldStatusChange(){if(this.foldStatusCallback!undefined){this.addLog(Fold,折叠状态监听已注册无需重复,warn);return;}this.foldStatusCallback(status:display.FoldStatus){constlabelthis.getFoldStatusLabel(status);this.lastFoldStatusChangelabel;this.addLog(Fold,折叠状态变化:${label},success);};DisplayUtil.onFoldStatusChange(this.foldStatusCallback);this.foldStatusChangeStatus已注册;this.foldStatusChangeColor#00C853;this.addLog(Fold,onFoldStatusChange() 已注册,success);}unregisterFoldStatusChange(){if(this.foldStatusCallback!undefined){DisplayUtil.offFoldStatusChange(this.foldStatusCallback);this.foldStatusCallbackundefined;this.foldStatusChangeStatus已注销;this.foldStatusChangeColor#888;this.addLog(Fold,offFoldStatusChange() 已注销,warn);}}registerFoldAngleChange(){if(this.foldAngleCallback!undefined){this.addLog(Fold,折叠角度监听已注册无需重复,warn);return;}this.foldAngleCallback(angles:Arraynumber){this.lastFoldAngleChangeangles.length0?angles.map(a${a}°).join(, ):无数据;this.addLog(Fold,折叠角度变化:${this.lastFoldAngleChange},success);};DisplayUtil.onFoldAngleChange(this.foldAngleCallback);this.foldAngleChangeStatus已注册;this.foldAngleChangeColor#00C853;this.addLog(Fold,onFoldAngleChange() 已注册,success);}5.3 UI 渲染// ══ 折叠设备 ═══════════════════════════════════════if(this.activeTab3){// 折叠状态概览Column(){Text(折叠设备状态).fontSize(13).fontColor(#666).fontWeight(FontWeight.Medium).alignSelf(ItemAlign.Start).margin({bottom:10})Row(){Column(){Text(this.isFoldableResult).fontSize(14).fontWeight(FontWeight.Bold).fontColor(this.isFoldableResult.includes(可折叠)?#00C853:#888)Text(isFoldable()).fontSize(10).fontColor(#888)}.layoutWeight(1).alignItems(HorizontalAlign.Center)Column(){Text(this.foldStatusLabel.includes(未知)?N/A:this.foldStatusLabel.split( )[0]).fontSize(14).fontWeight(FontWeight.Bold).fontColor(#4080FF)Text(getFoldStatus()).fontSize(10).fontColor(#888)}.layoutWeight(1).alignItems(HorizontalAlign.Center)Column(){Text(this.foldDisplayModeLabel.includes(未知)?N/A:this.foldDisplayModeLabel.split( )[0]).fontSize(14).fontWeight(FontWeight.Bold).fontColor(#D63384)Text(getFoldDisplayMode()).fontSize(10).fontColor(#888)}.layoutWeight(1).alignItems(HorizontalAlign.Center)}.width(100%).margin({bottom:10})Button(刷新折叠状态).fontSize(12).height(34).backgroundColor(#4080FF).fontColor(#FFF).onClick((){this.loadFoldInfo();})}.width(100%).padding(14).backgroundColor(#FFFFFF).borderRadius(12)// 枚举值说明this.buildSectionCard(FoldStatus 枚举值,[{label:FOLD_STATUS_UNKNOWN 0,value:未知},{label:FOLD_STATUS_EXPANDED 1,value:完全展开},{label:FOLD_STATUS_FOLDED 2,value:折叠},{label:FOLD_STATUS_HALF_FOLDED 3,value:半折叠悬停态},]asSectionRow[])this.buildSectionCard(FoldDisplayMode 枚举值,[{label:FOLD_DISPLAY_MODE_UNKNOWN 0,value:未知},{label:FOLD_DISPLAY_MODE_FULL 1,value:全屏显示},{label:FOLD_DISPLAY_MODE_MAIN 2,value:主屏幕显示},{label:FOLD_DISPLAY_MODE_SUB 3,value:子屏幕显示},{label:FOLD_DISPLAY_MODE_COORDINATION 4,value:双屏协同},]asSectionRow[])}六、生命周期中正确管理监听器一个非常重要的实践是在页面销毁时注销所有监听器避免内存泄漏。aboutToDisappear():void{this.unregisterAllListeners();}unregisterAllListeners(){if(this.foldStatusCallback!undefined){DisplayUtil.offFoldStatusChange(this.foldStatusCallback);this.foldStatusCallbackundefined;}if(this.foldAngleCallback!undefined){DisplayUtil.offFoldAngleChange(this.foldAngleCallback);this.foldAngleCallbackundefined;}}七、实际应用场景场景 1折叠屏布局自适应DisplayUtil.onFoldStatusChange((status){if(statusdisplay.FoldStatus.FOLD_STATUS_EXPANDED){// 展开状态使用大屏布局双列this.useWideLayouttrue;}elseif(statusdisplay.FoldStatus.FOLD_STATUS_FOLDED){// 折叠状态使用小屏布局单列this.useWideLayoutfalse;}elseif(statusdisplay.FoldStatus.FOLD_STATUS_HALF_FOLDED){// 半折叠悬停态可以做帐篷模式布局this.useTentLayouttrue;}});场景 2根据角度触发特效DisplayUtil.onFoldAngleChange((angles){constangleangles[0];if(angle90){// 屏幕几乎展开进入全屏模式this.enterFullScreenMode();}elseif(angle30){// 屏幕几乎合拢this.enterCompactMode();}});八、小结方法说明isFoldable()判断是否折叠设备先决条件getFoldStatus()获取当前折叠状态未知/展开/折叠/半折叠getFoldDisplayMode()获取显示模式全屏/主屏/子屏/协同onFoldStatusChange(cb)监听折叠状态变化offFoldStatusChange(cb?)注销折叠状态监听onFoldAngleChange(cb)监听折叠角度0~180°offFoldAngleChange(cb?)注销折叠角度监听折叠屏是 HarmonyOS 生态的重要差异化能力掌握这些 API能让你的应用在折叠屏设备上展现出与众不同的体验。