更新记录

1.0.0（2026-05-26）

• feat: Android / iOS / HarmonyOS 防截屏防录屏（key 叠加）
• feat: Android / iOS 截图监听；HarmonyOS 暂不支持
• feat: Android / iOS 录屏状态回调（Android 尽力检测）
• feat: iOS App Switcher 模糊保护
• feat: resetAllSecure、截图权限检测与跳转设置 API
• docs: readme 补充 key 叠加机制说明
• refactor: 插件 id 重命名为 ly028-NScreenshot（≤20 字符）

平台兼容性

uni-app(3.7.7)

uni-app x(4.0)

ly028-NScreenshot

UTS 防截屏防录屏插件，支持 Android / iOS / HarmonyOS。

平台能力

快速开始

1. 导入 uni_modules/ly028-NScreenshot
2. 制作自定义调试基座（必须）
3. 业务代码：

import { enableSecure, disableSecure } from '@/uni_modules/ly028-NScreenshot'

enableSecure({ key: 'pay-page' })
// ...
disableSecure({ key: 'pay-page' })

API

防截屏 / 防录屏

key 叠加机制（重要）

enableSecure / disableSecure 的可选参数 key，用于多处同时开启防截屏、互不误关。

作用

插件内部用 Map<key, 引用次数> 管理保护状态：

• enableSecure({ key: 'xxx' }) → 该 key 计数 +1
• disableSecure({ key: 'xxx' }) → 该 key 计数 -1，减到 0 时移除
• 仅当所有 key 都关闭，才会真正解除系统级防截屏/防录屏（如 Android FLAG_SECURE）

不传 key 时，默认使用 default。

典型场景

这样 A 页面 onHide 关闭自己的 key 时，若 B 页面仍持有 key，不会误关 B 页面的保护。

key 命名

可自定义，只要是字符串且 enable/disable 成对使用即可，例如 'pay-page'、'order-detail'、'secure-page'。

建议：

1. 语义化：见名知意，表示哪个页面/模块
2. 成对使用：同一处 enable/disable 必须用同一 key
3. 避免冲突：不同页面/模块使用不同 key
4. 集中管理：复杂项目可将 key 定义为常量，避免拼写不一致

查询状态

注意事项

1. 同一 key 多次 enable 需对应多次 disable

enableSecure({ key: 'pay-page' })
enableSecure({ key: 'pay-page' })  // 计数 = 2

disableSecure({ key: 'pay-page' })  // 计数 = 1，保护仍在
disableSecure({ key: 'pay-page' })  // 计数 = 0，才真正关闭

一般每个页面在 onShow enable 一次、onHide disable 一次即可，避免重复调用。

2. 一键清除所有 key

import { resetAllSecure } from '@/uni_modules/ly028-NScreenshot'

resetAllSecure()

页面级示例

import { enableSecure, disableSecure } from '@/uni_modules/ly028-NScreenshot'

const PAGE_KEY = 'pay-page'

export default {
  onShow() {
    enableSecure({ key: PAGE_KEY })
  },
  onHide() {
    disableSecure({ key: PAGE_KEY })
  }
}

截图监听

HBuilderX 4.25+ 请使用 onScreenshot 命名以支持持续回调。

录屏状态

iOS 多任务保护

调试

日志前缀：[ly028-NScreenshot]

截图 / 录屏监听（Android 注意）

正确测试顺序：

1. 关闭所有防截屏 key
2. 点「开始截图监听」→ 授予权限 → 用系统按键截屏
3. 点「开始录屏监听」→ 确认日志出现 captured=false → 再开系统录屏测试

权限

• Android 禁止截屏/录屏：无额外权限
• Android 截图监听：按宿主 targetSdkVersion 选择权限——targetSdk ≥ 33 用 READ_MEDIA_IMAGES（需在 manifest.json 声明）；targetSdk ≤ 32 用 READ_EXTERNAL_STORAGE（插件 manifest 已声明）
• iOS / HarmonyOS 禁止能力：无额外权限；HarmonyOS 插件 module.json5 已声明 ohos.permission.PRIVACY_WINDOW

targetSdk ≥ 33 且需要截图监听时，请在宿主 manifest.json → App 权限配置 中添加 READ_MEDIA_IMAGES。无权限时不应开启截图监听，需引导用户到系统设置授权。

iOS 限制 FAQ

• 苹果无官方「禁止截图」API；插件使用 secure layer 使截图内容变黑
• 物理拍照、部分辅助功能场景无法完全拦截
• 录屏时插件可展示全屏遮罩

HarmonyOS 说明

• 使用 setWindowPrivacyMode 系统级拦截截屏/录屏
• 截图监听暂无稳定公开 API
• 请在真机验证（模拟器可能无法体现效果）

本地调试

HBuilderX 打开 ly028-NScreenshot → 自定义基座 → 真机运行。

修改 utssdk/**/*.uts 后需重新制作自定义基座。