HarmonyOS 防窥保护（Anti-Peep Protection）入门指南：从系统安全到物理空间防护

前言

HarmonyOS 自发布以来持续深化安全与隐私能力体系建设：从早期的应用沙箱隔离、权限管控，到数据防泄漏（DLP）框架，再到如今面向物理环境的感知型安全防护能力，安全防护的边界已从系统内部延伸至用户所处的真实空间。

移动设备已深度融入日常生活——人们在地铁、咖啡厅、会议室等公共场所查看账户余额、阅读私密消息、浏览个人内容。屏幕上的信息可能暴露在陌生人的视线之下，“肩窥”（Shoulder Surfing）已成为现实生活中不可忽视的隐私威胁。正是在这一背景下，HarmonyOS 推出了 dlpAntiPeep（防窥保护） 能力——依托前置摄像头的实时感知，检测屏幕前是否存在非机主人员，并在检测到窥视时通知应用主动隐藏敏感信息或触发系统防窥蒙层。

本文作为防窥保护系列的第一篇，将从概念原理、窥视状态体系、API 全景、前置条件到基础代码实现，带你系统地理解这项物理空间安全防护能力。

一、防窥保护概念解析

1.1 什么是防窥保护

防窥保护（dlpAntiPeep）是 HarmonyOS Device Security Kit 提供的物理空间安全防护能力。它通过前置摄像头实时分析屏幕前的人员情况，智能判断是否存在非机主人员窥视屏幕，并将结果以标准 API 形式通知应用。

维度 说明
所属 Kit Device Security Kit（设备安全服务）
系统能力 SystemCapability.Security.DlpAntiPeep
起始版本 API 20（HarmonyOS 6.0.0 Beta1）
核心模块 @kit.DeviceSecurityKit
感知方式 前置摄像头实时人脸检测
处理位置 设备端完成，不泄露用户隐私

1.2 "感知 + 响应"分层设计

防窥保护采用"感知 + 响应"的分层设计架构：

在这里插入图片描述

图：防窥保护"感知 + 响应"分层架构——从摄像头感知到应用灵活响应

层级 职责 关键能力
感知层 前置摄像头实时检测屏幕前人员 人脸识别、机主判断、窥视检测
判断层 系统智能判断窥视状态 机主/非机主区分、环境光判断、距离判断
响应层 应用灵活决策保护策略 隐藏敏感字段、模糊画面、拉起蒙层、暂停推荐

关键设计：防窥保护并非对所有场景一刀切地拦截，而是让不同类型的应用都能以最贴合自身场景的方式接入。应用可以选择遮盖敏感字段、模糊画面、暂停播放，也可以直接拉起系统级防窥蒙层覆盖整个窗口。

二、窥视状态体系详解

2.1 机主判定机制

系统使用智能判断将长期通过人脸解锁手机的人认定为防窥保护的机主。这意味着：

  • 日常使用人脸解锁的用户自动被识别为机主
  • 重启手机后需进行一次人脸解锁以启用防窥保护
  • 删除人脸信息或关闭锁屏密码后，需重新设置防窥保护

2.2 DlpAntiPeepStatus 枚举

窥视状态通过 DlpAntiPeepStatus 枚举值表示：

枚举值 数值 含义 触发条件
PASS 0 非窥视状态 机主自身注视屏幕；无机主使用手机；机主分享场景
HIDE 1 被窥视状态 机主与非机主同时注视屏幕

2.3 三种典型判断场景

场景 屏幕前人员 返回状态 说明
机主独自使用 仅机主 PASS 正常显示，无保护
他人窥视 机主 + 非机主 HIDE 触发保护，隐藏敏感信息
机主主动分享 机主 + 他人 PASS 系统认为机主主动分享，不打扰
无机主使用 仅有非机主或无人 PASS 非机主使用场景，返回非窥视

重要提示：机主与非机主同时注视屏幕时才会返回 HIDE 状态。如果机主主动把手机递给他人看（分享场景），系统会判断为 PASS 状态，不会触发保护。这种智能判断机制避免了误打扰。

2.4 智能判断因素

防窥保护的识别准确率受以下因素影响：

判断因素 理想条件 可能导致误判的情况
人脸距离 在设备一定范围内 距离过近或过远
人脸遮挡 无遮挡 口罩、墨镜等遮挡
环境光线 充足光线 暗光、强光、逆光
人像类物品 无 人物海报等可能误触发

三、API 全景与接口体系

3.1 核心接口一览

防窥保护提供 7 个核心接口，覆盖从开关检测到状态监听、蒙层拉起、状态修改的完整链路：

