Expo 屏幕捕获
一个允许你保护应用中的屏幕不被截取或录制的库。
For the complete documentation index, see llms.txt. Use this Use this file to discover all available pages.
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 照片和视频权限政策详情。
目前,iOS 上无法阻止截图。这是由于底层操作系统的限制。
测试屏幕捕获功能时:在 Android Emulator 上,在单独的终端中运行adb shell input keyevent 120来触发截图。在 iOS Simulator 上,你可以通过菜单栏中的 Device > Trigger Screenshot 来触发截图。
安装
- npx expo install expo-screen-captureIf you are installing this in an existing React Native app, make sure to install expo in your project.
用法
示例: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="激活" onPress={activate} /> <Button title="停用" 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
| 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.
[null | PermissionResponse, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]Example
const [status, requestPermission] = ScreenCapture.usePermissions();
| Parameter | Type | Description |
|---|---|---|
| key(optional) | string | If provided, this will prevent multiple instances of this hook or the
Default: 'default' |
A React hook to prevent screen capturing for as long as the owner component is mounted.
voidMethods
| Parameter | Type | Description |
|---|---|---|
| key(optional) | string | This will prevent multiple instances of the Default: 'default' |
Re-allows the user to screen record or screenshot your app. If you haven't called
preventScreenCapture() yet, this method does nothing.
Promise<void>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
grantedpermission response.
Promise<PermissionResponse>A promise that resolves to a PermissionResponse object.
Returns whether the Screen Capture API is available on the current device.
Promise<boolean>A promise that resolves to a boolean indicating whether the Screen Capture API is available on the current
device.
| Parameter | Type | Description |
|---|---|---|
| key(optional) | string | Optional. If provided, this will help prevent multiple instances of the 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).
Please note that on iOS, this will only prevent screen recordings, and is only available on iOS 11 and newer. On older iOS versions, this method does nothing.
Promise<void>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
grantedpermission response.
Promise<PermissionResponse>A promise that resolves to a PermissionResponse object.
Event Subscriptions
| 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.
On Android, this method requires the READ_EXTERNAL_STORAGE permission. You can request this
with MediaLibrary.requestPermissionsAsync().
EventSubscriptionA Subscription object that you can use to unregister the listener, either by calling
remove() or passing it to removeScreenshotListener.
| Parameter | Type | Description |
|---|---|---|
| subscription | EventSubscription | Subscription returned by |
Removes the subscription you provide, so that you are no longer listening for screenshots.
You can also call remove() on that Subscription object.
voidExample
let mySubscription = addScreenshotListener(() => { console.log("You took a screenshot!"); }); ... mySubscription.remove(); // OR removeScreenshotListener(mySubscription);
Interfaces
A subscription object that allows to conveniently remove an event listener from the emitter.
Types
Literal Type: union
Acceptable values are: PermissionHookBehavior | Options
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. |