uni-app 截屏监听与防截屏 API 实战：onUserCaptureScreen / offUserCaptureScreen / setUserCaptureScreen 全平台实现解析-北京尧图网络

uni-app 截屏监听与防截屏 API 实战onUserCaptureScreen / offUserCaptureScreen / setUserCaptureScreen 全平台实现解析【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app本篇技术指南围绕 uni-appuni-app x的用户截屏事件监听与防截屏能力展开完整讲解uni.onUserCaptureScreen、uni.offUserCaptureScreen、uni.setUserCaptureScreen三个扩展 API 的兼容性、参数定义、调用示例并结合当前仓库中uni-usercapturescreen插件的 Android / iOS / HarmonyOS / 微信小程序源码剖析截屏监听与防截屏在系统底层的实现机制。读完本文你将能够在金融、隐私类 App 中独立实现截屏检测提示敏感页面防截屏的完整方案。说明docs/api/capturescreen.md是文档迁移入口其最新内容位于 capture-screen.md本文以该文档为骨架并引用仓库内插件源码 uni-usercapturescreen 与官方示例页 capture-screen.uvue 进行纵深印证。一、API 能力总览截屏相关 API 属于 uni-app 的ext api扩展 API需要下载并集成uni-usercapturescreen插件后方可使用插件本体位于 src/uni_modules/uni-usercapturescreen其 readme 对该插件定位为用户主动截屏事件监听。共包含三个接口| API | 能力 | 典型场景 | | :- | :- | :- | |uni.onUserCaptureScreen(callback)| 开启截屏监听 | 检测到用户截屏后弹出隐私提示 | |uni.offUserCaptureScreen(callback)| 关闭截屏监听 | 页面退出时释放监听 | |uni.setUserCaptureScreen(options)| 设置防截屏 | 敏感页面禁止截图如验证码、支付页 |其中截屏特指用户通过手机系统自带按键电源键音量键等触发的截屏行为而非代码内对视图的截图。若需要通过代码对某个 view 截图应使用 takeSnapshot 相关 API。二、uni.onUserCaptureScreen开启截屏监听2.1 函数签名与参数开启截屏监听当用户使用系统截屏按键截屏时触发回调。参数定义如下| 名称 | 类型 | 必填 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | callback | (res: OnUserCaptureScreenCallbackResult) void | 否 | Web: x |uni.onUserCaptureScreen/uni.offUserCaptureScreen回调函数定义 |回调结果对象OnUserCaptureScreenCallbackResult的属性值| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | path | string | 否 | Web: x | 截屏文件路径仅 Android 返回 |在插件类型定义 utssdk/interface.uts 中回调类型被声明为export type OnUserCaptureScreenCallbackResult { /** * 截屏文件路径仅Android返回 */ path ?: string } export type UserCaptureScreenCallback (res : OnUserCaptureScreenCallbackResult) void export type OnUserCaptureScreen (callback : UserCaptureScreenCallback | null) void2.2 兼容性| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | x | 4.11 | 3.9.0 | 4.11 | 4.61 |从 interface.uts 的uniPlatform注释可看到更细粒度的版本要求Android系统osVer 4.4.4uni-app xunixVer 3.9.0iOS系统osVer 12.0uni-app xunixVer 4.11HarmonyOS系统osVer 3.0uni-app xunixVer 4.61微信小程序宿主hostVer 1.4.0uni-app xunixVer 4.11Web 端不支持标记为 x其他小程序平台支付宝、百度、抖音、飞书、QQ、快手、京东当前亦不支持。2.3 Android 端实现原理文件系统监听Android 端实现位于 utssdk/app-android/index.uts核心是继承android.os.FileObserver的ScreenFileObserver对截屏图片目录做文件新增CREATE事件监听class ScreenFileObserver extends FileObserver { private screenFile : File; constructor(screenFileStr : string) { super(screenFileStr); this.screenFile new File(screenFileStr); } override onEvent(event : Int, path : string | null) : void { // 只监听文件新增事件 if (event FileObserver.CREATE) { if (path ! null) { const currentTime System.currentTimeMillis(); if ((currentTime - lastObserverTime) 1000) { // 本地截屏行为比上一次超过1000ms, 才认为是一个有效的时间 return; } lastObserverTime currentTime; const screenShotPath new File(this.screenFile, path).getPath(); const res : OnUserCaptureScreenCallbackResult { path: screenShotPath } listener?.(res); } } } }实现细节要点监听目录按厂商区分小米机型监听DCIM/Screenshots其他机型监听PICTURES/Screenshots见Build.MANUFACTURER.toLowerCase() xiaomi的分支判断防抖处理两次截屏事件间隔小于 1000ms 时直接丢弃避免同一次截屏触发重复回调权限申请首次调用时检查READ_EXTERNAL_STORAGE权限未授予则通过ActivityCompat.requestPermissions主动申请生命周期释放通过UTSAndroid.onAppActivityDestroy在 Activity 销毁时自动stopWatching防止监听泄漏回调结果Android 端回调中会携带path字段截屏文件完整路径这也是path属性仅 Android 返回的原因。2.4 iOS 端实现原理系统截屏通知iOS 端实现位于 utssdk/app-ios/index.uts通过注册系统通知UIApplication.userDidTakeScreenshotNotification监听截屏static listenCaptureScreen(callback : UserCaptureScreenCallback | null) { this.listener callback // target-action 回调方法需要通过 Selector(方法名) 构建 const method Selector(userDidTakeScreenshot) NotificationCenter.default.addObserver(this, selector method, name UIApplication.userDidTakeScreenshotNotification, object null) } objc static userDidTakeScreenshot() { const res: OnUserCaptureScreenCallbackResult {} this.listener?.(res) }iOS 系统在用户截屏后会广播userDidTakeScreenshotNotification插件以 target-action 方式订阅截屏发生时回调userDidTakeScreenshot()并触发开发者注册的 listener。注意 iOS 回调结果中不含 path。2.5 HarmonyOS 端实现原理captureStatusChange 事件HarmonyOS 端实现位于 utssdk/app-harmony/index.uts通过display.on(captureStatusChange)订阅系统截屏状态变更const onUserCaptureScreenCallbacks: Function[] [] const harmonyCaptureStatusChange: Callbackboolean (captureStatus: boolean) { if (captureStatus) { onUserCaptureScreenCallbacks.forEach(cb { typeof cb function cb() }) } } display.on(captureStatusChange, harmonyCaptureStatusChange)插件内部维护回调数组onUserCaptureScreenCallbacksonUserCaptureScreen负责 push、offUserCaptureScreen负责按引用移除indexOfsplice多个监听者互不覆盖。三、uni.offUserCaptureScreen关闭截屏监听3.1 函数签名与参数取消截屏事件监听参数与onUserCaptureScreen一致| 名称 | 类型 | 必填 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | callback | (res: OnUserCaptureScreenCallbackResult) void | 否 | Web: x |uni.onUserCaptureScreen/uni.offUserCaptureScreen回调函数定义 |最佳实践传入的 callback 必须与onUserCaptureScreen注册时是同一个函数引用否则无法正确移除尤其是 HarmonyOS 端依赖indexOf精确查找引用。3.2 各平台关闭逻辑Android直接停止 FileObserver 监听并置空引用见 app-android/index.uts 的offUserCaptureScreen同时会重置lastObserverTime防抖时间戳iOS移除 NotificationCenter 观察者并清空 listenerNotificationCenter.default.removeObserver(this)HarmonyOS从回调数组中按引用移除指定回调。四、uni.setUserCaptureScreen设置防截屏4.1 函数签名与参数设置防截屏控制用户能否截取当前应用页面内容| 名称 | 类型 | 必填 | 兼容性 | | :- | :- | :- | :-: | | options |SetUserCaptureScreenOptions| 是 | Web: x |options属性描述| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | enable | boolean | 是 | Web: x | true: 允许用户截屏false: 不允许用户截屏防止用户截屏到应用页面内容 | | success | (res: SetUserCaptureScreenSuccess) void | 否 | Web: x | 设置成功回调 | | fail | (res: IUniError) void | 否 | Web: x | 设置失败回调 | | complete | (res: any) void | 否 | Web: x | 完成回调成功、失败均执行 |其中IUniError的属性值错误对象详细规范见 err-spec.md| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | errCode | number | 是 | Web: x | 统一错误码 | | errSubject | string | 是 | Web: x | 统一错误主题模块名称 | | data | any | 否 | Web: x | 错误信息中包含的数据 | | cause | Error | 否 | | 源错误信息可以包含多个错误详见 SourceError | | errMsg | string | 是 | Web: x | 错误描述 |4.2 兼容性| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | x | 4.11 | 3.9.0 | 4.11 | 4.61 |注意 iOS 端setUserCaptureScreen对系统版本要求更高osVer 13.0见 interface.uts 的注释而on/offUserCaptureScreen在 iOS 12.0 起即可用。4.3 各平台防截屏实现原理AndroidFLAG_SECURE 窗口标志位在 app-android/index.uts 中通过切换窗口的FLAG_SECURE标志实现且必须运行在 UI 线程export const setUserCaptureScreen : SetUserCaptureScreen function (option : SetUserCaptureScreenOptions) { // 切换到UI线程 UTSAndroid.getUniActivity()?.runOnUiThread(new SetUserCaptureScreenRunnable(option.enable)); const res : SetUserCaptureScreenSuccess {} option.success?.(res); option.complete?.(res); } class SetUserCaptureScreenRunnable extends Runnable { override run() : void { if (this.enable) { UTSAndroid.getUniActivity()?.getWindow()?.clearFlags(WindowManager.LayoutParams.FLAG_SECURE); } else { UTSAndroid.getUniActivity()?.getWindow()?.addFlags(WindowManager.LayoutParams.FLAG_SECURE); } } }FLAG_SECURE是系统级防截屏机制设置后截屏画面为空白/黑屏同时禁止最近任务预览图显示应用内容。iOS安全输入视图UITextField secure 技巧iOS 端没有公开的防截屏 API插件采用了业界通用的借壳方案——利用UITextField.isSecureTextEntry true时系统自动创建的私有安全视图将其插入到窗口层级中包裹根视图从而让截屏画面变黑见 app-ios/index.uts 的createSecureView/onAntiScreenshot/offAntiScreenshot。同时注意iOS 的 uts 方法默认在子线程执行涉及 UI 操作统一通过DispatchQueue.main.async切回主线程。HarmonyOSPRIVACY_WINDOW 受限权限窗口隐私模式HarmonyOS 端通过ohos.permission.PRIVACY_WINDOW受限开放权限使用前需在应用配置中申请受限权限配合window.setWindowPrivacyMode(!options.enable)设置窗口隐私模式见 app-harmony/index.utsUTSHarmony.requestSystemPermission([ohos.permission.PRIVACY_WINDOW], (allRight: boolean, _grantedList: string[]) { if (allRight) { window.setWindowPrivacyMode(!options.enable, (err: BusinessError) { // 成功/失败分别回调 success / fail / complete }); } // ... });权限被拒绝permission denied时会走fail回调错误主题errSubject统一为uni-usercapturescreen。4.4 错误码定义防截屏相关错误码在 utssdk/unierror.uts 中统一定义错误主题为uni-usercapturescreen| 错误码 | 错误信息 | 触发条件 | | :- | :- | :- | | 12001 |setUserCaptureScreen:system not support| iOS 系统版本低于 13.0 | | 12010 |setUserCaptureScreen:system internal error| iOS 15.1 系统 bug 导致 |export const UniErrors : MapSetUserCaptureScreenErrorCode, string new Map([ [12001, setUserCaptureScreen:system not support], [12010, setUserCaptureScreen:system internal error], ]); export class SetUserCaptureScreenFailImpl extends UniError implements SetUserCaptureScreenFail { constructor(errCode : SetUserCaptureScreenErrorCode) { super(); this.errSubject UniErrorSubject; this.errCode errCode; this.errMsg UniErrors[errCode] ?? ; } }五、完整实战示例截屏监听防截屏组合页面以下是仓库官方示例 src/pages/API/capture-screen/capture-screen.uvue 的完整代码与 hello uni-app x 同步维护实现了允许截屏开关开启/关闭截屏监听的完整交互可在真机上直接体验该 API 不支持 Web请运行到 App 平台template view classuni-container page-head :titletitle/page-head view classuni-common-mt text classuni-title截屏状态{{ captureStatus }}/text boolean-data :defaultValueallowCapture title是否允许截屏 changetoggleCaptureScreen/boolean-data view classuni-btn button clickstartCaptureListener typeprimary classuni-common-mt开启截屏监听/button button clickstopCaptureListener classuni-common-mt关闭截屏监听/button /view /view /view /template script setup languts import { state, setAllowCapture } from /store/index.uts const title 截屏监听 const allowCapture ref(state.allowCapture) const captureStatus ref(未监听) let captureCallback: ((res: OnUserCaptureScreenCallbackResult) void) | null null; const toggleCaptureScreen (checked: boolean) { uni.setUserCaptureScreen({ enable: checked, success: (res: SetUserCaptureScreenSuccess) { allowCapture.value checked setAllowCapture(checked) console.log(设置截屏状态成功, res) }, fail: (err:IUniError) { console.log(设置截屏状态失败, err) } }) } const startCaptureListener () { captureCallback (res: OnUserCaptureScreenCallbackResult) { captureStatus.value 检测到截屏 console.log(检测到用户截屏,res) } uni.onUserCaptureScreen(captureCallback) captureStatus.value 正在监听 console.log(开始监听截屏) } const stopCaptureListener () { if (captureCallback ! null) { uni.offUserCaptureScreen(captureCallback) captureStatus.value 未监听 console.log(停止监听截屏) } } // 页面卸载时清理监听 onUnmounted(() { stopCaptureListener() }) /script示例中的关键编码规范回调引用复用captureCallback保存为模块级变量供 on / off 成对使用保证能精确解绑生命周期清理在onUnmounted中调用stopCaptureListener()避免页面销毁后监听器泄漏对应 Android 端 Activity 销毁自动释放的兜底逻辑状态驱动 UI通过ref维护captureStatus、allowCapture截屏检测到后立即更新界面提示。六、使用注意事项tips以下限制与坑位来自官方文档务必在方案设计阶段确认本文的截屏指手机自带截屏事件的监听和取消监听由用户操作手机按键触发。App 平台如需通过代码对 view 截屏另见 API takeSnapshotiOS 13.0 以下系统不支持该系列 API调用setUserCaptureScreen会返回错误12001: system not supportiOS 15.1 系统存在系统 bug在该系统上调用setUserCaptureScreen会返回错误12010: system internal errorAndroid 平台在某些页面暂不支持如图片选择等页面以及 App 原生插件内部的原生页面HarmonyOS 平台使用setUserCaptureScreen时需要添加受限开放权限ohos.permission.PRIVACY_WINDOW对应 app-harmony/index.uts 中的requestSystemPermission动态申请逻辑。七、延伸阅读仓库内相关资源| 资源 | 路径 | 说明 | | :- | :- | :- | | 官方 API 文档 | capture-screen.md | 本文内容的一手来源 | | 插件 README | uni-usercapturescreen/readme.md | 插件能力简介 | | 类型与兼容性定义 | uni-usercapturescreen/utssdk/interface.uts | 回调、选项类型及各平台版本要求 | | Android 实现 | uni-usercapturescreen/utssdk/app-android/index.uts | FileObserver 监听 FLAG_SECURE 防截屏 | | iOS 实现 | uni-usercapturescreen/utssdk/app-ios/index.uts | 系统截屏通知安全视图防截屏 | | HarmonyOS 实现 | uni-usercapturescreen/utssdk/app-harmony/index.uts | captureStatusChange 监听窗口隐私模式 | | 错误码定义 | uni-usercapturescreen/utssdk/unierror.uts | 12001 / 12010 错误映射 | | 官方示例页面 | src/pages/API/capture-screen/capture-screen.uvue | 可直接运行的完整示例 |综上uni.onUserCaptureScreen/uni.offUserCaptureScreen/uni.setUserCaptureScreen三个 API 覆盖了截屏检测与防截屏两大诉求监听侧在 Android 基于文件系统监听、在 iOS 基于系统截屏通知、在 HarmonyOS 基于captureStatusChange事件防截屏侧在 Android 依赖FLAG_SECURE、在 iOS 采用安全视图技巧、在 HarmonyOS 依赖PRIVACY_WINDOW受限权限与窗口隐私模式。理解这些平台差异后开发者即可在 uni-app 项目中按需集成为金融、隐私、版权类业务提供可靠的截屏防护能力。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

uni-app 截屏监听与防截屏 API 实战：onUserCaptureScreen / offUserCaptureScreen / setUserCaptureScreen 全平台实现解析

相关推荐

智能家居项目计划书：从架构选型到MQTT设计的工程决策指南

ANSYS APDL电磁-热耦合建模实战：从物理逻辑到收敛控制

Celery Next Steps 实战指南：从最小示例到任务编排、路由与远程控制

更多资讯

Qwen2.5-Turbo 调 API 报 401？TaoToken 通道这样排查

Unity模型导入避坑指南：3DMax单位设置与轴心调整全攻略

从224MB到4.7MB：Tauri+Vue跨平台桌面方案实战

论文AI率太高怎么降？亲测有效的AI智能降重工具推荐，降AI率不达标全额退款

Move Prover 框架的形式化验证：从 Move IR 到 IVL 的最弱前置条件、循环切割与端到端可靠性证明

PostHog 数据仓库 Iterable 数据源实战解析：API 盘点、分页安全与全量刷新设计

今日更新

校园网认证计费模式详解：AAA与代拨架构、原理及排障

Spring Boot+Vue垃圾分类毕设：分层、权限与排错实战

把 Cline 的 Base URL 改到 TaoToken 之后，DeepSeek 仍能修调试配置

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？