HarmonyOS ArkUI 防截屏功能完全指南setWindowPrivacyMode 隐私窗口实践适用版本HarmonyOS NEXTAPI 23、DevEco Studio 6.1关键词ArkUI、防截屏、隐私窗口、setWindowPrivacyMode、PRIVACY_WINDOW、HarmonyOS NEXT效果一、前言在金融、支付、登录等敏感场景中防止应用界面被截屏或录屏是一项重要的安全需求。HarmonyOS NEXT 提供了setWindowPrivacyModeAPI开启后系统会拦截截屏和录屏操作保护窗口内容不被泄露。本文将详细介绍防截屏功能的完整实现流程包括权限配置、API 调用、生命周期管理并提供两个完整示例。二、功能原理开启隐私模式后系统将拦截截屏操作用户按截屏快捷键或手势时截取的图像中该窗口区域显示为黑色拦截录屏操作录屏软件或系统录屏时该窗口内容不会被录制多任务预览模糊在最近任务列表中窗口预览图可能被模糊处理用户操作 → 系统截屏/录屏请求 ↓ 检查 setWindowPrivacyMode 状态 ├── true隐私模式开启→ 窗口区域显示黑色/模糊 └── false正常模式 → 正常截取三、核心 API 详解3.1 setWindowPrivacyModewindow.setWindowPrivacyMode(isPrivacyMode:boolean,callback:AsyncCallbackvoid):void;参数类型说明isPrivacyModebooleantrue开启隐私模式防截屏false关闭callbackAsyncCallbackvoid异步回调返回操作结果也可以使用 Promise 风格window.setWindowPrivacyMode(isPrivacyMode): Promisevoid3.2 获取 Window 实例调用setWindowPrivacyMode需要先获取window.Window实例有两种主要方式方式一通过 WindowStage 获取Ability 层onWindowStageCreate(windowStage:window.WindowStage):void{letmainWindowwindowStage.getMainWindowSync();mainWindow.setWindowPrivacyMode(true,(err){...});}方式二通过 getLastWindow 获取组件/页面层import{window}fromkit.ArkUI;import{common}fromkit.AbilityKit;letcontextthis.getUIContext().getHostContext()ascommon.UIAbilityContext;window.getLastWindow(context).then((lastWindow){lastWindow.setWindowPrivacyMode(true,(err){...});});四、权限配置使用防截屏功能需要在module.json5中声明ohos.permission.PRIVACY_WINDOW权限。4.1 配置步骤第一步打开entry/src/main/module.json5第二步在module节点下添加requestPermissions字段{ module: { name: entry, type: entry, // ... 其他配置 requestPermissions: [ { name: ohos.permission.PRIVACY_WINDOW } ] } }权限说明ohos.permission.PRIVACY_WINDOW属于系统级权限system_grant无需用户手动授权系统会自动授予。4.2 完整 module.json5 示例{ module: { name: entry, type: entry, description: $string:module_desc, mainElement: EntryAbility, deviceTypes: [phone], deliveryWithInstall: true, installationFree: false, pages: $profile:main_pages, requestPermissions: [ { name: ohos.permission.PRIVACY_WINDOW } ], abilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ets, description: $string:EntryAbility_desc, icon: $media:layered_image, label: $string:EntryAbility_label, startWindowIcon: $media:startIcon, startWindowBackground: $color:start_window_background, exported: true, skills: [ { entities: [entity.system.home], actions: [ohos.want.action.home] } ] } ] } }五、实现示例示例 1页面级防截屏整个页面禁止截屏适用于银行App主页面、密码管理页面等需要全程保护的场景。// pages/PrivacyPage.etsimport{window}fromkit.ArkUI;import{common}fromkit.AbilityKit;import{BusinessError}fromkit.BasicServicesKit;import{hilog}fromkit.PerformanceAnalysisKit;constDOMAIN0x0000;constTAGPrivacyPage;EntryComponentstruct PrivacyPage{aboutToAppear():void{this.setPrivacyMode(true);}aboutToDisappear():void{this.setPrivacyMode(false);}setPrivacyMode(enable:boolean):void{letcontextthis.getUIContext().getHostContext()ascommon.UIAbilityContext;window.getLastWindow(context).then((lastWindow:window.Window){lastWindow.setWindowPrivacyMode(enable,(err:BusinessError){if(errerr.code){hilog.error(DOMAIN,TAG,设置隐私模式失败: %{public}s,JSON.stringify(err));return;}hilog.info(DOMAIN,TAG,隐私模式已%{public}s,enable?开启:关闭);});}).catch((err:BusinessError){hilog.error(DOMAIN,TAG,获取窗口失败: %{public}s,JSON.stringify(err));});}build(){Column(){Text(此页面已开启防截屏保护).fontSize(20).fontWeight(FontWeight.Medium)Text(截屏操作将被系统拦截截取结果为黑色画面).fontSize(14).fontColor(#666666).margin({top:12})}.width(100%).height(100%).justifyContent(FlexAlign.Center).backgroundColor(#F5F5F5)}}示例 2组件级防截屏键盘弹出时开启收起时关闭适用于自定义安全键盘——仅在键盘显示期间禁止截屏键盘关闭后恢复正常。// components/SecurityKeyboard.etsimport{window}fromkit.ArkUI;import{common}fromkit.AbilityKit;import{BusinessError}fromkit.BasicServicesKit;import{hilog}fromkit.PerformanceAnalysisKit;constDOMAIN0x0000;constTAGSecurityKeyboard;Componentexportstruct SecurityKeyboard{StatekeyboardData:string[][1,2,3,4,5,6,7,8,9,0];aboutToAppear():void{// 键盘显示时开启防截屏this.togglePrivacyMode(true);}aboutToDisappear():void{// 键盘隐藏时关闭防截屏this.togglePrivacyMode(false);}togglePrivacyMode(enable:boolean):void{letcontextthis.getUIContext().getHostContext()ascommon.UIAbilityContext;window.getLastWindow(context).then((lastWindow:window.Window){lastWindow.setWindowPrivacyMode(enable,(err:BusinessError){if(errerr.code){hilog.error(DOMAIN,TAG,切换隐私模式失败: %{public}s,JSON.stringify(err));}});});}build(){Column(){Text(安全键盘).fontSize(14).fontColor(#999999).margin({bottom:8})Flex({wrap:FlexWrap.Wrap}){ForEach(this.keyboardData,(item:string){Button(item).width(80).height(48).margin(4).borderRadius(8).backgroundColor(#FFFFFF).onClick((){// 处理按键点击})},(item:string)item)}.padding(8)}.width(100%).backgroundColor(#E8E8E8)}}在页面中使用// pages/LoginPage.etsimport{SecurityKeyboard}from../components/SecurityKeyboard;EntryComponentstruct LoginPage{StateshowKeyboard:booleanfalse;build(){Column(){TextInput({placeholder:请输入密码}).type(InputType.Password).customKeyboard(this.keyboardBuilder(),{supportAvoidance:true}).width(90%).margin({top:40})}.width(100%).height(100%)}BuilderkeyboardBuilder(){SecurityKeyboard()}}示例 3Ability 全局防截屏应用级保护在EntryAbility的onWindowStageCreate中全局开启// entryability/EntryAbility.etsimport{UIAbility,AbilityConstant,Want}fromkit.AbilityKit;import{window}fromkit.ArkUI;import{BusinessError}fromkit.BasicServicesKit;import{hilog}fromkit.PerformanceAnalysisKit;exportdefaultclassEntryAbilityextendsUIAbility{onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{hilog.info(0x0000,EntryAbility,onCreate);}onWindowStageCreate(windowStage:window.WindowStage):void{windowStage.loadContent(pages/Index,(err){if(err.code){hilog.error(0x0000,EntryAbility,加载失败: %{public}s,JSON.stringify(err));return;}// 获取主窗口并全局开启防截屏letmainWindow:window.WindowwindowStage.getMainWindowSync();mainWindow.setWindowPrivacyMode(true,(err:BusinessError){if(errerr.code){hilog.error(0x0000,EntryAbility,设置防截屏失败: %{public}s,JSON.stringify(err));return;}hilog.info(0x0000,EntryAbility,全局防截屏已开启);});});}onForeground():void{}onBackground():void{}onDestroy():void{}onWindowStageDestroy():void{}}六、效果验证方法6.1 手动测试步骤编译运行应用进入开启了防截屏的页面使用系统截屏快捷键电源键 音量下键截屏打开相册查看截图确认截图中该应用窗口区域显示为黑色或空白关闭防截屏后再次截屏对比验证截图内容正常6.2 录屏测试开启系统录屏功能录制包含防截屏页面的操作过程回放录屏视频确认防截屏页面在视频中显示为黑色6.3 最近任务预览测试打开应用进入防截屏页面切换到最近任务列表确认该应用的预览卡片是否被模糊或遮挡七、注意事项7.1 权限要求必须在module.json5中声明ohos.permission.PRIVACY_WINDOW该权限为system_grant类型系统自动授权无需弹窗申请若未声明权限直接调用 API将抛出BusinessError7.2 生命周期管理场景建议页面级保护aboutToAppear开启aboutToDisappear关闭组件级保护如键盘组件onAppear开启onDisAppear关闭全局保护onWindowStageCreate开启onWindowStageDestroy关闭⚠️重要务必在离开页面/组件时关闭隐私模式否则整个应用将持续防截屏影响用户体验。7.3 异步处理setWindowPrivacyMode是异步操作存在执行延迟。若需要确保隐私模式生效后再渲染敏感内容可在回调中处理lastWindow.setWindowPrivacyMode(true,(err){if(!err||!err.code){// 隐私模式已生效可以显示敏感内容this.isPrivacyReadytrue;}});7.4 多窗口场景在多窗口/分屏模式下setWindowPrivacyMode仅对当前窗口生效不影响其他窗口。八、总结防截屏功能是保护应用隐私数据的重要手段实现步骤简洁明了声明权限module.json5中添加ohos.permission.PRIVACY_WINDOW获取窗口通过getLastWindow或getMainWindowSync获取 Window 实例切换模式调用setWindowPrivacyMode(true/false)开关隐私保护管理生命周期在合适的时机开启和关闭避免影响正常功能保护粒度适用场景实现位置全局级银行App全程保护EntryAbility页面级特定敏感页面Page aboutToAppear/Disappear组件级安全键盘、密码输入框Component onAppear/onDisAppear
