1. 场景介绍
在日常通勤、咖啡厅等公共场合使用手机时,屏幕内容很容易被旁人窥视。支付记录、聊天内容、隐私笔记等敏感信息一旦泄露,轻则尴尬,重则造成财产损失。
HarmonyOS 6.0 提供的**防窥保护(DlpAntiPeep)**能力,可以智能判断机主是否被旁人窥屏。当检测到被窥视时,应用可以自动拉起系统级蒙层遮盖窗口,有效保护用户隐私。
本文将带你一步步完成防窥保护的接入,适合刚接触 HarmonyOS 开发的入门同学。
前置条件
- HarmonyOS 6.0.0 Beta1 及以上系统
- DevEco Studio 6.0.0 Beta1 及以上
- 设备需开启人脸识别,并在「设置 > 隐私与安全 > 防窥保护」中开启开关
2. 业务流程
防窥保护的整体流程如下:
用户开启防窥开关 → 应用订阅窥视状态 → 检测到被窥视 → 拉起系统蒙层 → 窥视消失/页面退出 → 取消订阅
简单来说,应用只需要做三件事:判断是否支持 → 订阅状态变化 → 在合适时机拉起蒙层。
3. 开发步骤
3.1 核心 API 一览
| 接口 | 作用 |
|---|---|
canIUse('SystemCapability.Security.DlpAntiPeep') |
判断设备是否支持防窥保护 |
isDlpAntiPeepSwitchOn() |
检查当前应用防窥开关状态 |
requestAntiPeepOptions(context) |
拉起系统弹窗引导用户开启 |
on('dlpAntiPeep', callback) |
订阅窥视状态变化 |
setAntiPeepMaskLayer(windowId) |
拉起系统级窗口蒙层 |
off('dlpAntiPeep', callback) |
取消订阅 |
3.2 申请 ACL 权限(重要)
防窥保护需要 ohos.permission.DLP_GET_HIDE_STATUS 权限,这是一个 ACL 受限权限,不能仅在 module.json5 中声明。
操作步骤:
- 在
module.json5中声明权限:
"requestPermissions": [
{
"name": "ohos.permission.DLP_GET_HIDE_STATUS",
"reason": "$string:dlp_permission_reason"
}
]
- 在 AppGallery Connect 中为你的应用申请 ACL 权限授权。登录 AppGallery Connect,进入「证书、APP ID 与 Profile」→「ACL 权限」,勾选
ohos.permission.DLP_GET_HIDE_STATUS提交审核。


