HarmonyOS WindowUtil 窗口属性查询详解：getWindowProperties 与快捷 isXxx 方法全解析

文章目录背景方法总览WindowUtil 是什么getWindowProperties() — 一口气拿到所有属性快捷状态检查方法isWindowSupportWideGamut() — 异步检测宽色域getWindowType() 和 getWindowStatus()findWindow 和 getLastWindow错误处理要养成习惯写在最后背景近期发现一款很有意思的HarmonyOS 三方库, 地址 pura/harmony-utils(V1.4.0) , 作者是桃花镇童长老, 我这里也是直接通过该作者公布的源码进行案例编写进行,写了到目前写了一部分demo ,感觉确实很有帮助,这里呢也是开始写一个系列的演示demo 供大家参考。如有帮助可以在OpenHarmony中进行下载安装进行使用哦案例demo导航展示↓↓↓↓↓↓接下来言归正传 ↓↓↓↓刚上手 HarmonyOS 开发的时候想知道当前窗口是不是全屏、有没有开隐私模式、屏幕亮度是多少——翻了一圈官方文档找到了window.Window对象但调用路径又长又绕。用了WindowUtil之后一行代码搞定真的省了不少事。方法总览WindowUtil 是什么WindowUtil是对 HarmonyOS 原生kit.ArkUI中window模块的封装把常用的窗口操作都变成了更简洁的静态方法。不用每次都去拿 Window 实例直接WindowUtil.xxx()调用就行。getWindowProperties() — 一口气拿到所有属性最基础的用法是调getWindowProperties()它返回一个包含窗口所有属性的对象。try{constpropsWindowUtil.getWindowProperties();this.addLog(type${props.type}isFullScreen${props.isFullScreen}isPrivacyMode${props.isPrivacyMode});this.addLog(brightness${props.brightness}focusable${props.focusable}touchable${props.touchable});}catch(e){this.addLog(Error:${e});}运行后你会看到类似这样的日志输出type1 isFullScreenfalse isPrivacyModefalse brightness-1 focusabletrue touchabletrue返回字段说明字段含义典型值type窗口类型应用主窗口为11isFullScreen是否全屏falseisPrivacyMode是否隐私模式截屏遮挡falsebrightness屏幕亮度-1表示跟随系统-1focusable窗口是否可获焦truetouchable窗口是否可触摸true这个方法适合需要一次性读取多个属性的场景比如页面加载时做状态同步。快捷状态检查方法如果只想知道某一个状态不需要调getWindowProperties()然后再取字段WindowUtil提供了一系列快捷的isXxx()方法。// 是否全屏this.Btn(isFullScreen(),#2980B9,(){try{this.addLog(isFullScreen() →${WindowUtil.isFullScreen()});}catch(e){this.addLog(Error:${e});}})// 是否隐私模式this.Btn(isPrivacyMode(),#2980B9,(){try{this.addLog(isPrivacyMode() →${WindowUtil.isPrivacyMode()});}catch(e){this.addLog(Error:${e});}})// 是否屏幕常亮this.Btn(isKeepScreenOn(),#1A6BB5,(){try{this.addLog(isKeepScreenOn() →${WindowUtil.isKeepScreenOn()});}catch(e){this.addLog(Error:${e});}})// 是否可获焦this.Btn(isFocusable(),#1A6BB5,(){try{this.addLog(isFocusable() →${WindowUtil.isFocusable()});}catch(e){this.addLog(Error:${e});}})// 是否可触摸this.Btn(isTouchable(),#154360,(){try{this.addLog(isTouchable() →${WindowUtil.isTouchable()});}catch(e){this.addLog(Error:${e});}})// 是否透明this.Btn(isTransparent(),#154360,(){try{this.addLog(isTransparent() →${WindowUtil.isTransparent()});}catch(e){this.addLog(Error:${e});}})// 是否已获焦当前是否在最前面this.Btn(isFocused(),#0E4C86,(){try{this.addLog(isFocused() →${WindowUtil.isFocused()});}catch(e){this.addLog(Error:${e});}})// 窗口是否正在显示this.Btn(isWindowShowing(),#0E4C86,(){try{this.addLog(isWindowShowing() →${WindowUtil.isWindowShowing()});}catch(e){this.addLog(Error:${e});}})这些方法都是同步返回的直接拿结果就行不需要await。isWindowSupportWideGamut() — 异步检测宽色域唯一有点特殊的是isWindowSupportWideGamut()它是异步方法需要用.then()获取结果this.Btn(isWindowSupportWideGamut() async,#083E6E,(){WindowUtil.isWindowSupportWideGamut().then(v{this.addLog(isWindowSupportWideGamut() →${v});}).catch((e:Error){this.addLog(Error:${e.message});});})宽色域Wide Color Gamut支持 P3 色彩空间高端屏幕才有。这个值对做图像处理、视频播放的同学比较有用。getWindowType() 和 getWindowStatus()除了isXxx()还有两个枚举值查询方法// 窗口类型数字枚举this.Btn(getWindowType(),#27AE60,(){try{this.addLog(getWindowType() →${WindowUtil.getWindowType()});}catch(e){this.addLog(Error:${e});}})// 窗口当前状态正常/最小化/最大化等this.Btn(getWindowStatus(),#1E8449,(){try{this.addLog(getWindowStatus() →${WindowUtil.getWindowStatus()});}catch(e){this.addLog(Error:${e});}})getWindowType()返回的是window.WindowType枚举值应用主窗口一般是1TYPE_APP。getWindowStatus()返回的是window.WindowStatusType枚举值比如FULL_SCREEN、FLOATING等对需要响应窗口状态变化的应用如分屏场景很有用。findWindow 和 getLastWindow有时候你需要拿到窗口对象本身去做更底层的操作// 按名称查找窗口this.Btn(findWindow(EntryAbility) 查找窗口,#E74C3C,(){constwWindowUtil.findWindow(EntryAbility);this.addLog(findWindow(EntryAbility) →${w?Window found:undefined});})// 获取当前最顶层的窗口异步this.Btn(getLastWindow() 获取顶层窗口,#C0392B,(){WindowUtil.getLastWindow().then(w{this.addLog(getLastWindow() → Window ok${!!w});}).catch((e:Error){this.addLog(Error:${e.message});});})findWindow通过 ability 名字查找拿到的是window.Window | undefined。getLastWindow是异步的返回当前上下文中最顶层的窗口实例。错误处理要养成习惯注意看上面所有同步方法都包在try/catch里了。这不是多此一举——如果 WindowUtil 没有初始化、或者窗口已经销毁这些方法会直接抛出异常。所以无论是用getWindowProperties()还是各种isXxx()都建议套一层try/catch避免崩溃。写在最后窗口属性查询是很多功能的基础比如做截屏保护要先判断isPrivacyMode()做沉浸式布局要先查isFullScreen()做显示适配要看getWindowStatus()。WindowUtil把这些都封装成了最简洁的调用形式建议先把这几个方法的返回值打印出来看看心里有个底后面做复杂功能就不容易踩坑了。