Back to Uni App

Capture Screen

docs/api/capture-screen.md

2.3.312.7 KB
Original Source

uni.onUserCaptureScreen(callback?) @onusercapturescreen

开启截屏监听

本 API 是 uni ext api,需下载插件:uni-usercapturescreen

onUserCaptureScreen 兼容性

Web微信小程序AndroidiOSHarmonyOS
<a style="color:unset;" href="https://vote.dcloud.net.cn/#/?name=uni-app%20x">x</a>4.113.9.04.114.61

参数

名称类型必填默认值兼容性描述
callback(res: OnUserCaptureScreenCallbackResult) => void-Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -

OnUserCaptureScreenCallbackResult 的属性值 @onusercapturescreencallbackresult-values

名称类型必备默认值兼容性描述
pathstring-Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -截屏文件路径(仅Android返回)

参见

uni.offUserCaptureScreen(callback?) @offusercapturescreen

关闭截屏监听

本 API 是 uni ext api,需下载插件:uni-usercapturescreen

offUserCaptureScreen 兼容性

Web微信小程序AndroidiOSHarmonyOS
<a style="color:unset;" href="https://vote.dcloud.net.cn/#/?name=uni-app%20x">x</a>4.113.9.04.114.61

参数

名称类型必填默认值兼容性描述
callback(res: OnUserCaptureScreenCallbackResult) => void-Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -

OnUserCaptureScreenCallbackResult 的属性值 @onusercapturescreencallbackresult-values

名称类型必备默认值兼容性描述
pathstring-Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -截屏文件路径(仅Android返回)

参见

通用类型

GeneralCallbackResult

名称类型必备默认值兼容性描述
errMsgstring-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -错误信息

uni.setUserCaptureScreen(options) @setusercapturescreen

设置防截屏

本 API 是 uni ext api,需下载插件:uni-usercapturescreen

setUserCaptureScreen 兼容性

Web微信小程序AndroidiOS 系统版本iOSHarmonyOS
<a style="color:unset;" href="https://vote.dcloud.net.cn/#/?name=uni-app%20x">x</a>4.113.9.013.04.114.61

参数

名称类型必填默认值兼容性描述
optionsSetUserCaptureScreenOptions-Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -

options 的属性描述

名称类型必备默认值兼容性描述
enableboolean-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完成回调函数定义

IUniError 的属性值 @iunierror-values

名称类型必备默认值兼容性描述
errCodenumber-Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -统一错误码
errSubjectstring-Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -统一错误主题(模块)名称
dataany-Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -错误信息中包含的数据
causeError-Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -源错误信息,可以包含多个错误,详见SourceError
errMsgstring-Web: x; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -
<!-- UTSAPIJSON.setUserCaptureScreen.example -->

参见

示例

示例为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

uvue
<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>



:::

通用类型

GeneralCallbackResult

名称类型必备默认值兼容性描述
errMsgstring-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -错误信息

tips

  • 本文的截屏指手机自带的截屏事件的监听和取消监听,由用户操作手机按键触发。App平台如需通过代码对view截屏,另见API takeSnapshot
  • iOS平台该API在iOS 13.0及以上系统支持,在iOS 13.0以下系统调用该API会返回12001:system not support的错误。
  • 因iOS 15.1系统bug,在该系统上调用此API会返回12010:system internal error的错误。
  • Android平台在某些页面暂不支持(如:图片选择、图片预览、一键登录等页面以及App原生插件内部原生页面)。
  • HarmonyOS 平台使用时需要添加受限开放权限 ohos.permission.PRIVACY_WINDOW