Docs
博客更新日志GitHub简中文档
首页指南EAS参考学习

Reference version

存档Expo SnackDiscord 和论坛新闻邮件
This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 56).

Expo 任务管理器

一个为可在后台运行的任务提供支持的库。

Android
iOS
tvOS
Included in Expo Go

GitHub

npm

更新日志

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

expo-task-manager 提供了一个 API，允许你管理长时间运行的任务，尤其是那些可以在应用处于后台时运行的任务。这个库的一些功能会被其他库在底层使用。以下是使用 TaskManager 的 Expo SDK 库列表。

使用 Expo TaskManager 的库

安装

Terminal
- npx expo install expo-task-manager

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


你可以在 Expo Go 应用中测试 TaskManager。不过，请查看每个使用 TaskManager 的库的文档，以确认它是否支持在 Expo Go 中测试。

配置 
iOS

独立应用需要一些额外配置：在 iOS 上，每个后台功能都需要在你的 Info.plist 文件中的 UIBackgroundModes 数组里添加一个特殊的键。

关于如何进行配置，请阅读各个使用 TaskManager 的库的参考文档。

用法

Example
import { Button, View, StyleSheet } from 'react-native';
import * as TaskManager from 'expo-task-manager';
import * as Location from 'expo-location';

const LOCATION_TASK_NAME = 'background-location-task';

const requestPermissions = async () => {
  const { status: foregroundStatus } = await Location.requestForegroundPermissionsAsync();
  if (foregroundStatus === 'granted') {
    const { status: backgroundStatus } = await Location.requestBackgroundPermissionsAsync();
    if (backgroundStatus === 'granted') {
      await Location.startLocationUpdatesAsync(LOCATION_TASK_NAME, {
        accuracy: Location.Accuracy.Balanced,
      });
    }
  }
};

const PermissionsButton = () => (
  <View style={styles.container}>
    <Button onPress={requestPermissions} title="启用后台定位" />
  </View>
);

// 在模块作用域中定义任务，以便后台运行时可以找到它。
// 需要在全局作用域中调用，而不是在 React 组件中。
TaskManager.defineTask(LOCATION_TASK_NAME, ({ data, error }) => {
  if (error) {
    // 发生错误 - 请检查 `error.message` 以获取更多详情。
    return;
  }
  if (data) {
    const { locations } = data;
    // 在后台捕获到的位置上执行一些操作
  }
});

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

export default PermissionsButton;
注意： TaskManager.defineTask 必须在模块作用域中调用，而不是在 React 组件内部。上面的示例将其放在屏幕文件的模块作用域中，这对非路由应用有效。在 Expo Router 项目中，请将其移到单独的文件中（例如 tasks.ts），并在根布局（app/_layout.tsx）顶部导入该文件，这样在任何导航运行之前就会注册该任务。

API

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

Methods

TaskManager.defineTask(taskName, taskExecutor)

Android
iOS
tvOS
ParameterTypeDescription
taskNamestring

Name of the task. It must be the same as the name you provided when registering the task.

taskExecutorTaskManagerTaskExecutor<T>

A function that will be invoked when the task with given taskName is executed.


Defines task function. It must be called in the global scope of your JavaScript bundle, not inside a React component. When the application is launched in the background, no components are mounted, so the task must already be registered at module load time.

Returns:
void

TaskManager.getRegisteredTasksAsync()

Android
iOS
tvOS

Provides information about tasks registered in the app.

Returns:
Promise<TaskManagerTask[]>

A promise which fulfills with an array of tasks registered in the app.

Example

[
  {
    taskName: 'location-updates-task-name',
    taskType: 'location',
    options: {
      accuracy: Location.Accuracy.High,
      showsBackgroundLocationIndicator: false,
    },
  },
  {
    taskName: 'geofencing-task-name',
    taskType: 'geofencing',
    options: {
      regions: [...],
    },
  },
]

TaskManager.getTaskOptionsAsync(taskName)

Android
iOS
tvOS
ParameterTypeDescription
taskNamestring

Name of the task.


Retrieves options associated with the task, that were passed to the function registering the task (e.g. Location.startLocationUpdatesAsync).

Returns:
Promise<TaskOptions>

A promise which fulfills with the options object that was passed while registering task with given name or null if task couldn't be found.

TaskManager.isAvailableAsync()

Android
iOS
tvOS

Determine if the TaskManager API can be used in this app.

Returns:
Promise<boolean>

A promise which fulfills with true if the API can be used, and false otherwise. With Expo Go, TaskManager is not available on Android, and does not support background execution on iOS. Use a development build to avoid limitations: https://expo.fyi/dev-client. On the web, it always returns false.

TaskManager.isTaskDefined(taskName)

Android
iOS
tvOS
ParameterTypeDescription
taskNamestring

Name of the task.


Checks whether the task is already defined.

Returns:
boolean

TaskManager.isTaskRegisteredAsync(taskName)

Android
iOS
tvOS
ParameterTypeDescription
taskNamestring

Name of the task.


Determine whether the task is registered. Registered tasks are stored in a persistent storage and preserved between sessions.

Returns:
Promise<boolean>

A promise which resolves to true if a task with the given name is registered, otherwise false.

TaskManager.unregisterAllTasksAsync()

Android
iOS
tvOS

Unregisters all tasks registered for the running app. You may want to call this when the user is signing out and you no longer need to track his location or run any other background tasks.

Returns:
Promise<void>

A promise which fulfills as soon as all tasks are completely unregistered.

TaskManager.unregisterTaskAsync(taskName)

Android
iOS
tvOS
ParameterTypeDescription
taskNamestring

Name of the task to unregister.


Unregisters task from the app, so the app will not be receiving updates for that task anymore. It is recommended to use methods specialized by modules that registered the task, eg. Location.stopLocationUpdatesAsync.

Returns:
Promise<void>

A promise which fulfills as soon as the task is unregistered.

Interfaces

TaskManagerError

Android
iOS
tvOS

Error object that can be received through TaskManagerTaskBody when the task fails.

PropertyTypeDescription
codestring | number
-
messagestring
-

TaskManagerTask

Android
iOS
tvOS

Represents an already registered task.

PropertyTypeDescription
optionsany

Provides options that the task was registered with.

taskNamestring

Name that the task is registered with.

taskTypestring

Type of the task which depends on how the task was registered. Standard values emitted by Expo SDK libraries are 'location' and 'geofencing' (expo-location), 'backgroundFetch' (expo-background-fetch), 'expo-background-task' on Android or 'backgroundTask' on iOS (expo-background-task), and 'remote-notification' (expo-notifications). User-registered tasks may have any string value.

TaskManagerTaskBody

Android
iOS
tvOS

Represents the object that is passed to the task executor.

PropertyTypeDescription
dataT

An object of data passed to the task executor. Its properties depend on the type of the task.

errorTaskManagerError | null

Error object if the task failed or null otherwise.

executionInfoTaskManagerTaskBodyExecutionInfo

Additional details containing unique ID of task event and name of the task.

TaskManagerTaskBodyExecutionInfo

Android
iOS
tvOS

Additional details about execution provided in TaskManagerTaskBody.

PropertyTypeDescription
appState(optional)'active' | 'background' | 'inactive'
Only for: 
iOS

State of the application.

eventIdstring

Unique ID of task event.

taskNamestring

Name of the task.

Types

TaskManagerTaskExecutor(body)

Android
iOS
tvOS

Type of task executor – a function that handles the task.

ParameterType
bodyTaskManagerTaskBody<T>
Returns:

Promise<any>