Flutter background_fetch 技术文档

1. 安装指南

1.1 使用 pubspec.yaml 安装

在项目的 pubspec.yaml 文件中添加以下依赖：

dependencies:
  background_fetch: '^1.1.3'

1.2 从 Git 安装

如果需要使用最新版本的插件，可以从 GitHub 安装：

dependencies:
  background_fetch:
    git:
      url: https://github.com/transistorsoft/flutter_background_fetch

1.3 平台特定设置

iOS 设置

请参考 iOS 安装指南 进行详细设置。

Android 设置

请参考 Android 安装指南 进行详细设置。

2. 项目的使用说明

2.1 基本功能

background_fetch 插件会在后台每隔大约 15 分钟唤醒一次应用，提供短暂的运行时间。插件会在后台获取事件发生时执行你提供的 callbackFn。

2.2 自定义任务

除了默认的后台获取任务，你还可以使用 scheduleTask 方法来调度任意的“一次性”或周期性任务。

2.3 平台差异

iOS

• 无法增加获取事件的发生频率，最频繁的事件间隔为 15 分钟。
• scheduleTask 似乎只在设备插电时触发。
• 当应用被终止时，iOS 不再触发事件。

Android

• 提供 Headless 实现，允许在应用终止后继续处理事件。

3. 项目 API 使用文档

3.1 配置后台获取

使用 BackgroundFetch.configure 方法配置后台获取：

int status = await BackgroundFetch.configure(BackgroundFetchConfig(
    minimumFetchInterval: 15,
    stopOnTerminate: false,
    enableHeadless: true,
    requiresBatteryNotLow: false,
    requiresCharging: false,
    requiresStorageNotLow: false,
    requiresDeviceIdle: false,
    requiredNetworkType: NetworkType.NONE
), (String taskId) async {  // <-- Event handler
    print("[BackgroundFetch] Event received $taskId");
    BackgroundFetch.finish(taskId);
}, (String taskId) async {  // <-- Task timeout handler
    print("[BackgroundFetch] TASK TIMEOUT taskId: $taskId");
    BackgroundFetch.finish(taskId);
});

3.2 启动和停止后台获取

使用 BackgroundFetch.start 和 BackgroundFetch.stop 方法来启动和停止后台获取：

BackgroundFetch.start().then((int status) {
    print('[BackgroundFetch] start success: $status');
}).catchError((e) {
    print('[BackgroundFetch] start FAILURE: $e');
});

BackgroundFetch.stop().then((int status) {
    print('[BackgroundFetch] stop success: $status');
});

3.3 获取状态

使用 BackgroundFetch.status 方法获取当前状态：

int status = await BackgroundFetch.status;
print('[BackgroundFetch] status: $status');

4. 项目安装方式

4.1 使用 pubspec.yaml 安装

在项目的 pubspec.yaml 文件中添加以下依赖：

dependencies:
  background_fetch: '^1.1.3'

4.2 从 Git 安装

如果需要使用最新版本的插件，可以从 GitHub 安装：

dependencies:
  background_fetch:
    git:
      url: https://github.com/transistorsoft/flutter_background_fetch

4.3 平台特定设置

iOS 设置

请参考 iOS 安装指南 进行详细设置。

Android 设置

请参考 Android 安装指南 进行详细设置。