This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 55).

Expo 屏幕捕获

一个允许你保护应用中的屏幕不被捕获或录制的库。

Android

iOS

Included in Expo Go

GitHub

npm

更新日志

expo-screen-capture 允许你保护应用中的屏幕不被捕获或录制，并且当应用处于前台时，如果有人截取了屏幕截图，你也会收到通知。你可能希望阻止屏幕捕获的两个最常见原因是：

如果某个屏幕正在显示敏感信息（密码、信用卡数据等）
你正在展示付费内容，而不希望它被录制并分享

这在 Android 上尤其重要，因为 android.media.projection API 允许第三方应用执行屏幕捕获或屏幕共享（即使应用处于后台）。

在 Android 上，屏幕捕获回调在 Android 14+ 上无需额外权限即可工作。在 Android 14+ 上，你不需要请求或检查用于阻止屏幕捕获或使用回调的权限。

如果你想在 Android 13 或更低版本上使用屏幕捕获回调，你需要在 AndroidManifest.xml 文件中添加 READ_MEDIA_IMAGES 权限。你可以在应用配置中使用 android.permissions 键。更多信息请参阅 Android permissions。

READ_MEDIA_IMAGES 权限只能为需要广泛访问照片的应用添加。请参阅 Google Play 关于照片和视频权限政策的详情。

测试屏幕捕获功能时：在 Android 模拟器上，在单独的终端中运行 adb shell input keyevent 120 以触发截图。在 iOS 模拟器上，你可以通过菜单栏中的 Device > Trigger Screenshot 来触发截图。

安装

Terminal

- npx expo install expo-screen-capture

If you are installing this in an existing React Native app, make sure to install expo in your project.

使用

示例：hook

Screen Capture hook

import { usePreventScreenCapture } from 'expo-screen-capture';
import { Text, View } from 'react-native';

export default function ScreenCaptureExample() {
  usePreventScreenCapture();

  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Text>只要这个组件处于挂载状态，这个屏幕就无法被录制！</Text>
    </View>
  );
}

示例：以命令式方式阻止屏幕捕获

Blocking screen capture

import * as ScreenCapture from 'expo-screen-capture';
import { useEffect } from 'react';
import { Button, StyleSheet, View } from 'react-native';

export default function ScreenCaptureExample() {
  const activate = async () => {
    await ScreenCapture.preventScreenCaptureAsync();
  };

  const deactivate = async () => {
    await ScreenCapture.allowScreenCaptureAsync();
  };

  return (
    <View style={styles.container}>
      <Button title="激活" onPress={activate} />
      <Button title="停用" onPress={deactivate} />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});

示例：屏幕捕获回调

Callback for screen capture

import * as ScreenCapture from 'expo-screen-capture';
import { useEffect } from 'react';
import { Button, StyleSheet, View } from 'react-native';

export default function useScreenCaptureCallback() {
  // 仅在你将 READ_MEDIA_IMAGES 权限添加到 AndroidManifest.xml 时使用此功能
  const hasPermissions = async () => {
    const { status } = await ScreenCapture.requestPermissionsAsync();
    return status === 'granted';
  };

  useEffect(() => {
    let subscription;

    const addListenerAsync = async () => {
      if (await hasPermissions()) {
        subscription = ScreenCapture.addScreenshotListener(() => {
          alert('感谢你截取了我美丽应用的截图 😊');
        });
      } else {
        console.error('订阅截图事件所需的权限缺失！');
      }
    };
    addListenerAsync();

    return () => {
      subscription?.remove();
    };
  }, []);
}

API

import * as ScreenCapture from 'expo-screen-capture';

Hooks

`usePermissions(options)`

Android

iOS

Parameter	Type
options(optional)	`PermissionHookOptions<object>`

Check or request permissions necessary for detecting when a screenshot is taken. This uses both requestPermissionsAsync and getPermissionsAsync to interact with the permissions.

Returns:

[PermissionResponse | null, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]

Example

const [status, requestPermission] = ScreenCapture.usePermissions();

`usePreventScreenCapture(key)`

Android

iOS

Parameter	Type	Description
key(optional)	`string`	If provided, this will prevent multiple instances of this hook or the `preventScreenCaptureAsync` and `allowScreenCaptureAsync` methods from conflicting with each other. This argument is useful if you have multiple active components using the `allowScreenCaptureAsync` hook. Default:`'default'`

A React hook to prevent screen capturing for as long as the owner component is mounted.

Returns:

void

`useScreenshotListener(listener)`

Android

iOS

Parameter	Type	Description
listener	`() => void`	A function that will be called whenever a screenshot is detected. This hook automatically starts listening when the component mounts, and stops listening when the component unmounts.

A React hook that listens for screenshots taken while the component is mounted.

Returns:

void

Methods

`ScreenCapture.allowScreenCaptureAsync(key)`

Android

iOS

Parameter	Type	Description
key(optional)	`string`	This will prevent multiple instances of the `preventScreenCaptureAsync` and `allowScreenCaptureAsync` methods from conflicting with each other. If provided, the value must be the same as the key passed to `preventScreenCaptureAsync` in order to re-enable screen capturing. Default:`'default'`

Re-allows the user to screen record or screenshot your app. If you haven't called preventScreenCapture() yet, this method does nothing.

Returns:

Promise<void>