接口名 类型 描述 起始版本
isDlpAntiPeepSwitchOn() 查询 检查当前应用是否开启防窥保护 API 20
on('dlpAntiPeep', callback) 订阅 订阅防窥保护状态通知 API 20
off('dlpAntiPeep', callback) 取消订阅 解除订阅防窥保护状态通知 API 20
getDlpAntiPeepInfo() 查询 获取当前应用的窥视状态 API 20
setAntiPeepMaskLayer(windowId) 操作 拉起系统级防窥蒙层 API 20
passDlpAntiPeepInfo() 操作 修改窥视状态为 PASS（直到锁屏或退出） API 20
requestAntiPeepOptions(context) 操作 拉起设置弹窗请求用户开启防窥保护 API 23
publishAntiPeepInformation() 操作 发布防窥保护提示信息（实况窗提醒） API 23

3.2 接口调用流程

标准的防窥保护接入流程如下：

  1. 能力检测：canIUse('SystemCapability.Security.DlpAntiPeep') 检测设备是否支持
  2. 开关检测：isDlpAntiPeepSwitchOn() 确认用户已开启开关
  3. 引导开启（可选）：requestAntiPeepOptions(context) 拉起设置弹窗
  4. 获取初始状态：getDlpAntiPeepInfo() 获取页面展示时的初始状态
  5. 注册监听：on('dlpAntiPeep', callback) 实时监听状态变化
  6. 响应处理：根据状态隐藏敏感信息或拉起蒙层
  7. 取消监听：off('dlpAntiPeep') 页面销毁时取消监听

3.3 权限要求

权限 类型 说明
ohos.permission.DLP_GET_HIDE_STATUS 受限权限（ACL） 调用防窥保护 API 的必要权限

权限申请说明：该权限为受限权限，如果应用需要上架使用防窥保护能力，需在 AGC 平台申请 ACL 权限。本地调试时，自动签名同意权限申请即可。

四、前置条件与环境准备

4.1 版本要求

组件 最低版本
HarmonyOS 系统 6.0.0 Beta1 及以上
DevEco Studio 6.0.0 Beta1 及以上
HarmonyOS SDK 6.0.0 Beta1 SDK 及以上
API 版本 API 20 及以上

4.2 设备要求

  1. 设备必须支持人脸识别功能
  2. 在"设置 > 隐私与安全 > 防窥保护"中能看到防窥保护选项
  3. 当前仅支持 Phone 设备
  4. 模拟器不支持防窥保护功能，需使用真机调试

4.3 用户侧前置操作

  1. 在"设置 > 生物识别和密码 > 人脸识别"中录入人脸
  2. 在"设置 > 隐私与安全 > 防窥保护"中开启防窥保护开关
  3. 通过人脸验证后，打开需要加入保护的应用开关

五、基础代码入门

5.1 模块导入与能力检测

import { dlpAntiPeep } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';

/**
 * 检测设备是否支持防窥保护能力
 */
export function canUseAntiPeep(): boolean {
  return canIUse('SystemCapability.Security.DlpAntiPeep');
}

5.2 开关状态检测

/**
 * 检查当前应用是否已开启防窥保护
 */
export async function isAntiPeepOn(): Promise<boolean> {
  try {
    if (canUseAntiPeep()) {
      const result: boolean = await dlpAntiPeep.isDlpAntiPeepSwitchOn();
      console.info(`防窥保护开关状态: ${result}`);
      return result;
    } else {
      console.warn('当前设备不支持防窥保护');
      return false;
    }
  } catch (err) {
    const error = err as BusinessError;
    console.error(`检查开关状态失败: ${error.code}, ${error.message}`);
    return false;
  }
}

5.3 获取初始窥视状态

/**
 * 同步获取当前窥视状态
 */
export function getAntiPeepInfo(): dlpAntiPeep.DlpAntiPeepStatus | number {
  try {
    if (canUseAntiPeep()) {
      const status = dlpAntiPeep.getDlpAntiPeepInfo();
      console.info(`当前窥视状态: ${JSON.stringify(status)}`);
      return status;
    } else {
      return -1; // 设备不支持
    }
  } catch (err) {
    console.error(`获取窥视状态失败: ${JSON.stringify(err)}`);
    return -1;
  }
}

5.4 注册与取消监听

/**
 * 防窥保护回调接口
 */
interface AntiPeepCallback {
  onStatusChanged: (status: dlpAntiPeep.DlpAntiPeepStatus) => Promise<void>;
}

/**
 * 注册防窥保护状态监听
 */
export function listenOnAntiPeepStatus(antiPeepCB: AntiPeepCallback): boolean {
  try {
    if (canUseAntiPeep()) {
      console.info('开始监听防窥保护状态');

      dlpAntiPeep.on('dlpAntiPeep', (status: dlpAntiPeep.DlpAntiPeepStatus) => {
        console.info(`防窥状态变化: ${JSON.stringify(status)}`);
        if (antiPeepCB) {
          antiPeepCB.onStatusChanged(status);
        }
      });

      console.info('防窥保护监听已注册');
      return true;
    } else {
      return false;
    }
  } catch (err) {
    const error = err as BusinessError;
    console.error(`注册监听失败: ${error.code}, ${error.message}`);
    return false;
  }
}

