Flutter后台任务管理插件simple_work_manager的使用

Simple Work Manager 是一个用于在 Android 和 iOS 上管理后台任务的插件。它映射了 Android 的 WorkManager 和 iOS 的 BGTaskScheduler。

抽象

Simple Work Manager 可以帮助开发者在后台执行重复性任务，例如数据同步、文件处理等。

开始使用

在 pubspec.yaml 中添加依赖

首先，在项目的 pubspec.yaml 文件中添加 simple_work_manager 依赖：

dependencies:
  simple_work_manager:

然后运行以下命令安装依赖：

flutter pub get

iOS 配置

1. 在 Info.plist 中设置允许的任务调度标识符

在 Xcode 的项目设置中，打开 Info.plist 文件，添加以下键值对：

<key>PermittedBackgroundTaskSchedulerIdentifier</key>
<string>[com].[domain].simple_work_manager.process</string>

确保字符串是唯一的，并包含你的域名标识符。

2. 启用后台模式

在 Xcode 的项目设置中，勾选 Background Modes 并选择 Background Processing。

3. 注册插件

在 AppDelegate.swift 文件中添加以下代码：

import UIKit
import Flutter

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

导入插件

在 Dart 文件中导入插件：

import 'package:simple_work_manager/simple_work_manager.dart';

准备回调函数

定义一个顶级函数作为回调函数，该函数将在后台任务中被调用：

[@pragma](/user/pragma)("vm:entry-point")
void callbackDispatcher() {
  debugPrint("simple_work_manager: callbackDispatcher() is called at ${DateTime.now()}");
  // 在这里执行后台任务
}

实例化 SimpleWorkManager

创建一个 SimpleWorkManager 实例，并指定回调函数和回调函数标识符：

SimpleWorkManager _simpleWorkManagerPlugin;

[@override](/user/override)
void initState() {
  super.initState();
  _simpleWorkManagerPlugin =
      SimpleWorkManager(callbackFunction: callbackDispatcher, callbackFunctionIdentifier: "callbackDispatcher");
}

安排后台任务

使用 schedule 方法安排后台任务，指定 Android 和 iOS 的选项：

_simpleWorkManagerPlugin.schedule(
  AndroidOptions(
    requiresNetworkConnectivity: true, // 是否需要网络连接
    requiresExternalPower: true,      // 是否需要外部电源
    targetPeriodInMinutes: 15         // 最小任务间隔（分钟）
  ),
  IOSOptions(
    requiresNetworkConnectivity: true, // 是否需要网络连接
    requiresExternalPower: true,      // 是否需要外部电源
    taskIdentifier: "com.jimdo.uchida001tmhr.simple_work_manager.process" // 唯一的任务标识符
  )
);

注意事项

• requiresNetworkConnectivity 和 requiresExternalPower 必须根据实际需求进行配置。
• targetPeriodInMinutes 的最小值为 15 分钟。
• taskIdentifier 必须与 Xcode 中设置的 PermittedBackgroundTaskSchedulerIdentifier 一致。

取消任务

可以通过以下方法取消已安排的任务：

_simpleWorkManagerPlugin.cancel();

约束条件的行为表

以下是 requiresNetworkConnectivity 和 requiresExternalPower 的行为表：

Android 表格

iOS 表格

建议的约束条件

为了持续执行后台任务，建议将 requiresExternalPower 和 requiresNetworkConnectivity 设置为 true，并插入外部电源。

警告

• 应用程序必须保持运行状态以调用回调函数。
• 在 iOS 上，应用程序必须处于后台才能调用回调函数。

示例代码

以下是一个完整的示例代码，展示如何使用 simple_work_manager 插件：

import 'package:flutter/material.dart';
import 'package:simple_work_manager/simple_work_manager.dart';
import 'package:flutter_local_notifications/flutter_local_notifications.dart';

[@pragma](/user/pragma)("vm:entry-point")
void callbackDispatcher() {
  debugPrint("simple_work_manager: callbackDispatcher() is called at ${DateTime.now()}");
  final flutterLocalNotificationsPlugin = FlutterLocalNotificationsPlugin();
  flutterLocalNotificationsPlugin
      .initialize(
        const InitializationSettings(
          android: AndroidInitializationSettings('@mipmap/ic_launcher'),
          iOS: DarwinInitializationSettings()
        )
      )
      .then((_) => flutterLocalNotificationsPlugin.show(
          0,
          'simple_work_manager',
          'debug notification',
          const NotificationDetails(
              android: AndroidNotificationDetails('simple_work_manager debug notification',
                  'simple_work_manager debug notification'))));
}

void main() {
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  [@override](/user/override)
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  late SimpleWorkManager _simpleWorkManagerPlugin;
  int iRequiresNetworkConnectivity = 0;
  int iRequiresExternalPower = 0;

  [@override](/user/override)
  void initState() {
    super.initState();
    _simpleWorkManagerPlugin =
        SimpleWorkManager(callbackFunction: callbackDispatcher, callbackFunctionIdentifier: "callbackDispatcher");
  }

  bool? dropDownToBool(int dropDownValue) {
    switch (dropDownValue) {
      case 1:
        return false;
      case 2:
        return true;
      default:
        return null;
    }
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    Map<int, String> dropDownMap = {0: "NULL", 1: "FALSE", 2: "TRUE"};
    return MaterialApp(
        home: Scaffold(
            appBar: AppBar(
              title: const Text("Plugin example app"),
            ),
            body: Column(children: [
              Row(children: [
                TextButton(
                    onPressed: () {
                      debugPrint("simple_work_manager: scheduled at ${DateTime.now()}");
                      _simpleWorkManagerPlugin.schedule(
                          AndroidOptions(
                              requiresNetworkConnectivity: dropDownToBool(iRequiresNetworkConnectivity),
                              requiresExternalPower: dropDownToBool(iRequiresExternalPower),
                              targetPeriodInMinutes: 15),
                          IOSOptions(
                              requiresNetworkConnectivity: dropDownToBool(iRequiresNetworkConnectivity),
                              requiresExternalPower: dropDownToBool(iRequiresExternalPower),
                              taskIdentifier: "com.jimdo.uchida001tmhr.simple_work_manager.process"));
                    },
                    child: const Text("Schedule")),
                const Spacer(),
                TextButton(
                    onPressed: () {
                      debugPrint("simple_work_manager: cancel");
                      _simpleWorkManagerPlugin.cancel();
                    },
                    child: const Text("Cancel"))
              ]),
              Row(children: [
                const Text("requiresNetworkConnectivity"),
                const Spacer(),
                DropdownButton(
                    value: iRequiresNetworkConnectivity,
                    items: [
                      for (var element in dropDownMap.entries) ...{
                        DropdownMenuItem(value: element.key, child: Text(element.value))
                      }
                    ],
                    onChanged: (value) {
                      setState(() {
                        iRequiresNetworkConnectivity = value as int;
                      });
                    })
              ]),
              Row(children: [
                const Text("requiresExternalPower"),
                const Spacer(),
                DropdownButton(
                    value: iRequiresExternalPower,
                    items: [
                      for (var element in dropDownMap.entries) ...{
                        DropdownMenuItem(value: element.key, child: Text(element.value))
                      }
                    ],
                    onChanged: (value) {
                      setState(() {
                        iRequiresExternalPower = value as int;
                      });
                    })
              ])
            ])));
  }
}