Expo BackgroundTask

提供用于运行后台任务的 API 的库。

expo-background-task 提供了一个 API，用于以优化终端用户设备上的电池和功耗的方式运行可延迟的后台任务。此模块使用 Android 上的 WorkManager API 和 iOS 上的 BGTaskScheduler API 来安排任务。它还使用 expo-task-manager Native API 来运行 JavaScript 任务。

¥expo-background-task provides an API to run deferrable background tasks in a way that optimizes battery and power consumption on the end user's device. This module uses the WorkManager API on Android and the BGTaskScheduler API on iOS to schedule tasks. It also uses the expo-task-manager Native API to run JavaScript tasks.

后台任务

¥Background tasks

后台任务是在后台执行的可延迟工作单元，在应用生命周期之外。这对于需要在应用处于非活动状态时执行的任务很有用，例如与服务器同步数据、获取新内容，甚至检查是否有任何 expo-updates。

¥A background task is a deferrable unit of work that is performed in the background, outside your app's lifecycle. This is useful for tasks that need to be executed when the app is inactive, such as syncing data with a server, fetching new content, or even checking if there are any expo-updates.

后台任务何时运行？

¥When are background tasks run?

当应用处于后台时，Expo 后台任务 API 利用每个平台在对用户和设备而言最合适的时间执行任务。

¥The Expo Background Task API leverages each platform to execute tasks at the most optimal time for both the user and the device when the app is in the background.

这意味着任务可能不会在安排后立即运行，但如果系统决定，它将在未来某个时间点运行。你可以指定任务运行的最小间隔（以分钟为单位）。如果满足指定的条件，任务将在间隔过后的某个时间执行。

¥This means that the task may not run immediately after it is scheduled, but it will run at some point in the future if the system decides so. You can specify a minimum interval in minutes for the task to run. The task will execute sometime after the interval has passed, provided the specified conditions are met.

仅当电池电量充足（或设备已插入电源）且网络可用时，后台任务才会运行。如果没有这些条件，任务将无法执行。确切的行为将因操作系统而异。

¥A background task will only run if the battery has enough charge (or the device is plugged into power) and the network is available. Without these conditions, the task won't execute. The exact behavior will vary depending on the operating system.

何时停止？

¥When will they be stopped?

后台任务由平台 API 和系统约束管理。了解任务何时停止有助于有效地规划它们的使用。

¥Background tasks are managed by platform APIs and system constraints. Knowing when tasks stop helps plan their use effectively.

• 如果用户终止应用，后台任务将停止。应用重新启动时任务恢复。

  ¥Background tasks are stopped if the user kills the app. Tasks resume when the app is restarted.

• 如果系统停止应用或设备重新启动，后台任务将恢复，并且应用将重新启动。

  ¥If the system stops the app or the device reboots, background tasks will resume, and the app will be restarted.

在 Android 上，从最近的应用列表中删除应用并不能完全停止它，而在 iOS 上，在应用切换器中将其滑走会完全终止它。

¥On Android, removing an app from the recent apps list doesn't completely stop it, whereas on iOS, swiping it away in the app switcher fully terminates it.

信息 在 Android 上，行为因设备供应商而异。例如，某些实现将应用从最近的应用列表中删除视为将其终止。在此处阅读有关这些差异的更多信息：https://dontkillmyapp.com。

¥On Android, behavior varies by device vendor. For example, some implementations treat removing an app from the recent apps list as killing it. Read more about these differences here: https://dontkillmyapp.com.

平台差异

¥Platform differences

安卓

¥Android

在 Android 上，WorkManager API 允许指定任务运行的最小间隔（最少 15 分钟）。如果满足指定的条件，任务将在间隔过后的某个时间执行。

¥On Android, the WorkManager API allows specifying a minimum interval for a task to run (minimum 15 minutes). The task will execute sometime after the interval has passed, provided the specified conditions are met.

iOS 系统

¥iOS

