更新记录

1.0.0（2026-09-22）

AIGC: ContentProducer: '001191110102MAD55U9H0F10002' ContentPropagator: '001191110102MAD55U9H0F10002' Label: '1' ProduceID: '6be1c858-7562-4c3f-afce-abb7b8c3e2e1' PropagateID: '6be1c858-7562-4c3f-afce-abb7b8c3e2e1' ReservedCode1: '6cdb5456-8435-4550-8af4-e5efe0a0de5d' ReservedCode2: '6cdb5456-8435-4550-8af4-e5efe0a0de5d'

cc-screen-protection 使用说明

插件简介

cc-screen-protection 是一个 HarmonyOS 防截屏/防录屏 UTS 插件，通过调用 HarmonyOS 原生 window.setWindowPrivacyMode() API，为应用窗口启用隐私模式，使截屏和录屏时显示黑屏，保护敏感页面内容。

平台支持

环境要求

• HBuilderX 4.24.0+
• HarmonyOS SDK 6.0.0(20)+
• Vue 3 项目

安装方式

将 cc-screen-protection 目录复制到项目的 uni_modules/ 目录下即可。

API 文档

类型定义

interface ScreenProtectionResult {
  supported: boolean       // 当前平台是否支持
  eventSupported: boolean  // 是否支持截屏事件监听
  message: string          // 结果说明
}

方法

enableScreenProtection(): Promise<ScreenProtectionResult>

启用防截屏。调用后会向系统申请 PRIVACY_WINDOW 权限，并将当前窗口设为隐私模式。

disableScreenProtection(): Promise<ScreenProtectionResult>

关闭防截屏。关闭隐私模式并释放截屏事件监听器。

onScreenCaptureAttempt(callback: () => void): ScreenProtectionResult

注册截屏事件回调。当检测到用户截屏时，会触发传入的 callback。

offScreenCaptureAttempt(): ScreenProtectionResult

取消截屏事件监听，清空回调。

使用示例

基本用法

// #ifdef APP-HARMONY
import {
  initializeScreenProtection,
  disableScreenProtection
} from '@/uni_modules/cc-screen-protection/utssdk/app-harmony/util/screenProtectionHarmony.js'
// #endif

// 启用防截屏 + 注册截屏回调
// #ifdef APP-HARMONY
const result = await initializeScreenProtection(() => {
  console.log('检测到截屏！')
  uni.showToast({ title: '检测到截屏尝试', icon: 'none' })
})
// #endif

// 关闭防截屏
// #ifdef APP-HARMONY
await disableScreenProtection()
// #endif

在 App.vue 中初始化

// App.vue
<script>
// #ifdef APP-HARMONY
import {
  initializeHarmonyScreenProtectionModule,
  SCREEN_PROTECTION_ENABLED
} from '@/uni_modules/cc-screen-protection/utssdk/app-harmony/util/screenProtectionHarmony.js'
// #endif

export default {
  onLaunch() {
    // #ifdef APP-HARMONY
    if (SCREEN_PROTECTION_ENABLED) {
      initializeHarmonyScreenProtectionModule(() => {
        console.log('检测到截屏')
      })
    }
    // #endif
  }
}
</script>

权限配置

插件会自动申请 ohos.permission.PRIVACY_WINDOW 权限，无需手动在 module.json5 中声明。

注意事项

1. 仅支持鸿蒙真机：模拟器环境可能不支持隐私窗口模式，请在真机上测试。
2. 权限申请：首次启用时会弹出权限申请弹窗，用户拒绝后无法启用防截屏。
3. 全局生效：防截屏是窗口级别的，启用后整个窗口的截屏/录屏都会显示黑屏。
4. 安卓端替代方案：安卓端请使用 DCloud 官方 uni-usercapturescreen 插件，通过 uni.setUserCaptureScreen({ enable: false }) 实现。
5. 截屏监听：onScreenCaptureAttempt 需要在 enableScreenProtection 之后调用才能生效。

Demo 工程

本目录为完整的 HBuilderX uni-app Vue3 工程，可直接用 HBuilderX 打开运行。

运行步骤

1. 用 HBuilderX 打开本目录
2. 点击「运行」→「运行到手机或模拟器」→ 选择鸿蒙设备
3. 在 demo 页面中点击「启用防截屏」按钮测试

目录结构

cc-screen-protection-demo/
├── App.vue                  # 应用入口
├── main.js                  # Vue3 初始化
├── manifest.json            # 应用配置
├── pages.json               # 页面路由
├── pages/
│   └── index/
│       └── index.vue         # Demo 演示页面
├── static/                  # 静态资源
├── utils/                   # 工具类
└── uni_modules/
    └── cc-screen-protection/  # 插件源码
        ├── package.json
        ├── index.js           # JS 桩文件（H5 编译用）
        ├── index.d.ts         # TypeScript 类型声明
        └── utssdk/
            ├── interface.uts  # 接口定义
            ├── app-harmony/   # 鸿蒙原生实现
            │   ├── index.uts
            │   └── util/
            │       └── screenProtectionHarmony.js  # JS 封装层
            └── app-android/   # 安卓桩（已废弃）
                └── index.uts

平台兼容性

uni-app(5.24)

其他