文档开发者中心
我的

#码上创新# HarmonyOS 防窥保护开发实战:为你的应用加上“防偷看”能力

浏览150发布于2026-05-19 15:46广东
本文章最后由 Loki 于 2026-05-19 15:55 编辑

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 中声明。

操作步骤:

  1. 在 module.json5 中声明权限:
收起
自动换行
深色代码主题
复制
"requestPermissions": [
  {
    "name": "ohos.permission.DLP_GET_HIDE_STATUS",
    "reason": "$string:dlp_permission_reason"
  }
]
  1. 在 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. 效果验证

完成接入后,建议按以下步骤验证:

  1. 确认开关状态:进入「设置 > 隐私与安全 > 防窥保护」,确认你的应用开关已打开
  2. 正常阅读场景:机主独自注视屏幕,不应触发蒙层
  3. 被窥视场景:旁人从侧面注视屏幕,系统应自动拉起蒙层遮盖窗口
  4. 蒙层恢复:窥视消失后,蒙层应消失,应用恢复正常显示

6. 总结

防窥保护是 HarmonyOS 6.0 提供的一项实用隐私能力,接入成本不高,但能显著提升用户在公共场合使用应用的安全感。接入过程的几个关键点:

关键步骤 注意事项
ACL 权限申请 必须到 AGC 后台提交,仅声明无效
设备能力判断 用 canIUse 做前置检查,处理 801 错误码
生命周期管理 on / off 成对使用,onPageShow 重置状态
蒙层防重入 用标记位避免频繁拉起蒙层
收藏
1
回复
1
分享
全部评论
authorIcon
投资堂
赞
回复于2026-05-20 01:14浙江
写评论
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。
发表
我要写文章
目录 收起
1. 场景介绍
2. 业务流程
3. 开发步骤
3.1 核心 API 一览
3.2 申请 ACL 权限(重要)
3.3 判断设备是否支持
3.4 完整实现代码
3.5 设置页面中的开关
4. 技术要点与常见坑点
坑点一:ACL 权限容易被忽略
坑点二:设备能力判断要前置
坑点三:生命周期管理要对称
坑点四:蒙层拉起要防重入
5. 效果验证
6. 总结
了解社区公约,与您携手共创和谐专业的开发者社区。