Reference version

Expo BackgroundFetch

一个提供执行后台获取任务 API 的库。

Android
iOS
Bundled version:
~13.1.6

For the complete documentation index, see llms.txt. Use this Use this file to discover all available pages.

已弃用: expo-background-fetch 库正在被 expo-background-task 中的新版本替代。expo-background-fetch 不再接收补丁,并将在即将发布的版本中移除。

expo-background-fetch 提供了一个用于执行后台获取任务的 API,允许你定期在后台运行特定代码以更新你的应用。这个模块在底层使用 TaskManager 原生 API。

已知问题 
iOS

BackgroundFetch 仅在应用处于后台时可用;如果应用已终止或设备重启后则不可用。你可以查看相关的 GitHub issue 了解更多详情。

在 iOS 上,BackgroundFetch 库要求你使用 开发构建,因为 iOS 的 Expo Go 应用中未启用 Background Fetch。

安装

Terminal
npx expo install expo-background-fetch

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

配置 
iOS

要能够在 iOS 上运行后台获取任务,你需要在应用的 Info.plist 文件中的 UIBackgroundModes 数组里添加 fetch 值。这是 Background Fetch 正常工作所必需的。

如果你正在使用 CNG,所需的 UIBackgroundModes 配置会在 prebuild 过程中自动应用。

在 iOS 上手动配置 UIBackgroundModes

如果你没有使用 Continuous Native Generation(CNG),或者你正在手动使用原生 ios 项目,那么你需要将以下内容添加到你的 Expo.plist 文件中:

ios/project-name/Supporting/Expo.plist
<key>UIBackgroundModes</key> <array> <string>fetch</string> </array>

用法

下面是一个演示如何使用 expo-background-fetch 的示例。

Background Fetch Usage
import { useState, useEffect } from 'react'; import { StyleSheet, Text, View, Button } from 'react-native'; import * as BackgroundFetch from 'expo-background-fetch'; import * as TaskManager from 'expo-task-manager'; const BACKGROUND_FETCH_TASK = 'background-fetch'; // 1. 通过提供名称和应执行的函数来定义任务 // 注意:这需要在全局作用域中调用(例如在你的 React 组件外部) TaskManager.defineTask(BACKGROUND_FETCH_TASK, async () => { const now = Date.now(); console.log(`Got background fetch call at date: ${new Date(now).toISOString()}`); // 一定要返回成功的结果类型! return BackgroundFetch.BackgroundFetchResult.NewData; }); // 2. 在你的应用中的某个时刻注册该任务,提供相同的名称, // 以及用于控制后台获取行为的配置选项 // 注意:这不需要在全局作用域中,并且可以在你的 React 组件中使用! async function registerBackgroundFetchAsync() { return BackgroundFetch.registerTaskAsync(BACKGROUND_FETCH_TASK, { minimumInterval: 60 * 15, // 15 分钟 stopOnTerminate: false, // 仅安卓, startOnBoot: true, // 仅安卓 }); } // 3. (可选)通过指定任务名称注销任务 // 这将取消所有与给定名称匹配的未来后台获取调用 // 注意:这不需要在全局作用域中,并且可以在你的 React 组件中使用! async function unregisterBackgroundFetchAsync() { return BackgroundFetch.unregisterTaskAsync(BACKGROUND_FETCH_TASK); } export default function BackgroundFetchScreen() { const [isRegistered, setIsRegistered] = useState(false); const [status, setStatus] = useState<BackgroundFetch.BackgroundFetchStatus | null>(null); useEffect(() => { checkStatusAsync(); }, []); const checkStatusAsync = async () => { const status = await BackgroundFetch.getStatusAsync(); const isRegistered = await TaskManager.isTaskRegisteredAsync(BACKGROUND_FETCH_TASK); setStatus(status); setIsRegistered(isRegistered); }; const toggleFetchTask = async () => { if (isRegistered) { await unregisterBackgroundFetchAsync(); } else { await registerBackgroundFetchAsync(); } checkStatusAsync(); }; return ( <View style={styles.screen}> <View style={styles.textContainer}> <Text> 后台获取状态:{' '} <Text style={styles.boldText}> {status && BackgroundFetch.BackgroundFetchStatus[status]} </Text> </Text> <Text> 后台获取任务名称:{' '} <Text style={styles.boldText}> {isRegistered ? BACKGROUND_FETCH_TASK : '尚未注册!'} </Text> </Text> </View> <View style={styles.textContainer}></View> <Button title={isRegistered ? '注销 BackgroundFetch 任务' : '注册 BackgroundFetch 任务'} onPress={toggleFetchTask} /> </View> ); } const styles = StyleSheet.create({ screen: { flex: 1, justifyContent: 'center', alignItems: 'center', }, textContainer: { margin: 10, }, boldText: { fontWeight: 'bold', }, });

触发后台获取

后台获取可能难以测试,因为它们的触发可能不稳定。幸运的是,在开发你的应用时,你可以手动触发后台获取。

对于 iOS,你可以使用 macOS 上的 Instruments 应用手动触发后台获取:

  1. 打开 Instruments 应用。可以通过 Spotlight(⌘ + Space)搜索,或者从 /Applications/Xcode.app/Contents/Applications/Instruments.app 打开
  2. 选择 Time Profiler
  3. 选择你的设备/模拟器并选中 Expo Go 应用
  4. 点击左上角的 Record 按钮
  5. 前往 Document 菜单并选择 Simulate Background Fetch - Expo Go

