docs/api/capture-screen.md
开启截屏监听
本 API 是 uni ext api,需下载插件:uni-usercapturescreen
| Web | 微信小程序 | Android | iOS | HarmonyOS |
|---|---|---|---|---|
| <a style="color:unset;" href="https://vote.dcloud.net.cn/#/?name=uni-app%20x">x</a> | 4.11 | 3.9.0 | 4.11 | 4.61 |
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| callback | (res: OnUserCaptureScreenCallbackResult) => void | 否 | - | Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - |
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| path | string | 否 | - | Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 截屏文件路径(仅Android返回) |
关闭截屏监听
本 API 是 uni ext api,需下载插件:uni-usercapturescreen
| Web | 微信小程序 | Android | iOS | HarmonyOS |
|---|---|---|---|---|
| <a style="color:unset;" href="https://vote.dcloud.net.cn/#/?name=uni-app%20x">x</a> | 4.11 | 3.9.0 | 4.11 | 4.61 |
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| callback | (res: OnUserCaptureScreenCallbackResult) => void | 否 | - | Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - |
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| path | string | 否 | - | Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 截屏文件路径(仅Android返回) |
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| errMsg | string | 是 | - | Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: - | 错误信息 |
设置防截屏
本 API 是 uni ext api,需下载插件:uni-usercapturescreen
| Web | 微信小程序 | Android | iOS 系统版本 | iOS | HarmonyOS |
|---|---|---|---|---|---|
| <a style="color:unset;" href="https://vote.dcloud.net.cn/#/?name=uni-app%20x">x</a> | 4.11 | 3.9.0 | 13.0 | 4.11 | 4.61 |
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| options | SetUserCaptureScreenOptions | 是 | - | Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - |
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| enable | boolean | 是 | - | Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | true: 允许用户截屏 false: 不允许用户截屏,防止用户截屏到应用页面内容 |
| success | (res: SetUserCaptureScreenSuccess) => void | 否 | - | Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | uni.setUserCaptureScreen成功回调函数定义 |
| fail | (res: IUniError) => void | 否 | - | Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | uni.setUserCaptureScreen失败回调函数定义 |
| complete | (res: any) => void | 否 | - | Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | uni.setUserCaptureScreen完成回调函数定义 |
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| errCode | number | 是 | - | Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 统一错误码 |
| errSubject | string | 是 | - | Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 统一错误主题(模块)名称 |
| data | any | 否 | - | Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 错误信息中包含的数据 |
| cause | Error | 否 | - | Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 源错误信息,可以包含多个错误,详见SourceError |
| errMsg | string | 是 | - | Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - |
示例为hello uni-app x alpha分支,与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见
该 API 不支持 Web,请运行 hello uni-app x 到 App 平台体验
::: preview
appRedirect https://hellouniappx.dcloud.net.cn/appredirect.html?path=pages/API/capture-screen/capture-screen
<template>
<view class="uni-container">
<page-head :title="title"></page-head>
<view class="uni-common-mt">
<text class="uni-title">截屏状态:{{ captureStatus }}</text>
<view style="flex-direction: row;">
<text class="uni-title">是否允许截屏</text>
<switch :checked="allowCapture" @change="(e: UniSwitchChangeEvent) => toggleCaptureScreen(e.detail.value)" />
</view>
<view class="uni-btn">
<button @click="startCaptureListener" type="primary" class="uni-common-mt">开启截屏监听</button>
<button @click="stopCaptureListener" class="uni-common-mt">关闭截屏监听</button>
</view>
</view>
</view>
</template>
<script setup lang="uts">
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>
:::
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| errMsg | string | 是 | - | Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: - | 错误信息 |
HarmonyOS 平台使用时需要添加受限开放权限 ohos.permission.PRIVACY_WINDOW