鸿蒙刘海屏、水滴屏、瀑布屏适配：用 DisplayUtil 获取不可用区域

一、前言

近期发现一款很有意思的HarmonyOS 三方库, 地址 @pura/harmony-utils(V1.4.0) , 作者是"桃花镇童长老", 我这里也是直接通过该作者公布的源码进行案例编写进行,写了到目前写了一部分demo ,感觉确实很有帮助,这里呢也是开始写一个系列的演示demo 供大家参考。如有帮助可以在OpenHarmony中进行下载安装进行使用哦

案例demo导航展示

↓↓↓↓↓↓接下来言归正传 ↓↓↓↓

现代手机大多采用异形屏设计：刘海屏、水滴屏、挖孔屏、瀑布屏……这些屏幕在顶部或边角存在不可用区域（即摄像头挖孔区域），如果应用内容出现在这些区域，就会被摄像头遮挡，影响用户体验。

HarmonyOS 提供了display.getCutoutInfo()API 来获取这些不可用区域的坐标信息，DisplayUtil对其进行了二次封装，提供了更简洁的getCutoutRect()和getCutoutHeight()方法。

二、工具函数方法

// 获取挖孔/刘海区域的矩形坐标（异步）staticasyncgetCutoutRect():Promise<display.Rect>// 获取挖孔/刘海区域的高度（px，异步）staticasyncgetCutoutHeight():Promise<number>

三、方法详解

3.1getCutoutRect()— 获取不可用区域矩形

源码：

staticasyncgetCutoutRect():Promise<display.Rect>{letcutoutInfo=awaitDisplayUtil.getDefaultDisplaySync().getCutoutInfo();returncutoutInfo.boundingRects[0];}

说明：

• getCutoutInfo()返回的是完整的CutoutInfo对象，包含boundingRects（不可用区域矩形数组）。
• DisplayUtil取数组第一个元素（boundingRects[0]），即主挖孔区域。
• 返回的display.Rect对象包含：
  • left：矩形左边距（px）
  • top：矩形上边距（px）
  • width：矩形宽度（px）
  • height：矩形高度（px）

如果设备没有挖孔（全面屏）：boundingRects可能为空，boundingRects[0]返回undefined，Demo 中对此有判断处理。

3.2getCutoutHeight()— 获取挖孔区域高度

源码：

staticasyncgetCutoutHeight():Promise<number>{letrect=awaitDisplayUtil.getCutoutRect();if(rect){returnrect.height;}return0;}

说明：

• 如果有挖孔区域，返回该区域的高度（px）。
• 如果没有挖孔区域（全面屏），返回0。

这个方法非常实用：在计算顶部布局安全区域时，直接用挖孔高度来做内边距偏移即可。

四、完整演示代码

4.1 数据加载

loadCutoutInfo(){this.cutoutLoading=true;DisplayUtil.getCutoutRect().then((rect)=>{this.cutoutLoading=false;if(rect){this.cutoutRectInfo=`left:${rect.left}, top:${rect.top}, width:${rect.width}, height:${rect.height}`;this.addLog('Cutout',`getCutoutRect() OK -${this.cutoutRectInfo}`,'success');}else{this.cutoutRectInfo='无挖孔/刘海区域（全面屏）';this.addLog('Cutout','getCutoutRect() - 无挖孔区域','info');}}).catch((e:Error)=>{this.cutoutLoading=false;this.cutoutRectInfo=`获取失败:${e.message}`;this.addLog('Cutout',`getCutoutRect() 失败:${e.message}`,'error');});DisplayUtil.getCutoutHeight().then((h)=>{this.cutoutHeightInfo=h>0?`${h}px`:'无';this.addLog('Cutout',`getCutoutHeight() =${h}px`,'info');}).catch((e:Error)=>{this.cutoutHeightInfo=`失败:${e.message}`;});}

4.2 UI 渲染

