更新记录

1.0.5（2026-08-01）

• docs: 新增页面生命周期回调自动启用和释放截屏保护的示例

1.0.4（2026-08-01）

• chore: HarmonyOS 支持的最低 HBuilderX 版本提升至 ^4.61.0

1.0.3（2026-06-23）

• feat(harmony): 支持窗口隐私模式实现禁止/允许截屏录屏
• feat(harmony): 截图监听标记为不支持，返回安全的空订阅

平台兼容性

uni-app(4.87)

uni-app x(4.87)

hans-screen-capture

uni-app / uni-app x（UTS）插件：禁止截屏/录屏 + 截图监听（Android/iOS/Harmony）。

平台支持

• app-android：√（禁止截屏/录屏/最近任务预览）；截图监听为“尽力而为 + 权限 + 启发式”
• app-ios：√（secure layer 禁止截屏；录屏遮挡；App Switcher 保护；截图监听）
• app-harmony：√（窗口隐私模式；截图监听暂不支持）

安装

把本模块放在项目 uni_modules/hans-screen-capture/ 下即可。

API

1) 禁止/允许截屏（支持 key 叠加）

import { preventScreenCapture, allowScreenCapture } from '@/uni_modules/hans-screen-capture'

preventScreenCapture({
    key: 'demo',
    success: (res) => console.log('prevent ok', res),
    fail: (e) => console.error('prevent fail', e),
})

allowScreenCapture({
    key: 'demo',
    success: (res) => console.log('allow ok', res),
})

说明：

• 未传 key 使用内部默认 key；可多处调用叠加，任一 key 未释放则保持生效。

2) 页面生命周期回调自动防护

页面显示时禁止截屏，页面隐藏或卸载时使用相同的 key 释放防护。onHide 与 onUnload 可能连续触发，因此释放函数需要保持幂等。

uni-app x（.uvue）：

<script setup lang="uts">
import { allowScreenCapture, preventScreenCapture } from '@/uni_modules/hans-screen-capture'

const PAGE_PROTECTION_KEY = 'payment-page'
let pageProtectionEnabled = false

function enablePageProtection() {
    if (pageProtectionEnabled) return
    pageProtectionEnabled = true
    preventScreenCapture({
        key: PAGE_PROTECTION_KEY,
        success: (res) => console.log('截屏保护已启用', res),
        fail: (err) => console.error('启用截屏保护失败', err),
    })
}

function disablePageProtection() {
    if (!pageProtectionEnabled) return
    pageProtectionEnabled = false
    allowScreenCapture({
        key: PAGE_PROTECTION_KEY,
        success: (res) => console.log('截屏保护已释放', res),
        fail: (err) => console.error('释放截屏保护失败', err),
    })
}

onShow(() => {
    enablePageProtection()
})

onHide(() => {
    disablePageProtection()
})

onUnload(() => {
    disablePageProtection()
})
</script>

标准 uni-app（.vue）：

<script>
import { allowScreenCapture, preventScreenCapture } from '@/uni_modules/hans-screen-capture'

const PAGE_PROTECTION_KEY = 'payment-page'

export default {
    data() {
        return { pageProtectionEnabled: false }
    },
    onShow() {
        this.enablePageProtection()
    },
    onHide() {
        this.disablePageProtection()
    },
    onUnload() {
        this.disablePageProtection()
    },
    methods: {
        enablePageProtection() {
            if (this.pageProtectionEnabled) return
            this.pageProtectionEnabled = true
            preventScreenCapture({
                key: PAGE_PROTECTION_KEY,
                success: (res) => console.log('截屏保护已启用', res),
                fail: (err) => console.error('启用截屏保护失败', err),
            })
        },
        disablePageProtection() {
            if (!this.pageProtectionEnabled) return
            this.pageProtectionEnabled = false
            allowScreenCapture({
                key: PAGE_PROTECTION_KEY,
                success: (res) => console.log('截屏保护已释放', res),
                fail: (err) => console.error('释放截屏保护失败', err),
            })
        },
    },
}
</script>

3) 截图监听

import { onScreenshot } from '@/uni_modules/hans-screen-capture'

const sub = onScreenshot((event) => {
    console.log('onScreenshot', event)
})

// 取消监听
sub.remove()

说明：

• HBuilderX 4.25+（iOS 的 uni-app/uni-app x、Android 的 uni-app）默认会在回调触发一次后回收 callback；监听类 API 请使用 on* 形式以支持持续回调。
• HarmonyOS 端当前不提供系统级截图监听，onScreenshot() 会保持空订阅。

4) 权限（Android：截图监听用）

import { getPermissions, requestPermissions } from '@/uni_modules/hans-screen-capture'

getPermissions({
    success: (res) => console.log(res),
})

requestPermissions({
    success: (res) => console.log(res),
})

说明：

• Android：截图监听通常需要读取图片权限（API 33+ 为 READ_MEDIA_IMAGES，<=32 为 READ_EXTERNAL_STORAGE）。
• Android：禁止截屏/录屏本身不需要额外权限（FLAG_SECURE）。
• iOS：恒返回 granted。

5) App Switcher 保护（iOS）

import { enableAppSwitcherProtection, disableAppSwitcherProtection } from '@/uni_modules/hans-screen-capture'

enableAppSwitcherProtection({ blurIntensity: 0.5 })
disableAppSwitcherProtection()

6) 日志开关

import { setLogEnabled, isLogEnabled } from '@/uni_modules/hans-screen-capture'
// 默认开启；如需关闭：
setLogEnabled(false)
console.log('插件日志开关:', isLogEnabled())

说明：

• UTS 侧日志会以 [hans-screen-capture] 前缀输出到控制台。
• Android 原生日志 tag 为 hans-screen-capture（logcat）。
• HarmonyOS 端通过窗口隐私模式实现防截屏/录屏。

已知限制（Android 截图监听）

截图监听基于系统相册写入事件 + 关键字启发式判断，受 ROM/相册实现/权限策略影响，可能出现漏报或误报；建议在产品层面把它当作“提示性事件”，不要用于强安全依赖。