`ScreenCapture.disableAppSwitcherProtectionAsync()`

iOS

Disables the privacy protection overlay that was previously enabled with enableAppSwitcherProtectionAsync.

Returns:

Promise<void>

`ScreenCapture.enableAppSwitcherProtectionAsync(blurIntensity)`

iOS

Parameter	Type	Description
blurIntensity(optional)	`number`	The intensity of the blur effect, from 0.0 (no blur) to 1.0 (maximum blur). Default is 0.5. Default:`0.5`

Enables a privacy protection blur overlay that hides sensitive content when the app is not in focus. The overlay applies a customizable blur effect when the app is in the app switcher, background, or during interruptions (calls, Siri, Control Center, etc.), and automatically removes it when the app becomes active again.

This provides visual privacy protection by preventing sensitive app content from being visible in:

App switcher previews
Background app snapshots
Screenshots taken during inactive states

For Android, app switcher protection is automatically provided by preventScreenCaptureAsync() using the FLAG_SECURE window flag, which shows a blank screen in the recent apps preview.

Returns:

Promise<void>

`ScreenCapture.getPermissionsAsync()`

Android

iOS

Checks user's permissions for detecting when a screenshot is taken.

Only Android requires additional permissions to detect screenshots. On iOS devices, this method will always resolve to a granted permission response.

Returns:

Promise<PermissionResponse>

A promise that resolves to a PermissionResponse object.

`ScreenCapture.isAvailableAsync()`

Android

iOS

Returns whether the Screen Capture API is available on the current device.

Returns:

Promise<boolean>

A promise that resolves to a boolean indicating whether the Screen Capture API is available on the current device.

`ScreenCapture.preventScreenCaptureAsync(key)`

Android

iOS

Parameter	Type	Description
key(optional)	`string`	Optional. If provided, this will help prevent multiple instances of the `preventScreenCaptureAsync` and `allowScreenCaptureAsync` methods (and `usePreventScreenCapture` hook) from conflicting with each other. When using multiple keys, you'll have to re-allow each one in order to re-enable screen capturing. Default:`'default'`

Prevents screenshots and screen recordings until allowScreenCaptureAsync is called or the app is restarted. If you are already preventing screen capture, this method does nothing (unless you pass a new and unique key).

On iOS, this prevents screen recordings and screenshots, and is only available on iOS 11+ (recordings) and iOS 13+ (screenshots). On older iOS versions, this method does nothing.

Returns:

Promise<void>

`ScreenCapture.requestPermissionsAsync()`

Android

iOS

Asks the user to grant permissions necessary for detecting when a screenshot is taken.

Only Android requires additional permissions to detect screenshots. On iOS devices, this method will always resolve to a granted permission response.

Returns:

Promise<PermissionResponse>

A promise that resolves to a PermissionResponse object.

Event Subscriptions

`ScreenCapture.addScreenshotListener(listener)`

Android

iOS

Parameter	Type	Description
listener	`() => void`	The function that will be executed when the user takes a screenshot. This function accepts no arguments.

Adds a listener that will fire whenever the user takes a screenshot while the app is foregrounded.

Permission requirements for this method depend on your device’s Android version:

Before Android 13: Requires READ_EXTERNAL_STORAGE.
Android 13: Switches to READ_MEDIA_IMAGES.
Post-Android 13: No additional permissions required. You can request the appropriate permissions by using MediaLibrary.requestPermissionsAsync().

Returns:

EventSubscription

A Subscription object that you can use to unregister the listener, either by calling remove() or passing it to removeScreenshotListener.

Deprecated: use subscription.remove() instead.

`ScreenCapture.removeScreenshotListener(subscription)`

Android

iOS

Parameter	Type
subscription	`EventSubscription`

Removes the subscription you provide, so that you are no longer listening for screenshots.

Returns:

void

`ScreenCapture.useScreenshotListener(listener)`

Android

iOS

Parameter	Type	Description
listener	`() => void`	A function that will be called whenever a screenshot is detected. This hook automatically starts listening when the component mounts, and stops listening when the component unmounts.

A React hook that listens for screenshots taken while the component is mounted.

Returns:

void

Interfaces

`Subscription`

Android

iOS

A subscription object that allows to conveniently remove an event listener from the emitter.

Subscription Methods

`remove()`

Android

iOS

Removes an event listener for which the subscription has been created. After calling this function, the listener will no longer receive any events from the emitter.

Returns:

void

Types

`PermissionHookOptions`

Android

iOS

Literal Type: union

Acceptable values are: PermissionHookBehavior | Options

`PermissionResponse`

Android

iOS

An object obtained by permissions get and request functions.

Property	Type	Description
canAskAgain	`boolean`	Indicates if user can be asked again for specific permission. If not, one should be directed to the Settings app in order to enable/disable the permission.
expires	`PermissionExpiration`	Determines time when the permission expires.
granted	`boolean`	A convenience boolean that indicates if the permission is granted.
status	`PermissionStatus`	Determines the status of the permission.

Enums

`PermissionStatus`

Android

iOS

`DENIED`

PermissionStatus.DENIED ＝ "denied"

User has denied the permission.

`GRANTED`

PermissionStatus.GRANTED ＝ "granted"

User has granted the permission.

`UNDETERMINED`

PermissionStatus.UNDETERMINED ＝ "undetermined"

User hasn't granted or denied the permission yet.