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

v2.4.1-beta.1

Published

2 days ago

🛡️ Prevent and detect screen capture, screenshots and app switcher on HarmonyOS (React Native for OpenHarmony adaptation)

0High
0Medium
0Low

react-native harmony harmonyos

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

项目介绍

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

| 鸿蒙适配包版本 | 原始库版本 | 支持 RN 版本 | Autolink | 编译 API 版本 | | ------------ | ---------- | ------------ | -------- | ------------- | | 2.4.1-beta.1 | react-native-capture-protection 2.4.1 | 0.72+ | 是 | API 12+ |

集成指南

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 且工程已接入，可跳过手动配置。

说明：本模块需要同时在 C++ 侧和 ETS 侧注册 Package。

1. Overrides RN SDK

在工程根目录 oh-package.json5 添加：

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

2. 引入原生端依赖

打开 entry/oh-package.json5，添加：

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

执行 ohpm install。

3. 配置 CMakeLists

打开 entry/src/main/cpp/CMakeLists.txt，添加：

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)

4. 注册 Package（C++ 侧）

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "CaptureProtectionPackage.h"

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

5. 注册 Package（ETS 侧）

打开 entry/src/main/ets/RNPackagesFactory.ets，添加：

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() 三项同值。

接口文档

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | allow | 允许捕获（关闭隐私模式；无参=全部） | option? | Promise<void> | ✅ 完全支持 | | prevent | 防止捕获（开启隐私模式；无参=全部） | option? | Promise<void> | ✅ 完全支持 | | allowScreenshot | 允许截屏 | 无 | Promise<void> | ⚠️ 部分支持（窗口级统一开关） | | preventScreenshot | 防止截屏 | 无 | Promise<void> | ✅ 完全支持 | | allowScreenRecord | 允许录屏 | 无 | Promise<void> | ⚠️ 部分支持（窗口级统一开关） | | preventScreenRecord | 防止录屏 | 无 | Promise<void> | ✅ 完全支持 | | allowAppSwitcher | 允许应用切换预览 | 无 | Promise<void> | ⚠️ 部分支持（窗口级统一开关） | | preventAppSwitcher | 防止应用切换预览 | 无 | Promise<void> | ✅ 完全支持 | | preventScreenRecordWithText | 防止录屏（自定义文本覆盖层） | text, textColor?, backgroundColor? | Promise<void> | ⚠️ 部分支持（忽略自定义内容，仅隐私模式） | | preventScreenRecordWithImage | 防止录屏（自定义图片覆盖层） | image, backgroundColor?, contentMode? | Promise<void> | ⚠️ 部分支持（忽略自定义内容，仅隐私模式） | | preventAppSwitcherWithText | 防止应用切换（自定义文本覆盖层） | text, textColor?, backgroundColor? | Promise<void> | ⚠️ 部分支持（忽略自定义内容，仅隐私模式） | | preventAppSwitcherWithImage | 防止应用切换（自定义图片覆盖层） | image, backgroundColor?, contentMode? | Promise<void> | ⚠️ 部分支持（忽略自定义内容，仅隐私模式） | | protectionStatus | 查询保护状态 | 无 | Promise<{ screenshot, record, appSwitcher }> | ✅ 完全支持 | | hasListener | 查询事件监听状态 | 无 | Promise<boolean> | ✅ 完全支持 | | isScreenRecording | 查询是否录屏中 | 无 | Promise<boolean \| undefined> | ⚠️ 返回值差异（恒返回 undefined） | | requestPermission | 请求权限 | 无 | Promise<boolean> | ✅ 完全支持 | | addListener | 注册捕获事件监听 | callback | EmitterSubscription \| undefined | ✅ 完全支持 | | removeListener | 移除事件监听 | emitter | void（实现为同步 remove） | ✅ 完全支持 |

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

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | |------|----------| | Node.js | >= 18 | | DevEco Studio | 5.0+ | | HarmonyOS SDK | API 12+ |

运行步骤

1. 克隆仓库

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

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/[email protected]，不再使用本地 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