/**
 * 取消防窥保护状态监听
 */
export function listenOffAntiPeepStatus(): void {
  try {
    if (canUseAntiPeep()) {
      console.info('取消防窥保护监听');
      dlpAntiPeep.off('dlpAntiPeep');
      console.info('防窥保护监听已取消');
    }
  } catch (err) {
    const error = err as BusinessError;
    console.error(`取消监听失败: ${error.code}, ${error.message}`);
  }
}

5.5 拉起设置弹窗（API 23+）

/**
 * 拉起系统设置弹窗，引导用户开启防窥保护
 * 需要 API 23 及以上版本
 */
async function requestAntiPeepOptions(context: Context): Promise<void> {
  try {
    const result = await dlpAntiPeep.requestAntiPeepOptions(context);
    console.info(`防窥保护设置弹窗结果: ${JSON.stringify(result)}`);
  } catch (err) {
    const error = err as BusinessError;
    console.error(`拉起设置弹窗失败: ${error.code}, ${error.message}`);
  }
}

5.6 发布实况窗提醒（API 23+）

/**
 * 发布防窥保护实况窗提醒
 * 当设备持续处于窥屏风险状态时，系统只会主动发送一次时长5秒的提醒
 * 再次提醒需要通过本接口主动触发
 * 需要 API 23 及以上版本
 */
async function publishAntiPeepWarning(): Promise<void> {
  try {
    await dlpAntiPeep.publishAntiPeepInformation();
    console.info('防窥保护实况窗提醒已发布');
  } catch (err) {
    const error = err as BusinessError;
    console.error(`发布实况窗提醒失败: ${error.code}, ${error.message}`);
  }
}

六、防窥保护完整接入流程

6.1 标准接入流程

以下是防窥保护的完整接入流程，涵盖从能力检测到页面销毁的全生命周期：