对于 Android,你可以将任务的 minimumInterval 选项设置为一个较小的数值,然后像这样让应用进入后台:

async function registerBackgroundFetchAsync() { return BackgroundFetch.registerTaskAsync(BACKGROUND_FETCH_TASK, { minimumInterval: 1 * 60, // 任务将在应用进入后台 1 分钟后触发 }); }

API

import * as BackgroundFetch from 'expo-background-fetch';

Methods

Deprecated: Use getStatusAsync() from expo-background-task instead. The expo-background-fetch package has been deprecated.

BackgroundFetch.getStatusAsync()

Android
iOS

Gets a status of background fetch.

Returns a promise which fulfils with one of BackgroundFetchStatus enum values.

Deprecated: Use registerTaskAsync() from expo-background-task instead. The expo-background-fetch package has been deprecated.

BackgroundFetch.registerTaskAsync(taskName, options)

Android
iOS
ParameterTypeDescription
taskNamestring

Name of the task to register. The task needs to be defined first - see TaskManager.defineTask for more details.

options(optional)BackgroundFetchOptions

An object containing the background fetch options.

Default:{}

Registers background fetch task with given name. Registered tasks are saved in persistent storage and restored once the app is initialized.

Returns:
Promise<void>

Example

import * as BackgroundFetch from 'expo-background-fetch'; import * as TaskManager from 'expo-task-manager'; TaskManager.defineTask(YOUR_TASK_NAME, () => { try { const receivedNewData = // do your background fetch here return receivedNewData ? BackgroundFetch.BackgroundFetchResult.NewData : BackgroundFetch.BackgroundFetchResult.NoData; } catch (error) { return BackgroundFetch.BackgroundFetchResult.Failed; } });

Deprecated: Use the registerTaskAsync() method from expo-background-task package, and specify BackgroundTaskOptions argument instead, when setting task interval time.

BackgroundFetch.setMinimumIntervalAsync(minimumInterval)

Android
iOS
ParameterTypeDescription
minimumIntervalnumber

Number of seconds that must elapse before another background fetch can be called.


Sets the minimum number of seconds that must elapse before another background fetch can be initiated. This value is advisory only and does not indicate the exact amount of time expected between fetch operations.

This method doesn't take any effect on Android. It is a global value which means that it can overwrite settings from another application opened through Expo Go.

Returns:
Promise<void>

A promise which fulfils once the minimum interval is set.

Deprecated: Use unregisterTaskAsync() from expo-background-task instead. The expo-background-fetch package has been deprecated.

BackgroundFetch.unregisterTaskAsync(taskName)

Android
iOS
ParameterTypeDescription
taskNamestring

Name of the task to unregister.


Unregisters background fetch task, so the application will no longer be executing this task.

Returns:
Promise<void>

A promise which fulfils when the task is fully unregistered.

Interfaces

BackgroundFetchOptions

Android
iOS
PropertyTypeDescription
minimumInterval(optional)number

Inexact interval in seconds between subsequent repeats of the background fetch alarm. The final interval may differ from the specified one to minimize wakeups and battery usage.

  • On Android it defaults to 10 minutes,
  • On iOS it calls BackgroundFetch.setMinimumIntervalAsync behind the scenes and the default value is the smallest fetch interval supported by the system (10-15 minutes). Background fetch task receives no data, but your task should return a value that best describes the results of your background fetch work.
startOnBoot(optional)boolean
Only for:
Android

Whether to restart background fetch events when the device has finished booting.

Default:false
stopOnTerminate(optional)boolean
Only for:
Android

Whether to stop receiving background fetch events after user terminates the app.

Default:true

Enums

BackgroundFetchResult

Android
iOS

This return value is to let iOS know what the result of your background fetch was, so the platform can better schedule future background fetches. Also, your app has up to 30 seconds to perform the task, otherwise your app will be terminated and future background fetches may be delayed.

NoData

BackgroundFetchResult.NoData = 1

There was no new data to download.

NewData

BackgroundFetchResult.NewData = 2

New data was successfully downloaded.

Failed

BackgroundFetchResult.Failed = 3

An attempt to download data was made but that attempt failed.

BackgroundFetchStatus

Android
iOS

Denied

BackgroundFetchStatus.Denied = 1

The user explicitly disabled background behavior for this app or for the whole system.

Restricted

BackgroundFetchStatus.Restricted = 2

Background updates are unavailable and the user cannot enable them again. This status can occur when, for example, parental controls are in effect for the current user.

Available

BackgroundFetchStatus.Available = 3

Background updates are available for the app.

权限

Android

在 Android 上,此模块可能会在设备启动时监听。这样做是为了继续执行使用 startOnBoot 启动的任务。它还会让那些即将空闲并快速进入睡眠的设备保持“唤醒”,以提高任务的可靠性。因此,RECEIVE_BOOT_COMPLETEDWAKE_LOCK 这两个权限会自动添加。

Android PermissionDescription

RECEIVE_BOOT_COMPLETED

Allows an application to receive the Intent.ACTION_BOOT_COMPLETED that is broadcast after the system finishes booting.

Allows an application to receive the Intent.ACTION_BOOT_COMPLETED that is broadcast after the system finishes booting. If you don't request this permission, you will not receive the broadcast at that time. Though holding this permission does not have any security implications, it can have a negative impact on the user experience by increasing the amount of time it takes the system to start and allowing applications to have themselves running without the user being aware of them. As such, you must explicitly declare your use of this facility to make that visible to the user.

WAKE_LOCK

Allows using PowerManager WakeLocks to keep processor from sleeping or screen from dimming.