react-native-capture-protection

本项目基于 react-native-capture-protection开发。如果在使用过程中有任何问题，欢迎在AtomGit提交Issue，会及时跟进。

项目介绍

@hxa-rn/react-native-capture-protection 是 react-native-capture-protection 的 React Native 鸿蒙（OpenHarmony）适配包，提供防截屏、防录屏、防应用切换预览及截屏检测事件能力。当前版本：2.4.5。

集成指南

npm install @hxa-rn/react-native-capture-protection

本包 harmony.alias 为 react-native-capture-protection：业务代码请从 'react-native-capture-protection' 导入，不要写 '@hxa-rn/react-native-capture-protection'。

peerDependencies：react-native >= 0.72。

如使用版本支持 Autolink 且工程已接入，可跳过手动配置。

{
  "overrides": {
    "@rnoh/react-native-openharmony": "./react_native_openharmony"
  }
}

"dependencies": {
  "@hxa-rn/react-native-capture-protection": "file:../../node_modules/@hxa-rn/react-native-capture-protection/harmony/capture_protection.har"
}

set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")

add_subdirectory("${OH_MODULES}/@hxa-rn/react-native-capture-protection/src/main/cpp" ./capture_protection)

target_link_libraries(rnoh_app PUBLIC capture_protection)

#include "CaptureProtectionPackage.h"

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
        std::make_shared<CaptureProtectionPackage>(ctx),
    };
}

import { CaptureProtectionPackage } from '@hxa-rn/react-native-capture-protection/ts';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
    new CaptureProtectionPackage(ctx),
  ];
}

需在 module.json5 中声明 "ohos.permission.PRIVACY_WINDOW"。

使用说明

import {
  CaptureProtection,
  CaptureEventType,
} from 'react-native-capture-protection';
import type { EmitterSubscription } from 'react-native';

async function setupCaptureProtection() {
  // 开启全部捕获防护（防截屏 + 防录屏 + 防应用切换）
  await CaptureProtection.prevent();

  // 关闭全部捕获防护
  await CaptureProtection.allow();

  // 仅开启防截屏
  await CaptureProtection.prevent({ screenshot: true });

  // 查询防护状态
  const status = await CaptureProtection.protectionStatus();
  console.log(status); // { screenshot: boolean, record: boolean, appSwitcher: boolean }

  // 监听截屏 / 应用切换事件（用完后 removeListener 释放）
  const subscription: EmitterSubscription | undefined =
    CaptureProtection.addListener((eventType: CaptureEventType) => {
      if (eventType === CaptureEventType.CAPTURED) {
        console.log('检测到截屏');
      }
    });
  if (subscription) {
    await CaptureProtection.removeListener(subscription);
  }
}

平台差异：

• 鸿蒙隐私模式为窗口级统一开关：prevent() 一次开启防截屏/防录屏/防应用切换；allowScreenshot() / allowScreenRecord() 等细分 API 实际会关闭整个隐私模式。
• isScreenRecording() 鸿蒙无等价公开 API，恒返回 undefined。
• iOS 自定义文本/图片覆盖层（preventScreenRecordWithText 等）鸿蒙不支持自定义内容，仅开启隐私模式统一蒙层。

官方文档（窗口隐私模式）：

• API 参考：Window.setWindowPrivacyMode（无法截屏/录屏；多任务卡片隐私蒙层；需 ohos.permission.PRIVACY_WINDOW）
• 编码实践：应用安全编码实践
• 窗口 FAQ：窗口开发常见问题

鸿蒙无分项独立系统能力；prevent({screenshot|record|appSwitcher}) 均映射为 setWindowPrivacyMode(true)，protectionStatus() 三项同值。

接口文档

• 窗口级统一开关：通过 window.setWindowPrivacyMode(true/false)（API 9+，官方 API）统一控制截屏/录屏/应用切换防护。
• 事件监听：addListener 注册 window.on('screenshot') 与 window.on('windowEvent')，分别触发 CAPTURED 与 APP_SWITCHING；RECORDING / END_RECORDING 鸿蒙不发送。
• 保护状态：protectionStatus() 返回的三项同值（窗口级隐私模式布尔）。

快速验证（运行 Example）

前置条件

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/react-native-capture-protection.git
cd react-native-capture-protection
git checkout main

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/react-native-capture-protection@2.4.5，不再使用本地 file:../xxx.tgz，运行 Example 不必再执行 npm pack。

3. 进入 example 目录，安装依赖

cd example          # 或 example_auto
npm install --legacy-peer-deps

4. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

5. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio
• 选择 example/harmony（或 example_auto/harmony）目录
• 等待 Sync 完成

6. 编译并运行 HAP

在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备/模拟器。

注意：Example 中已预置插件依赖和 Package 注册，无需手动配置 Link。Example 已声明 ohos.permission.PRIVACY_WINDOW。

约束与限制

兼容性

• 鸿蒙 SDK：API 12+
• 上游 RN 库：react-native-capture-protection 2.4.1
• React Native / RNOH：0.72+
• DevEco Studio：5.0+

权限

• ohos.permission.PRIVACY_WINDOW（system_grant，声明即可，无需运行时申请）

其他

• 隐私模式开启后，最近任务卡片显示隐私蒙层，应用内容不可见（预期行为）

开源license

本项目基于 MIT 协议，详见 LICENSE 文件。

问题反馈渠道

使用问题请在 AtomGit 提交 Issue。也可在 GitCode 仓库反馈：

https://gitcode.com/hxa-rn/react-native-capture-protection

https://gitcode.com/hxa-rn/react-native-capture-protection/issues