引言屏幕是应用与用户交互的唯一窗口。应用的布局适配、字体缩放、图片资源选择都依赖对屏幕参数的准确感知。HarmonyOS NEXT 通过ohos.display模块将屏幕元信息统一暴露为同步可读的属性和事件回调——分辨率、刷新率、像素密度、旋转角度、折叠状态、录屏检测等全部无需权限即可获取。ohos.display属于kit.ArkUI是 UI 框架层的核心模块。与 Android 的DisplayMetrics/WindowManager和 iOS 的UIScreen不同ohos.display不仅提供基础的分辨率和密度还内置了对折叠设备Foldable的完整支持——isFoldable()判断、getFoldStatus()查询、on(foldStatusChange)实时监听以及isCaptured()录屏检测。这些在 Android 和 iOS 中需要分散在多个 API 中的能力在鸿蒙中被整合到了一个模块中。本文将深入讲解ohos.display的屏幕属性读取、密度体系、旋转识别和折叠状态管理四大核心能力并构建一个屏幕信息实验室Demo在一个页面中完整展示屏幕全部参数。一、API 架构同步属性 事件监听1.1 核心设计理念ohos.display的 API 分为两层同步读取层提供屏幕属性的即时获取全部以Sync后缀或直接属性访问的形式提供事件监听层通过on/off模式提供折叠状态、录屏状态等实时变化的回调通知。importdisplayfromohos.display;// 同步瞬间返回完整 Display 对象constddisplay.getDefaultDisplaySync();// 直接读取属性——全部同步console.log(d.width × d.height);// 分辨率console.log(d.refreshRate.toFixed(0) Hz);// 刷新率console.log(d.densityDPI.toFixed(0) DPI);// 像素密度// 事件监听折叠状态变化display.on(foldStatusChange,(fs:display.FoldStatus){if(fsdisplay.FoldStatus.FOLD_STATUS_EXPANDED){// 切换到展开布局}});这种同步读取 事件回调的分层设计非常实用——屏幕基础属性在应用生命周期内通常不变分辨率、DPI同步读取零开销折叠状态和录屏状态是动态变化的事件监听模型及时且精确。1.2 getDefaultDisplaySync —— 默认屏幕对象getDefaultDisplaySync()是屏幕信息的核心入口。它同步返回一个Display对象包含当前默认屏幕的全部参数。这个方法无参数、无权限要求可以在任何地方调用。constddisplay.getDefaultDisplaySync();返回的Display对象是一个属性只读的快照——屏幕参数不会自动更新。如果需要获取最新值例如屏幕旋转后需要重新调用getDefaultDisplaySync()。Display 接口完整属性属性类型说明idnumber屏幕唯一标识符namestring屏幕名称如 “built-in”aliveboolean屏幕是否活跃stateDisplayState屏幕状态亮屏/息屏/待机/VRwidthnumber屏幕宽度像素heightnumber屏幕高度像素refreshRatenumber屏幕刷新率Hzrotationnumber屏幕旋转角度0/90/180/270densityDPInumber屏幕物理像素密度DPIdensityPixelsnumber逻辑像素密度缩放系数scaledDensitynumber字体缩放密度1.3 DisplayState —— 屏幕状态枚举DisplayState是屏幕当前的工作状态有四种取值枚举值说明典型场景STATE_ON亮屏正常使用中STATE_OFF息屏锁屏后、按电源键关闭STATE_DOZE待机常亮显示AOD 息屏显示模式STATE_VRVR 模式连接 VR 设备时privatestateLabel(state:display.DisplayState):string{if(statedisplay.DisplayState.STATE_ON)return亮屏;if(statedisplay.DisplayState.STATE_OFF)return息屏;if(statedisplay.DisplayState.STATE_DOZE)return待机;if(statedisplay.DisplayState.STATE_VR)returnVR 模式;return未知;}在实际开发中state可用于判断是否需要在息屏或待机状态下暂停动画、降低刷新率以节省电量。1.4 分辨率与刷新率width和height返回屏幕的物理像素分辨率。与 Android 的DisplayMetrics.widthPixels类似这两个值代表屏幕的实际像素数。refreshRate返回屏幕当前的刷新率Hz。大多数手机屏幕为 60Hz高刷屏为 90Hz 或 120Hz。开发者可以根据刷新率调整动画帧率constrrdisplay.getDefaultDisplaySync().refreshRate;if(rr90){// 高刷屏使用 90fps 流畅动画}else{// 标准屏使用 60fps 动画即可}1.5 rotation —— 屏幕旋转角度rotation返回当前屏幕的旋转角度0°、90°、180°、270°。这个值反映的是屏幕物理旋转状态不是应用窗口的朝向。配合ohos.window的setPreferredOrientation()使用时rotation 可以帮助判断用户当前的持握方向。privaterotationLabel(rot:number):string{if(rot0)return0°竖屏;if(rot90)return90°横屏;if(rot180)return180°倒置;if(rot270)return270°反向横屏;returnrot.toString()°;}二、密度体系DPI、像素密度与缩放密度2.1 三层密度模型ohos.display提供了三层密度概念这是理解鸿蒙 UI 尺寸体系的关键属性说明典型值手机用途densityDPI物理像素密度每英寸像素数420-560判断屏幕精细度等级densityPixels逻辑像素缩放系数2.75-3.5物理像素与逻辑像素的换算scaledDensity字体缩放密度与 densityPixels 相近字体大小的自动适配densityDPI是屏幕的物理属性反映了硬件的像素密度。值越高屏幕越精细。开发者通常不需要直接使用这个值做布局计算但可以用它来判断设备的屏幕等级低清/高清/超清。densityPixels是物理像素与逻辑像素vp之间的换算系数。在 ArkUI 中所有尺寸单位vp、fp都是逻辑像素框架会自动根据 densityPixels 换算为物理像素。只有在需要精确控制物理像素如 Canvas 绘制、图片解码时才需要读取这个值。scaledDensity是在 densityPixels 基础上叠加用户字体缩放设置后的系数。当用户在系统设置中调整字体大小时这个值会相应变化。// 三个密度的关系constddisplay.getDefaultDisplaySync();constphysicalPx100*d.densityPixels;// 100vp → 物理像素constfontSize16*d.scaledDensity;// 16fp → 物理像素2.2 密度与资源适配在 HarmonyOS 的资源管理中系统会根据 densityDPI 自动选择最合适的资源文件如resources/base/mediavsresources/xxhdpi/media。开发者通常不需要手动判断 DPI 等级但了解当前设备的 DPI 值有助于调试资源加载问题。三、折叠设备支持3.1 isFoldable —— 判断设备是否可折叠isFoldable()同步返回boolean判断当前设备是否为折叠设备折叠屏手机、平板等。constfoldabledisplay.isFoldable();if(foldable){// 初始化折叠适配逻辑}这是折叠适配的第一步——先判断设备类型再决定是否启用折叠相关的 UI 逻辑。3.2 getFoldStatus —— 当前折叠状态getFoldStatus()同步返回当前折叠状态值来自FoldStatus枚举枚举值说明布局策略FOLD_STATUS_EXPANDED展开状态大屏布局充分利用空间FOLD_STATUS_FOLDED折叠状态小屏布局优化单手操作FOLD_STATUS_HALF_FOLDED半开状态中间态通常保持前一个状态布局privatefoldLabel(status:display.FoldStatus):string{if(statusdisplay.FoldStatus.FOLD_STATUS_EXPANDED)return展开;if(statusdisplay.FoldStatus.FOLD_STATUS_FOLDED)return折叠;if(statusdisplay.FoldStatus.FOLD_STATUS_HALF_FOLDED)return半开;return未知;}在半开状态下如 Flex 模式悬停应用可以选择显示特殊的分屏 UI——例如上半屏播放视频、下半屏显示控制面板。3.3 折叠状态实时监听on(foldStatusChange, callback)和off(foldStatusChange, callback)提供折叠状态的实时监听。当用户折叠或展开设备时回调会被立即触发。privatestartFoldListen():void{if(!display.isFoldable()){return;}display.on(foldStatusChange,(fs:display.FoldStatus){this.foldStatusthis.foldLabel(fs);// 根据新状态调整布局});}// 离开页面时取消监听privatestopFoldListen():void{display.off(foldStatusChange);}需要注意的是off()必须在组件销毁aboutToDisappear时调用否则会造成内存泄漏。Demo 中我们将监听开关绑定到 Toggle 按钮用户可以手动开启/关闭折叠状态监听。四、实战 Demo屏幕信息实验室4.1 页面设计屏幕信息实验室页面分为六个功能区域屏幕身份卡片展示屏幕名称大字标题、活跃状态活跃/未活跃带颜色标签、屏幕 ID。下方三栏展示屏幕 ID、活跃状态和录屏检测结果。分辨率与刷新率面板双栏展示物理分辨率width × height和刷新率Hz右侧展示当前旋转角度0°竖屏/90°横屏/180°倒置/270°反向横屏。显示密度面板三栏展示三层密度——DPI物理像素密度、像素密度逻辑缩放系数、缩放密度字体缩放系数。折叠状态面板展示是否折叠设备、当前折叠状态展开/折叠/半开。提供两个按钮——刷新折叠状态重新读取最新值监听折叠Toggle 按钮控制折叠状态监听的开启与关闭。API 能力说明以灰色文字展示核心 API 的方法签名和功能说明。操作日志记录所有操作按时间倒序排列不同类别success / error / system以不同颜色标记。4.2 核心实现数据模型StatedisplayName:string--;StatedisplayId:string--;StatedisplayAlive:string--;StatedisplayState:string--;Stateresolution:string--;StaterefreshRate:string--;StatedensityDPI:string--;StatedensityPixels:string--;StatescaledDensity:string--;Staterotation:string--;StateisFoldable:booleanfalse;StatefoldStatus:string--;StatefoldListening:booleanfalse;StateisCaptured:string--;Statelogs:LogEntry[][];每个屏幕属性独立一个State变量确保 UI 能够单独更新每一项。一次性读取全部属性privaterefreshAll():void{try{constddisplay.getDefaultDisplaySync();this.displayNamed.name;this.displayIdd.id.toString();this.displayAlived.alive?活跃:未活跃;this.displayStatethis.stateLabel(d.state);this.resolutiond.width.toString() × d.height.toString();this.refreshRated.refreshRate.toFixed(0) Hz;this.densityDPId.densityDPI.toFixed(0) DPI;this.densityPixelsd.densityPixels.toFixed(3);this.scaledDensityd.scaledDensity.toFixed(3);this.rotationthis.rotationLabel(d.rotation);}catch(e){this.addLog(获取屏幕信息失败,error);}try{this.isFoldabledisplay.isFoldable();if(this.isFoldable){constfsdisplay.getFoldStatus();this.foldStatusthis.foldLabel(fs);}else{this.foldStatus非折叠设备;}}catch(e){this.isFoldablefalse;}try{this.isCaptureddisplay.isCaptured()?录屏中:正常;}catch(e){this.isCaptured--;}}每个独立功能块都使用 try/catch 包裹确保单个模块的异常不影响其他模块的数据读取。折叠状态监听 ToggleprivatetoggleFoldListen():void{if(this.foldListening){this.stopFoldListen();}else{this.startFoldListen();}}privatestartFoldListen():void{if(!display.isFoldable()){this.addLog(当前设备不支持折叠,system);return;}display.on(foldStatusChange,(fs:display.FoldStatus){this.foldStatusthis.foldLabel(fs);this.addLog(折叠状态变化: this.foldLabel(fs),system);});this.foldListeningtrue;this.addLog(已开启折叠状态监听,success);}privatestopFoldListen():void{try{display.off(foldStatusChange);this.foldListeningfalse;this.addLog(已关闭折叠状态监听,system);}catch(e){this.addLog(关闭折叠监听失败,error);}}4.3 交互方式Demo 提供四个核心交互点刷新全部信息屏幕身份卡片中的隐式刷新——每次进入页面时自动调用refreshAll()读取所有属性。Demo 中不设显式刷新按钮因为屏幕基础属性在应用生命周期内通常不变但折叠状态面板有独立刷新按钮。刷新折叠状态单击刷新折叠状态按钮重新调用isFoldable()getFoldStatus()更新折叠设备信息和当前折叠状态。折叠状态监听 Toggle单击监听折叠按钮开启监听按钮变为红色停止监听再次单击关闭监听按钮恢复青色监听折叠。开启后折叠设备的状态变化会实时反映在 UI 和操作日志中。操作日志每次 API 调用和状态变化都以时间戳 消息的形式记录到日志区域方便追踪操作时序。五、实际应用场景5.1 折叠屏布局适配classFoldableLayoutManager{privateisExpanded:booleanfalse;constructor(){if(display.isFoldable()){this.isExpandeddisplay.getFoldStatus()display.FoldStatus.FOLD_STATUS_EXPANDED;display.on(foldStatusChange,(fs:display.FoldStatus){this.isExpandedfsdisplay.FoldStatus.FOLD_STATUS_EXPANDED;this.onLayoutChanged();});}}getLayoutMode():single|dual{returnthis.isExpanded?dual:single;}privateonLayoutChanged():void{// 通知 UI 层重新布局}}5.2 根据屏幕密度选择图片资源functiongetImageQuality():low|medium|high{constdpidisplay.getDefaultDisplaySync().densityDPI;if(dpi480)returnhigh;if(dpi320)returnmedium;returnlow;}虽然 HarmonyOS 的资源系统会自动匹配 DPI 等级但在使用网络图片时可以根据此值请求不同分辨率的图片以优化流量和加载速度。5.3 高刷屏动画优化functiongetAnimationFPS():number{constrrdisplay.getDefaultDisplaySync().refreshRate;if(rr120)return120;if(rr90)return90;return60;}5.4 录屏检测functiononSensitiveContent():void{if(display.isCaptured()){// 检测到录屏隐藏敏感信息、添加水印showWatermark();}}isCaptured()返回当前屏幕是否正在被录制录屏或投屏这在金融、社交等涉及隐私保护的场景中非常实用。六、ArkTS 使用注意事项6.1 Display 对象是快照getDefaultDisplaySync()返回的Display对象是调用时刻的快照不会自动更新。如果屏幕发生了旋转或插入了外接显示器需要重新调用来获取最新值。这与 Android 的DisplayMetrics行为一致。6.2 事件监听的正确清理display.on(foldStatusChange, callback)注册的监听器必须在组件生命周期结束时通过display.off(foldStatusChange, callback)移除。在aboutToDisappear()中执行取消操作是最佳实践。6.3 非折叠设备的兼容处理在非折叠设备上isFoldable()返回falsegetFoldStatus()的行为是未定义的。代码中必须先判断isFoldable()的返回值再决定是否调用折叠相关 API。6.4 densityPixels 与 scaledDensity 的区别densityPixels是物理像素与逻辑像素vp的换算系数scaledDensity在此基础上叠加了用户的字体缩放设置。在布局计算中使用densityPixels在字号计算中使用scaledDensity。七、总结ohos.display是 HarmonyOS NEXT 中获取屏幕参数和监听显示状态变化的核心模块。通过本文的学习你应该已经掌握同步读取模型getDefaultDisplaySync()返回Display对象包含 id/name/alive/state/refreshRate/rotation/width/height/densityDPI/densityPixels/scaledDensity——全部同步可读三层密度体系densityDPI物理硬件密度、densityPixels逻辑像素缩放系数、scaledDensity字体缩放密度分别服务于资源匹配、布局换算和字体适配屏幕状态识别DisplayState枚举亮屏/息屏/待机/VR和rotation角度值0°/90°/180°/270°是节电策略和方向适配的依据折叠设备支持isFoldable()判断 getFoldStatus()查询 on/off(foldStatusChange)实时监听构成完整的折叠屏适配方案录屏检测isCaptured()同步返回当前是否处于录屏/投屏状态是隐私保护的重要检测点ohos.display的最佳使用模式可以总结为应用启动时全量读取 Display 对象建立屏幕画像折叠设备注册 foldStatusChange 监听驱动布局切换敏感场景调用 isCaptured 检测录屏状态。所有 API 同步为主、事件为辅——零权限、零延迟。屏幕信息是 UI 适配的元数据。虽然ohos.display的 API 数量不多但它覆盖了从基础分辨率到折叠状态的完整屏幕模型。在 HarmonyOS NEXT 的kit.ArkUI体系下ohos.display与ohos.window共同构成 UI 框架的双基石——display 负责屏幕是什么样的window 负责窗口怎么做。ohos.display属于kit.ArkUI是 HarmonyOS NEXT 屏幕信息查询与显示状态监听的统一入口。它的 API 设计体现了同步优先、事件补充的核心理念——基础属性零开销读取动态变化通过 on/off 回调精确感知。与 Android 的WindowManagerDisplayMetricsDisplayListener碎片化 API 相比ohos.display的一站式设计更加简洁和直观。