// ══ 挖孔屏 ════════════════════════════════════════if(this.activeTab===2){Column(){Text('getCutoutRect() - 获取挖孔屏区域').fontSize(13).fontColor('#666').fontWeight(FontWeight.Medium).alignSelf(ItemAlign.Start).margin({bottom:8})Row(){Text('区域信息:').fontSize(12).fontColor('#888')if(this.cutoutLoading){LoadingProgress().width(16).height(16).margin({left:6})Text('加载中...').fontSize(12).fontColor('#888').margin({left:4})}else{Text(this.cutoutRectInfo||'无').fontSize(12).fontFamily('monospace').fontColor('#4080FF').margin({left:6})}}.width('100%').margin({bottom:8})Row(){Text('挖孔高度:').fontSize(12).fontColor('#888')Text(this.cutoutHeightInfo||'--').fontSize(12).fontWeight(FontWeight.Bold).fontColor('#D63384').margin({left:6})}.width('100%').margin({bottom:10})Row(){Text('💡 ').fontSize(12).fontColor('#FF9800')Text('挖孔区域用于规避刘海/水滴/瀑布屏不可用区域，确保内容不被遮挡').fontSize(11).fontColor('#888')}.width('100%').backgroundColor('#FFF7E6').padding(8).borderRadius(6).margin({bottom:10})Button('刷新挖孔信息').fontSize(12).height(34).backgroundColor('#4080FF').fontColor('#FFF').onClick(()=>{this.loadCutoutInfo();})}.width('100%').padding(14).backgroundColor('#FFFFFF').borderRadius(12)this.buildApiCard('Cutout API',[{name:'getCutoutRect()',desc:'异步获取第一个挖孔/刘海区域 rect（left/top/width/height）'},{name:'getCutoutHeight()',desc:'异步获取挖孔区域高度（px），无挖孔返回 0'},]asApiRow[])}

五、实际应用场景

场景 1：计算顶部安全内边距

// 在页面初始化时获取挖孔高度，用于计算顶部安全区域asyncaboutToAppear(){constcutoutHeight=awaitDisplayUtil.getCutoutHeight();// 加上系统状态栏高度，得到真正的安全顶部内边距this.safeTopPadding=cutoutHeight;}

场景 2：判断是否全面屏并调整布局

asynccheckFullScreen(){constheight=awaitDisplayUtil.getCutoutHeight();if(height===0){// 全面屏，顶部内容可以贴边this.topInset=0;}else{// 异形屏，需要避让挖孔区域this.topInset=height;}}

场景 3：获取完整矩形信息用于精确避让

asyncavoidCutout(){constrect=awaitDisplayUtil.getCutoutRect();if(rect){// 挖孔在顶部中央，宽度为 rect.width，高度为 rect.height// 可以用于计算内容左右边距，确保重要内容不出现在挖孔区域constsafeLeft=rect.left;constsafeRight=DisplayUtil.getWidth()-rect.left-rect.width;console.info(`安全左边距:${safeLeft}px, 安全右边距:${safeRight}px`);}}

六、注意事项

1. 全面屏处理：无挖孔的全面屏设备，getCutoutRect()返回的数组可能为空，需要判断rect是否为undefined。

2. 单位为物理像素（px）：获取的矩形坐标是物理像素，在 ArkUI 中使用时需要转换为 vp（vp = px / densityPixels）。

3. 异步方法：两个方法都是异步的（Promise），需要在aboutToAppear的async函数中await，或使用.then().catch()。

4. 多个挖孔区域：boundingRects是数组，某些设备可能有多个挖孔区域（如顶部+底部）。DisplayUtil只取了[0]，若需要处理所有区域，需要直接调用display.getCutoutInfo()。

七、小结

这两个方法是实现全面屏适配的关键。只需一行await DisplayUtil.getCutoutHeight()，就能在所有类型的屏幕上正确规避不可用区域，让你的应用在各种异形屏上都能完美呈现。