This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Expo 后台获取
一个提供用于执行后台获取任务 API 的库。
警告 已弃用:
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。
安装
If you are installing this in an existing React Native app, make sure to install expo in your project.
配置 iOS
要能够在 iOS 上运行后台抓取任务,你需要在应用的 Info.plist 文件中将 fetch 值添加到 UIBackgroundModes 数组中。这是后台抓取正常工作的必要条件。
如果你使用的是 CNG,所需的 UIBackgroundModes 配置会在 prebuild 过程中自动应用。
在 iOS 上手动配置 UIBackgroundModes
如果你没有使用 Continuous Native Generation (CNG),或者你正在手动使用原生 ios 项目,那么你需要将以下内容添加到你的 Expo.plist 文件中:
用法
下面是一个演示如何使用 expo-background-fetch 的示例。
触发后台抓取
后台抓取可能难以测试,因为它们的发生并不稳定。幸运的是,在开发应用时,你可以手动触发后台抓取。
对于 iOS,你可以使用 macOS 上的 Instruments 应用手动触发后台抓取:
- 打开 Instruments 应用。你可以通过 Spotlight(Cmd ⌘ + Space)搜索 Instruments 应用,或从
/Applications/Xcode.app/Contents/Applications/Instruments.app打开它 - 选择
Time Profiler - 选择你的设备 / 模拟器,并选择
Expo Go应用 - 点击左上角的
Record按钮 - 打开
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()fromexpo-background-taskinstead. Theexpo-background-fetchpackage has been deprecated.
Gets a status of background fetch.
Promise<BackgroundFetchStatus | null>Returns a promise which fulfils with one of BackgroundFetchStatus enum values.
Deprecated: Use
registerTaskAsync()fromexpo-background-taskinstead. Theexpo-background-fetchpackage has been deprecated.
Registers background fetch task with given name. Registered tasks are saved in persistent storage and restored once the app is initialized.
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 specifyBackgroundTaskOptionsargument instead, when setting task interval time.
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.
Promise<void>A promise which fulfils once the minimum interval is set.
Deprecated: Use
unregisterTaskAsync()fromexpo-background-taskinstead. Theexpo-background-fetchpackage has been deprecated.
Unregisters background fetch task, so the application will no longer be executing this task.
Promise<void>A promise which fulfils when the task is fully unregistered.
Interfaces
Enums
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.
BackgroundFetchStatus.Denied = 1The user explicitly disabled background behavior for this app or for the whole system.
BackgroundFetchStatus.Restricted = 2Background 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.
权限
Android
在 Android 上,该模块可能会在设备启动时进行监听。这对于继续运行使用 startOnBoot 启动的任务是必要的。它还会使即将进入空闲和快速睡眠状态的设备保持“唤醒”,以提高任务的可靠性。因此,会自动添加 RECEIVE_BOOT_COMPLETED 和 WAKE_LOCK 这两个权限。