Expo ScreenCapture

一个允许你保护应用中的屏幕，防止被截图或录制的库。

Android

iOS

Included in Expo Go

GitHub

npm

更新日志

Recommended version:

~57.0.0

expo-screen-capture 允许你保护应用中的屏幕，防止其被捕获或录制，同时还可以在应用处于前台时截图被拍摄时收到通知。你可能想要阻止屏幕捕获的两个最常见原因是：

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

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

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

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

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

测试屏幕捕获功能时：在 Android Emulator 上，在单独的终端中运行 adb shell input keyevent 120 以触发截图。在 iOS Simulator 上，你可以通过菜单栏中的 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

屏幕捕获 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>
  );
}

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

阻止屏幕捕获

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="Activate" onPress={activate} />
      <Button title="Deactivate" onPress={deactivate} />
    </View>
  );
}

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

示例：屏幕捕获回调

屏幕捕获回调

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

export default function useScreenCaptureCallback() {
  // 仅当你在 AndroidManifest.xml 中添加了 READ_MEDIA_IMAGES 权限时才使用此方法
  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)`

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)`

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)`

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)`

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()`

Only for:

iOS

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

Returns:

Promise<void>

`ScreenCapture.enableAppSwitcherProtectionAsync(blurIntensity)`

Only for:

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()`

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()`

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)`

Only for:

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()`

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)`

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)`

Parameter	Type
subscription	`EventSubscription`

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

Returns:

void

`ScreenCapture.useScreenshotListener(listener)`

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`

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

Subscription Methods

`remove()`

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`

Literal type: union

Acceptable values are: PermissionHookBehavior | Options

`PermissionResponse`

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`

`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.