踩坑提示:ACL 权限和普通权限不同,仅声明是不够的,必须到 AGC 后台提交申请并通过审核才能生效。这是容易忽略的步骤。
3.3 判断设备是否支持
在调用防窥 API 之前,先用 canIUse 判断当前设备能力:
import { canIUse } from '@kit.AbilityKit';
if (!canIUse('SystemCapability.Security.DlpAntiPeep')) {
// 设备不支持,隐藏相关功能入口
console.info('当前设备不支持防窥保护');
return;
}
canIUse 返回 false 说明设备硬件或系统版本不满足要求,此时应隐藏防窥保护相关的设置入口,避免用户困惑。
3.4 完整实现代码
以下是阅读页面的完整实现。你也可以在设置页面中添加开关,让用户自主选择是否启用。
import { dlpAntiPeep } from '@kit.DeviceSecurityKit';
import { window } from '@kit.ArkUI';
import { common, canIUse } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct ReadPage {
@StorageLink('dlp_anti_peep_enabled') antiPeepEnabled: boolean = false;
private hasShownMask: boolean = false;
private statusCallback: Callback<dlpAntiPeep.DlpAntiPeepStatus> | null = null;
aboutToAppear(): void {
if (this.antiPeepEnabled) {
this.initAntiPeep();
}
}
aboutToDisappear(): void {
this.cleanupAntiPeep();
}
onPageShow(): void {
// 页面重新可见时重置蒙层标记,确保能正常响应下一次窥视
this.hasShownMask = false;
}
// 初始化防窥保护
private async initAntiPeep(): Promise<void> {
// 第0步:判断设备能力
if (!canIUse('SystemCapability.Security.DlpAntiPeep')) {
return;
}
try {
// 第1步:检查应用级开关
const isOpen = await dlpAntiPeep.isDlpAntiPeepSwitchOn();
if (isOpen) {
// 已开启,直接订阅
this.subscribe();
} else {
// 第2步:未开启,引导用户设置
const context = this.getUIContext()
.getHostContext() as common.UIAbilityContext;
const result = await dlpAntiPeep.requestAntiPeepOptions(context);
if (result === dlpAntiPeep.AntiPeepOptionsResult.SUCCESS ||
result === dlpAntiPeep.AntiPeepOptionsResult.ALREADY_ON) {
this.subscribe();
}
}
} catch (error) {
const err = error as BusinessError;
// 801 表示设备硬件规格不支持
if (err.code === 801) {
console.info('当前设备硬件不支持防窥保护');
} else {
console.error(`防窥初始化失败: ${err.message}`);
}
}
}
// 订阅窥视状态
private subscribe(): void {
this.statusCallback = (status: dlpAntiPeep.DlpAntiPeepStatus) => {
if (status === dlpAntiPeep.DlpAntiPeepStatus.HIDE
&& !this.hasShownMask) {
this.showMaskLayer();
}
};
dlpAntiPeep.on('dlpAntiPeep', this.statusCallback);
}
// 拉起系统蒙层
private async showMaskLayer(): Promise<void> {
try {
const context = this.getUIContext()
.getHostContext() as common.UIAbilityContext;
const windowClass = await window.getLastWindow(context);
const windowId = windowClass.getWindowProperties().id;
await dlpAntiPeep.setAntiPeepMaskLayer(windowId);
this.hasShownMask = true;
} catch (error) {
const err = error as BusinessError;
console.error(`拉起蒙层失败: ${err.message}`);
}
}
// 取消订阅
private cleanupAntiPeep(): void {
if (this.statusCallback) {
try {
dlpAntiPeep.off('dlpAntiPeep', this.statusCallback);
this.statusCallback = null;
} catch (error) {
console.error(`取消订阅失败: ${(error as BusinessError).message}`);
}
}
}
build() {
// 你的阅读页面 UI
Column() {
Text('阅读页面')
}
.width('100%')
.height('100%')
}
}
3.5 设置页面中的开关
你可以在设置页面提供一个开关,让用户控制是否启用防窥保护:
// 持久化存储开关状态
PersistentStorage.persistProp('dlp_anti_peep_enabled', false);
@Component
struct SettingsPage {
@StorageLink('dlp_anti_peep_enabled') antiPeepEnabled: boolean = false;
build() {
Column() {
Row() {
Text('防窥保护')
Toggle({ type: ToggleType.Switch, isOn: this.antiPeepEnabled })
.onChange((value: boolean) => {
this.antiPeepEnabled = value;
})
}
}
}
}
使用 @StorageLink + PersistentStorage.persistProp 组合,开关状态会自动持久化,各个页面都能实时响应变化。
4. 技术要点与常见坑点
坑点一:ACL 权限容易被忽略
ohos.permission.DLP_GET_HIDE_STATUS 是受限权限,仅声明不生效。必须在 AppGallery Connect 后台提交 ACL 申请。
如果遗漏这一步,调用 API 时会直接抛出权限错误,且错误信息可能不够直观,排查起来比较费时。
坑点二:设备能力判断要前置
部分 HarmonyOS 设备可能因硬件限制不支持防窥保护。调用 isDlpAntiPeepSwitchOn() 时如果返回错误码 801,就表示硬件不支持。建议在调用任何防窥 API 之前,先用 canIUse 做一次快速判断,并根据结果控制功能入口的显隐。
坑点三:生命周期管理要对称
防窥的订阅和取消订阅必须成对出现,否则会导致:
- 忘记取消订阅:页面销毁后仍收到回调,尝试操作已不存在的 UI 状态,可能引发异常
- 重复订阅:每次进入页面都重新订阅而不清理旧的,造成回调堆积
建议的对称模式:
aboutToAppear → on('dlpAntiPeep', callback)
aboutToDisappear → off('dlpAntiPeep', callback)
onPageShow → 重置蒙层标记
坑点四:蒙层拉起要防重入
窥视状态变化可能频繁触发(比如机主和旁人交替注视屏幕时),每次变化都会回调 HIDE 状态。如果不加控制,setAntiPeepMaskLayer 会被重复调用。用 hasShownMask 标记位可以避免这类问题。
5. 效果验证
完成接入后,建议按以下步骤验证:
- 确认开关状态:进入「设置 > 隐私与安全 > 防窥保护」,确认你的应用开关已打开
- 正常阅读场景:机主独自注视屏幕,不应触发蒙层
- 被窥视场景:旁人从侧面注视屏幕,系统应自动拉起蒙层遮盖窗口
- 蒙层恢复:窥视消失后,蒙层应消失,应用恢复正常显示

6. 总结
防窥保护是 HarmonyOS 6.0 提供的一项实用隐私能力,接入成本不高,但能显著提升用户在公共场合使用应用的安全感。接入过程的几个关键点:
| 关键步骤 | 注意事项 |
|---|---|
| ACL 权限申请 | 必须到 AGC 后台提交,仅声明无效 |
| 设备能力判断 | 用 canIUse 做前置检查,处理 801 错误码 |
| 生命周期管理 | on / off 成对使用,onPageShow 重置状态 |
| 蒙层防重入 | 用标记位避免频繁拉起蒙层 |






































苏公安网备 32011402010933号