更新记录

1.0.0（2026-09-02）

• 隐私屏幕保护 UTS 插件首个版本，支持 iOS / Android / HarmonyOS 三端，同一套 API：setup(options?) / show() / close() / onBackground(callback, event?) / destroy()
• iOS：实时模糊遮罩，进后台/切 App Switcher/失焦自动叠加，回前台移除；支持 blurRadius（模糊强度）与 autoEvent（触发时机）配置
• Android：系统级 FLAG_SECURE 快照保护（截屏/录屏/最近任务快照空白）
• HarmonyOS NEXT：窗口隐私模式（需 ohos.permission.PRIVACY_WINDOW 权限）
• 传统 uni-app（Vue3）与 uni-app x 双宿主兼容

平台兼容性

uni-app(4.87)

uni-app x(4.87)

w-privacy-mask 隐私屏幕保护 UTS 插件

App 退到后台 / 切多任务卡片 / 失焦时自动保护屏幕内容，快照、截图、录屏不再泄露敏感信息。支持 iOS / Android / HarmonyOS，三端同一套 API。

安装

1. 将 uni_modules/w-privacy-mask 目录复制到项目根目录 uni_modules/ 下；
2. 若已发布到 DCloud 插件市场，可直接在 HBuilderX 中通过插件市场导入。

使用

在 App.vue 的 onLaunch 中初始化一次即可：

import { PrivacyMask } from "@/uni_modules/w-privacy-mask"

export default {
  onLaunch() {
    PrivacyMask.setup()
  }
}

API

setup(options?: PrivacyMaskOptions): void

启用自动隐私保护。

• options.blurRadius?: number：iOS 模糊强度，默认 12，范围 0-30；Android / HarmonyOS 忽略。
• options.autoEvent?: PrivacyMaskBackgroundEvent：iOS 触发时机，'didEnterBackground'（默认）或 'willResignActive'；Android / HarmonyOS 忽略（系统级全程保护）。

show(): void

手动启用保护：

• iOS：立即叠加实时模糊遮罩
• Android / HarmonyOS：立即启用截屏/快照保护

close(): void

手动解除保护（供正常截图/录屏等场景）；用毕 show() 恢复。

onBackground(callback: () => void, event?: PrivacyMaskBackgroundEvent): void

• 注册进后台回调，callback 触发，重复调用替换上一次回调。
• event：'didEnterBackground'（默认，真正进后台）或 'willResignActive'（失焦）。iOS / Android 精确映射；HarmonyOS 为窗口隐藏 / 失焦（依 SDK 支持）。
• uts 端已配置 @UTSJS.keepAlive（iOS / Android），回调可重复触发。

destroy(): void

移除所有监听、解除保护、清回调，彻底清理；未 setup 时调用安全无副作用。

平台差异

Android / HarmonyOS 保护期间无法截图/录屏属预期行为，需正常截图时先 close()，用毕 show()。

使用示例

import { PrivacyMask } from "@/uni_modules/w-privacy-mask"

// 自动保护 + 进后台回调
PrivacyMask.setup()
PrivacyMask.onBackground(() => {
  console.log('App 进入后台，可在此执行业务处理')
})

// 手动控制（如敏感操作前主动保护 / 结束后恢复）
PrivacyMask.show()
PrivacyMask.close()

说明

• 不使用任何系统权限与 SDK（HarmonyOS 端需系统隐私窗口权限 ohos.permission.PRIVACY_WINDOW，插件 module.json5 已配置，应用主工程建议同步声明）。
• iOS：基于 App 失焦在 keyWindow 顶层叠加实时模糊遮罩，回前台自动移除。
• Android：系统级 FLAG_SECURE 全程保持，切后台最近任务快照空白/纯色。
• HarmonyOS：窗口隐私模式，setup 后全程保护，回前台自动重设（防御部分系统切换后失效）。

HarmonyOS 权限配置（如需应用主工程声明）

// module.json5 的 module.requestPermissions 中追加
{
  "name": "ohos.permission.PRIVACY_WINDOW",
  "reason": "$string:privacy_window_reason",
  "usedScene": { "when": "inuse" }
}