更新记录

1.0.0（2026-10-03）

录屏/截图 监听和禁用

平台兼容性

uni-app(5.26)

uni-app x(5.26)

其他

yao-prevent-media

UTS 插件：监听系统截屏、录屏、投屏事件并回调，同时支持禁止截屏/录屏（画面黑屏保护）。

支持平台：Android / iOS / HarmonyOS（鸿蒙）

iOS 平台限制：iOS 系统不提供禁止截屏/录屏的 API，prevent 参数在 iOS 上无效，截屏/录屏不会黑屏。iOS 端只能通过监听回调自行处理页面（如收到事件后立即显示遮罩、隐藏敏感内容、停止播放等），见下方 iOS 端通过回调保护页面示例。

快速上手

import * as media from '@/uni_modules/yao-prevent-media'

// 仅监听：截屏、录屏时收到回调
media.onMediaCapture({ prevent: false }, (res) => {
    console.log('事件类型：', res.type)
    console.log('文件路径：', res.path)
})

// 监听并禁止：截屏/录屏时画面黑屏（Android、鸿蒙生效）
media.onMediaCapture({ prevent: true }, (res) => {
    uni.showToast({ title: '检测到 ' + res.type, icon: 'none' })
})

// 页面卸载或不再需要时，停止监听并解除禁止
media.offMediaCapture(null)

iOS 端通过回调保护页面示例

iOS 无法阻止截屏/录屏，正确做法是在回调里控制页面状态：收到 screenrecord（录屏开始，即时回调）时立即显示遮罩盖住敏感内容，收到 screenrecord_end 时再移除。

<template>
    <view>
        <!-- 敏感内容 -->
        <view class="sensitive">账户余额：******</view>

        <!-- iOS 保护遮罩：录屏期间盖住敏感内容 -->
        <view v-if="maskVisible" class="mask">
            <text>为保护您的隐私，已暂停展示内容</text>
        </view>
    </view>
</template>

<script>
    import * as media from '@/uni_modules/yao-prevent-media'

    export default {
        data() {
            return {
                maskVisible: false
            }
        },
        onLoad() {
            // iOS 上 prevent 传 false 即可（传 true 也会被忽略）
            media.onMediaCapture({ prevent: false }, (res) => {
                if (res.type === 'screenrecord') {
                    // 录屏/投屏开始：即时回调，来得及遮住内容
                    this.maskVisible = true
                } else if (res.type === 'screenrecord_end') {
                    // 录屏/投屏结束：移除遮罩
                    this.maskVisible = false
                } else if (res.type === 'screenshot') {
                    // 注意：截屏回调是"事后"触发的，截图已经生成
                    // 这里只能做记录、提示或风控上报，无法阻止本次截图
                    this.maskVisible = true
                    setTimeout(() => {
                        this.maskVisible = false
                    }, 1500)
                }
            })
        },
        onUnload() {
            media.offMediaCapture(null)
        }
    }
</script>

完整页面示例：

<template>
    <view class="content">
        <button class="btn" type="primary" @click="startListen(false)">开启截屏/录屏监听</button>
        <button class="btn" type="warn" @click="startListen(true)">监听并禁止截屏录屏（安卓/鸿蒙）</button>
        <button class="btn" @click="stopListen">停止监听</button>
        <view class="log-list">
            <view v-for="(item, index) in logs" :key="index" class="log-item">
                <text class="log-text">{{ item }}</text>
            </view>
        </view>
    </view>
</template>

<script>
    import * as media from '@/uni_modules/yao-prevent-media'

    export default {
        data() {
            return {
                logs: []
            }
        },
        onUnload() {
            media.offMediaCapture(null)
        },
        methods: {
            startListen(prevent) {
                media.onMediaCapture({ prevent: prevent }, (res) => {
                    this.logs.unshift(res.type + (res.path ? ' | ' + res.path : ''))
                })
            },
            stopListen() {
                media.offMediaCapture(null)
                this.logs = []
            }
        }
    }
</script>

API

onMediaCapture(options, callback)

开启截屏/录屏监听。重复调用会覆盖上一次的 callback 和 prevent 设置。

options 说明

callback 返回参数 MediaCaptureResult

事件类型（type）说明

offMediaCapture(callback)

停止监听，移除 callback，并解除禁止截屏/录屏（关闭隐私模式）。

平台差异

注意事项

1. 回调时机：Android 和 iOS 的截屏事件均由系统在截屏完成后发出，无法做到"事前拦截"，prevent 参数才是事前防护（直接黑屏，让截屏/录屏内容无效）。iOS、鸿蒙的录屏开始/结束事件为即时回调。
2. iOS 无法真正禁止截屏/录屏：系统不提供对应 API，prevent: true 在 iOS 上不会产生任何黑屏效果。iOS 端的正确用法是依赖回调自行处理页面：录屏开始（screenrecord，即时回调）时显示遮罩/隐藏敏感内容，录屏结束（screenrecord_end）时恢复；截屏（screenshot）回调为事后触发，只能做提示或风控记录，无法阻止已发生的截图。
3. Android 存储权限：Android 端通过监听公共目录文件变化实现，首次调用 onMediaCapture 会申请存储权限（Android 13+ 为照片/视频权限），拒绝后将无法收到截屏/录屏回调。权限需打包进基座，请使用自定义基座测试。
4. 鸿蒙 PRIVACY_WINDOW 权限：鸿蒙端 prevent: true 依赖 ohos.permission.PRIVACY_WINDOW 权限，插件已通过项目根目录 harmony-configs/entry/src/main/module.json5 声明。该权限为 system_basic 受控权限，调试证书可直接使用，正式上架需在 AppGallery Connect 申请 ACL 受限权限。
5. 鸿蒙依赖版本：鸿蒙端需 HBuilderX 4.31+。
6. 投屏：鸿蒙端隐私模式同时会阻止投屏（画面黑屏）；iOS、Android 无投屏拦截能力。
7. 建议在 onUnload / onUnmounted 中调用 offMediaCapture(null) 释放监听。