import { dlpAntiPeep } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct AntiPeepPage {
  @State private isAntiPeepSupported: boolean = false;
  @State private isSwitchOn: boolean = false;
  @State private isPeeping: boolean = false;
  @State private sensitiveData: string = '¥12,345.67';
  @State private displayData: string = '¥12,345.67';

  private antiPeepCB: AntiPeepCallback = {
    onStatusChanged: async (status: dlpAntiPeep.DlpAntiPeepStatus) => {
      await this.handleAntiPeepStatus(status);
    }
  };

  aboutToAppear(): void {
    this.initializeAntiPeep();
  }

  aboutToDisappear(): void {
    // 页面销毁时必须取消监听
    listenOffAntiPeepStatus();
  }

  /**
   * 初始化防窥保护
   */
  private async initializeAntiPeep(): Promise<void> {
    // 1. 检测设备能力
    this.isAntiPeepSupported = canUseAntiPeep();
    if (!this.isAntiPeepSupported) {
      console.warn('当前设备不支持防窥保护');
      return;
    }

    // 2. 检查开关状态
    this.isSwitchOn = await isAntiPeepOn();
    if (!this.isSwitchOn) {
      console.warn('防窥保护开关未开启，可引导用户开启');
      // 可选：调用 requestAntiPeepOptions 引导用户
      return;
    }

    // 3. 获取初始状态
    const initialStatus = getAntiPeepInfo();
    if (typeof initialStatus === 'number' && initialStatus !== -1) {
      await this.handleAntiPeepStatus(initialStatus as dlpAntiPeep.DlpAntiPeepStatus);
    }

    // 4. 注册实时监听
    listenOnAntiPeepStatus(this.antiPeepCB);
  }

  /**
   * 处理防窥保护状态变化
   */
  private async handleAntiPeepStatus(status: dlpAntiPeep.DlpAntiPeepStatus): Promise<void> {
    switch (status) {
      case dlpAntiPeep.DlpAntiPeepStatus.PASS:
        // 非窥视状态：正常显示敏感信息
        this.isPeeping = false;
        this.displayData = this.sensitiveData;
        console.info('✅ 非窥视状态，正常显示');
        break;

      case dlpAntiPeep.DlpAntiPeepStatus.HIDE:
        // 被窥视状态：隐藏敏感信息
        this.isPeeping = true;
        this.displayData = '****';
        console.info('⚠️ 检测到窥视，隐藏敏感信息');
        break;

      default:
        // 未知状态：正常显示
        this.displayData = this.sensitiveData;
        break;
    }
  }

  build() {
    Column() {
      if (!this.isAntiPeepSupported) {
        Text('当前设备不支持防窥保护')
          .fontSize(14)
          .fontColor('#999')
      }

      Text(`账户余额: ${this.displayData}`)
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .fontColor(this.isPeeping ? '#CCC' : '#333')

      if (this.isPeeping) {
        Text('检测到他人窥视，敏感信息已隐藏')
          .fontSize(14)
          .fontColor('#FF3B30')
          .margin({ top: 8 })
      }
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .padding(20)
  }
}

七、错误码与异常处理

7.1 常见错误码

错误码 含义 处理方式
201 权限被拒绝 检查 ohos.permission.DLP_GET_HIDE_STATUS 是否已授权
801 设备能力不支持 使用 canIUse 前置检测，不支持时降级
1020600001 内部错误 重试或提示用户重启应用

7.2 异常处理最佳实践

/**
 * 安全调用防窥保护 API
 * 封装统一的异常处理逻辑
 */
export async function safeCallAntiPeepAPI<T>(
  apiName: string,
  apiCall: () => Promise<T>,
  fallback: T
): Promise<T> {
  if (!canUseAntiPeep()) {
    console.warn(`[${apiName}] 设备不支持防窥保护，使用降级值`);
    return fallback;
  }

  try {
    return await apiCall();
  } catch (err) {
    const error = err as BusinessError;
    console.error(`[${apiName}] 调用失败: ${error.code}, ${error.message}`);

    if (error.code === 801) {
      console.warn(`[${apiName}] 设备能力不支持`);
    } else if (error.code === 201) {
      console.warn(`[${apiName}] 权限被拒绝`);
    }

    return fallback;
  }
}

八、约束与限制

8.1 已知限制

限制项 说明
设备类型 当前仅支持 Phone 设备
API 版本 需 API 20 及以上
人脸识别 设备必须支持并开启人脸识别
环境要求 暗光、强光、逆光等环境下识别成功率下降
模拟器 模拟器不支持防窥保护功能
人像物品 人物海报等可能被误判为窥视者

8.2 开发注意事项

  1. 调用前必须检测能力：调用任何 dlpAntiPeep API 之前，必须先通过 canIUse('SystemCapability.Security.DlpAntiPeep') 检测设备能力，不支持时直接调用会抛出异常导致应用崩溃
  2. 必须取消监听：在页面组件的 aboutToDisappear() 生命周期中必须调用 dlpAntiPeep.off('dlpAntiPeep') 取消监听
  3. 蒙层触发控制：setAntiPeepMaskLayer() 每次进入页面只触发一次，需通过标志位 isSystemLayerTriggered 控制，避免重复触发
  4. 上架需 ACL 权限：如果应用上架需使用防窥保护能力，需在 AGC 平台申请 ACL 权限

九、已接入防窥保护的应用

目前已有超过 20 款主流应用接入防窥保护，覆盖金融、社交、办公、生活等多个领域：

应用 保护场景
京东金融 "我的"页面、理财页面、资产金额数字隐藏
中国农业银行 "财富"页面、"我的"页面
华夏银行 财富页面总资产、收益明细、账户页
邮储银行 "我的"资产、本月收支、账户页
平安证券 交易页面、"我的"资产
钉钉 聊天页面
携程旅行 订单页面
去哪儿旅行 订单页面
美柚 记录页面（经期/备孕/怀孕/育儿）
钱迹记账 所有页面（账单、资产）

十、总结

本文作为防窥保护系列入门篇，系统介绍了以下核心内容：

  • 概念原理：防窥保护是 Device Security Kit 提供的物理空间安全防护能力，通过前置摄像头实时感知，检测非机主窥视
  • 窥视状态体系：PASS（非窥视）和 HIDE（被窥视）两种状态，系统智能判断机主/非机主
  • API 全景：8 个核心接口，覆盖开关检测、状态监听、蒙层拉起、状态修改、设置弹窗、实况窗提醒
  • 前置条件：API 20+、仅支持 Phone、需人脸识别、需开启系统开关
  • 基础代码：能力检测、开关检测、状态获取、监听注册/取消、完整接入流程

防窥保护将安全防护从"系统内部"延伸到"用户物理空间"，是 HarmonyOS 安全体系的重要里程碑。

下一篇将深入讲解金融场景的完整接入实战，包括系统蒙层、实况窗提醒、权限管理等内容。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

# harmonyos # 系统安全 # 华为
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

归档、恢复还是删除？HarmonyOS 习惯数据生命周期设计

avatar HarmonyOS开发者社区
cover

用 Node 脚本做 HarmonyOS 发布前静态自检：把项目约束写成代码

avatar HarmonyOS开发者社区
cover

技术拆解与实战优化：国产化视频会议系统核心原理与落地策略

avatar HarmonyOS开发者社区