Flutter后台任务执行插件flutter_background的使用

flutter_background

flutter_background 是一个用于保持Flutter应用程序在后台运行的插件。目前，它仅适用于Android平台。

该插件通过结合使用 Android前台服务、部分唤醒锁 和 禁用电池优化，来确保Flutter隔离区（isolate）持续运行。

注意：此插件目前仅支持Android平台。欢迎为iOS提交PR，不过不确定是否能在iOS上实现类似效果。

开始使用

添加依赖

要在项目中使用这个插件，请将 flutter_background 作为依赖添加到您的 pubspec.yaml 文件中：

dependencies:
  flutter_background: ^latest_version

Android配置

在 AndroidManifest.xml 中添加以下权限和Service配置：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="de.julianassmann.flutter_background_example">

    <!-- 根据需求选择合适的前台服务类型 -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />

    <application>
        ...

        <!-- 根据需求选择合适的前台服务类型 -->
        <service
            android:name="de.julianassmann.flutter_background.IsolateHolderService"
            android:exported="false"
            android:foregroundServiceType="dataSync|specialUse|..." />
    </application>
</manifest>

重要：必须为您的使用场景指定适当的 foregroundServiceType。更多关于前台服务类型的文档请参考 官方文档 和 可用的服务类型列表。

使用方法

首先导入 flutter_background.dart：

import 'package:flutter_background/flutter_background.dart';

初始化插件并处理权限

在使用插件之前，您需要通过调用 FlutterBackground.initialize(...) 来初始化它：

final androidConfig = FlutterBackgroundAndroidConfig(
    notificationTitle: "flutter_background example app",
    notificationText: "Background notification for keeping the example app running in the background",
    notificationImportance: AndroidNotificationImportance.normal,
    notificationIcon: AndroidResource(name: 'background_icon', defType: 'drawable'), // 默认是mipmap文件夹下的ic_launcher
);

bool success = await FlutterBackground.initialize(androidConfig: androidConfig);

这确保了所有必要的权限被授予，并且如果需要的话会请求这些权限。它还配置了前台通知。上述配置将在调用 FlutterBackground.enableBackgroundExecution() 时创建如下的前台通知：

参数说明：

• notificationTitle: 前台服务通知的标题。
• notificationText: 前台服务通知的内容。
• notificationImportance: 前台服务通知的重要性。
• notificationIcon: 前台服务通知左上角显示的图标。必须是一个可绘制的Android资源（参见这里了解更多）。例如，如果名为 “background_icon” 的图标位于 “drawable” 资源文件夹中，则应设置为 AndroidResource(name: 'background_icon', defType: 'drawable')。
• enableWifiLock: 指示当开始后台执行时是否获取Wi-Fi锁。这允许应用程序即使用户长时间未使用设备也能保持Wi-Fi无线电处于唤醒状态（例如，用于后台网络通信）。

在这个例子中，background_icon 是 drawable 文件夹中的一个可绘制资源（参见示例应用）。有关如何创建和存储图标的更多信息，请参阅 Android文档。

为了正确工作，此插件需要一些权限。FlutterBackground.initialize(...) 将根据需要向用户请求权限。您可以在每次调用 enableBackgroundExecution() 之前调用 initialize()。

为了提前告知用户即将到来的系统权限请求，您可以通过调用以下代码检查应用程序是否已经拥有这些权限：

bool hasPermissions = await FlutterBackground.hasPermissions;

如果应用程序已经有了所有必要的权限，那么就不会向用户显示权限请求。

运行应用程序在后台

通过调用以下代码可以让应用程序在后台运行：

bool success = await FlutterBackground.enableBackgroundExecution();

请注意，在调用 FlutterBackground.enableBackgroundExecution() 之前，必须先调用 FlutterBackground.initialize()。

停止后台执行：

await FlutterBackground.disableBackgroundExecution();

同样地，在调用 FlutterBackground.disableBackgroundExecution() 之前，也必须先调用 FlutterBackground.initialize()。

要检查当前是否启用了后台执行，可以使用：

bool enabled = FlutterBackground.isBackgroundExecutionEnabled;

示例

下面是一个完整的示例程序，展示了如何使用 flutter_background 插件进行后台任务处理：

import 'package:flutter/material.dart';
import 'package:flutter_background/flutter_background.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final androidConfig = FlutterBackgroundAndroidConfig(
    notificationTitle: "My App Running in Background",
    notificationText: "App is running in background to perform tasks",
    notificationImportance: AndroidNotificationImportance.high,
    notificationIcon: AndroidResource(name: 'background_icon', defType: 'drawable'),
  );

  bool initialized = await FlutterBackground.initialize(androidConfig: androidConfig);
  if (initialized) {
    runApp(MyApp());
  }
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Background Example',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  @override
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  bool _isBackgroundExecutionEnabled = false;

  @override
  void initState() {
    super.initState();
    _checkBackgroundExecutionStatus();
  }

  Future<void> _checkBackgroundExecutionStatus() async {
    bool isEnabled = await FlutterBackground.isBackgroundExecutionEnabled;
    setState(() {
      _isBackgroundExecutionEnabled = isEnabled;
    });
  }

  Future<void> _toggleBackgroundExecution() async {
    if (_isBackgroundExecutionEnabled) {
      await FlutterBackground.disableBackgroundExecution();
    } else {
      await FlutterBackground.enableBackgroundExecution();
    }
    _checkBackgroundExecutionStatus();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Flutter Background Example'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text(
              'Background Execution Status:',
            ),
            Text(
              _isBackgroundExecutionEnabled ? 'Enabled' : 'Disabled',
              style: Theme.of(context).textTheme.headline4,
            ),
            SizedBox(height: 20),
            ElevatedButton(
              onPressed: _toggleBackgroundExecution,
              child: Text(_isBackgroundExecutionEnabled ? 'Disable Background Execution' : 'Enable Background Execution'),
            ),
          ],
        ),
      ),
    );
  }
}

这个示例程序提供了一个简单的UI界面，允许用户启用或禁用应用程序的后台执行功能。同时，它还会显示当前的后台执行状态。

如果您有任何问题或者建议，请随时在 GitHub Issues 上创建一个新的issue。我们非常欢迎您贡献代码！

维护者

• Julian Aßmann

希望这篇文档对您有帮助！如果您有任何疑问，请随时提问。