在 iOS 上，BGTaskScheduler API 决定启动后台任务的最佳时间。系统将考虑电池电量、网络可用性和用户的使用模式来确定何时运行任务。你仍然可以指定任务运行的最小间隔，但系统可能会选择稍后运行该任务。

¥On iOS, the BGTaskScheduler API decides the best time to launch your background task. The system will consider the battery level, the network availability, and the user's usage patterns to determine when to run the task. You can still specify a minimum interval for the task to run, but the system may choose to run the task at a later time.

已知的限制

¥Known limitations

iOS 系统

¥iOS

Background Tasks API 在 iOS 模拟器上不可用。它仅在物理设备上运行时可用。

¥The Background Tasks API is unavailable on iOS simulators. It is only available when running on a physical device.

安装

¥Installation

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

配置

¥Configuration

为了能够在 iOS 上运行后台任务，你需要将 processing 值添加到应用的 Info.plist 文件中的 UIBackgroundModes 数组中。这是后台获取正常工作所必需的。

¥To be able to run background tasks on iOS, you need to add the processing value to the UIBackgroundModes array in your app's Info.plist file. This is required for background fetch to work properly.

如果你使用 CNG，所需的 UIBackgroundModes 配置将由预构建自动应用。

¥If you're using CNG, the required UIBackgroundModes configuration will be applied automatically by prebuild.

Usage

Below is an example that demonstrates how to use expo-background-task.

!!!IG1!!!

Multiple background tasks

Since the Background Tasks API on iOS and the WorkManager API on Android limit the number of tasks that can be scheduled for a single app, Expo Background Task uses a single worker on both platforms. While you can define multiple JavaScript background tasks, they will all run through this single worker.

The last registered background task determines the minimum interval for execution.

Testing background tasks

Background tasks can be tested using the triggerTaskWorkerForTestingAsync method. This method will run all registered tasks directly on Android and invoke the BGTaskScheduler on iOS. This is useful for testing the behavior of your background tasks without having to wait for the system to trigger them.

This method is only available in development mode. It will not work in production builds.

!!!IG2!!!

Inspecting background tasks 

!!!IG12!!!

To troubleshoot or debug issues with background tasks on Android, use the adb tool included with the Android SDK to inspect scheduled tasks:

!!!IG6!!!

The output from this command will show you the scheduled tasks for your app, including their status, constraints, and other information. Look for the JOB line to find the ID of the job and other details in the output:

!!!IG3!!!

The first line contains the Job ID (275). The Run time: earliest value indicates the earliest time the task may start, while enqueue time shows how long ago the task was scheduled.

To force a task to run, use the adb shell am broadcast command. Move your app to the background before running this command, as the task will not run if the app is in the foreground.

!!!IG7!!!

Where JOB_ID would be the identifier of the job you want to run that you found in the previous step.

Troubleshooting background tasks 

!!!IG13!!!

iOS does not have a tool similar to adb for inspecting background tasks. To test background tasks on iOS, use the built-in triggerTaskWorkerForTestingAsync method. This method simulates the system triggering the task.

You can trigger this method from your app in debug mode (it does not work in production builds) to test the behavior of your background tasks without waiting for the system. If your background task configuration is incorrect, you will see the error description in the Xcode console:

!!!IG4!!!

The above error tells you that you need to run prebuild to apply the changes to your app's configuration.

This error also means you must run prebuild to apply your background task configuration to the app. Additionally, ensure you have defined and registered a background task as shown in this example.

API

!!!IG5!!!

Methods

import * as TaskManager from 'expo-task-manager';

// Register the task outside of the component
TaskManager.defineTask(BACKGROUND_TASK_IDENTIFIER, () => {
  try {
    await AsyncStorage.setItem(LAST_TASK_DATE_KEY, Date.now().toString());
  } catch (error) {
    console.error('Failed to save the last fetch date', error);
    return BackgroundTaskResult.Failed;
  }
  return BackgroundTaskResult.Success;
});

BackgroundTask.registerTaskAsync(BACKGROUND_TASK_IDENTIFIER, {});

Types

Enums