Flutter 3.47 鸿蒙三方库适配实战：从 0 到 1 处理 workmanager

后台任务是消息推送、数据上报、定时同步的承载能力。workmanager 在 Android 上对接 WorkManager 框架，在 iOS 上对接 BGTaskScheduler。它比较特殊的一点是：新版把宿主接口迁移到了 Pigeon，方法分布在各自的 BasicMessageChannel 上，这对适配方式有直接影响。

本文以 workmanager 0.10.10 为例，记录我如何保留原有 Dart API、补齐 Flutter OH 插件入口、在鸿蒙端接入真实系统能力，并在 HarmonyOS API 26 真机上完成构建、安装、启动和按钮调用验证。

适配仓库： oh-flutter/workmanager

适配分支： feat/ohos_workmanager_0.10.10

适配 TAG： 0.10.10-ohos.2

一、先看最终效果

图 1：HarmonyOS API 26 真机启动 Demo。页面显示 workmanager 0.10.10。

图 2：点击“注册一次性任务”后返回 registerOneOffTask 调用完成，任务真实注册进系统 workScheduler。

图 3：点击“取消全部任务”后返回 cancelAll 调用完成，stopAndClearWorks() 执行成功。

验证点实测结果证据
Flutter OH 3.47 工程构建通过entry-default-signed.hap
安装、启动（真机）通过图 1
registerOneOffTask任务真实注册进系统 workScheduler图 2
cancelAllstopAndClearWorks() 执行成功图 3
后台入口WorkSchedulerExtensionAbility 已声明代码

二、这个库原来是怎么工作的

workmanager 0.10.x 的通道结构是纯 Pigeon：

Dart Workmanager
  -> BasicMessageChannel('dev.flutter.pigeon.workmanager_platform_interface.WorkmanagerHostApi.<方法名>')
  -> Android WorkManager / iOS BGTaskScheduler

需要注册的 Pigeon 方法包括 initialize、registerOneOffTask、registerPeriodicTask、cancelByUniqueName、cancelByTag、cancelAll、isScheduledByUniqueName、getWorkInfoByUniqueName 等。Pigeon 的回复协议是列表：功能方法成功返回 [value]，失败返回 [code, message, details]。

三、实际环境

Flutter 鸿蒙环境搭建不在本文重复展开，直接参考 Flutter OH 环境搭建指南。

组件版本
Flutter OH3.47.4-ohos-1.0.4
Dart3.13.3
DevEco Studio26.0.0 Release
HarmonyOS SDKAPI 26
测试设备华为畅享 90 Pro Max，HarmonyOS 7.0.0.105（API 26）
目标库workmanager 0.10.10
flutter --version
hdc list targets

四、确认上游版本并同步到 AtomGit

上游包地址是 https://github.com/fluttercommunity/flutter_workmanager，版本 0.10.10 使用 MIT（Copyright © 2019 vrtdev） License。适配前我在 AtomGit 目标组织中搜索了同名库，没有找到可以直接使用的 OHOS 实现。

仓库适配提交为 df928c1，分支与 TAG 0.10.10-ohos.2 均指向该提交。

git clone https://atomgit.com/oh-flutter/workmanager.git
cd workmanager
git switch feat/ohos_workmanager_0.10.10
git log --oneline -5

五、创建适配分支并检查工程结构

git switch -c feat/ohos_workmanager_0.10.10

关键目录如下：

workmanager/
├── lib/                                        # 原有 Dart API 和 MethodChannel
├── ohos/
│   ├── index.ets                               # OHOS 插件导出入口
│   └── src/main/ets/components/plugin/
│       └── WorkmanagerPlugin.ets                           # 通道实现
├── example/lib/main.dart                        # 真机验证 Demo
├── example/ohos/                                # Flutter OH 宿主工程
├── pubspec.yaml                                # 声明 ohos 平台
└── README.OpenHarmony_CN.md                    # 鸿蒙适配说明

pubspec.yaml 中的关键声明是：

flutter:
  plugin:
    platforms:
      ohos:
        pluginClass: WorkmanagerPlugin

pluginClass 必须和 ohos/index.ets 导出的类名一致，否则 Dart 端能编译，运行时却不会注册插件。

六、适配过程：注册通道并对齐语义

// 注册一次性任务：workScheduler.startWork
const info: workScheduler.WorkInfo = {
  workId: this.workIdOf(uniqueName),
  bundleName: this.context!.applicationInfo.name,
  abilityName: 'WorkSchedulerAbility',
  isPersisted: true,
  isCharging: true,          // 必须至少有一个触发条件
  parameters: { uniqueName, taskName, inputData: JSON.stringify(inputData) },
};
workScheduler.startWork(info);

后台执行入口（WorkSchedulerExtensionAbility）：

onWorkStart(work: workScheduler.WorkInfo): void {
  const taskName = work.parameters?.['taskName'] as string;
  this.recordExecution(taskName);      // 写 preferences 留痕
  this.startHeadlessEngine();          // 启动 headless FlutterEngine 跑 callbackDispatcher
}
方法OpenHarmony 实现
initialize把 Dart 的 callbackHandle 存进 preferences
registerOneOffTask / registerPeriodicTaskworkScheduler.startWork()，周期任务用 repeatCycleTime（≥20 分钟）
cancelByUniqueName / cancelAllstopWork() / stopAndClearWorks()
isScheduledByUniqueNamegetWorkStatus(workId)

七、构建配置与签名

示例工程的目标 SDK 对齐到 26，与 @ohos/flutter_ohos 的最低要求一致：

{
  "name": "default",
  "compatibleSdkVersion": "26.0.0",
  "targetSdkVersion": "26.0.0",
  "runtimeOS": "HarmonyOS"
}

Demo 的 AppScope/app.json5 统一成 com.example.flutter_oh_demo，与 DevEco 调试签名对应。证书、p12、p7b 和密码没有提交到仓库，读者应在自己的 DevEco Studio 中生成调试签名。

八、通过 AtomGit 引入适配版

在另一个 Flutter OH 应用中使用时，建议锁定 TAG：

dependencies:
  workmanager:
    git:
      url: https://atomgit.com/oh-flutter/workmanager.git
      ref: 0.10.10-ohos.2

flutter pub get

然后在 pubspec.lock 检查 source: git、AtomGit 地址和 resolved-ref，确认没有解析到 pub.dev 的同名版本。

九、构建、安装和真机验证

cd example
flutter pub get
flutter analyze
flutter build hap --debug
hdc install -r build/ohos/hap/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.example.flutter_oh_demo

构建输出为 ✓ Built build/ohos/hap/entry-default-signed.hap.，随后 hdc 报告安装成功并启动 Ability。真机上按本文的截图顺序逐一点击按钮完成验证。

十、适配结果和当前边界

后台调度已完整接入，有三个平台约束：

  1. WorkInfo 至少要有一个触发条件（网络/充电/电量等），否则系统报 401 The workinfo condition cannot be empty。本实现默认 isCharging: true。
  2. 周期任务的最小间隔是 20 分钟（repeatCycleTime 下限），比 Android 的 15 分钟更长。
  3. WorkSchedulerExtensionAbility 必须在 module.json5 的 extensionAbilities 里声明 type: "workScheduler"，否则系统找不到执行入口。

十一、FAQ

Q1：为什么错误来自 Dart 层？

  • 现象： 这个库的 Dart 侧用 Pigeon 通道，第一次请求会因 codec 类型不匹配在解码阶段就失败。
  • 解决方法： 实现需要支持 Pigeon 自定义类型 129–147 的解码器。
  • 验证结果： 注册与取消都返回成功。

Q2：Pigeon 通道注册了为什么没走到？

  • 现象： 裸 null 消息（如 cancelAll）会让 new DataView(null) 抛错。
  • 解决方法： 解码前判断消息是否为空。
  • 验证结果： cancelAll 正常返回。

Q3：registerOneOffTask 报 401？

  • 现象： WorkInfo 没有触发条件。
  • 解决方法： 至少设置 isCharging 或 networkType。
  • 验证结果： 注册成功。

十二、总结

workmanager 0.10.10 已接入鸿蒙的后台调度：用 @ohos.resourceschedule.workScheduler 注册任务，WorkSchedulerExtensionAbility 负责后台执行并启动 headless FlutterEngine 运行业务回调。真机上验证了注册与取消两条路径。

十三、参考资料和仓库地址

欢迎加入CPF-Flutter 鸿蒙社区：https://atomgit.com/CPF-Flutter

# flutter # harmonyos # 华为 # 架构 # 算法
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

cover

从 Python 光学库到鸿蒙 PC 原生应用：ohos_Optiland 的移植适配实战

avatar 人工智能6S服务平台
cover

把 Qucs-S 搬上鸿蒙 PC：「电路芯绘」移植实战开发实录

avatar 人工智能6S服务平台

纯血鸿蒙本地应用实测：六十四卦知识库「易经学」，离线可用数据不出手机

最近在纯血鸿蒙上试了一款叫「易经学」的本地应用，把它当作《易经》的随身知识库来用。选它的出发点很简单：六十四卦这类传统文化内容，能不离开手机就别离开。下面按我自己的使用路径，实测几个核心模块，仅作个人体验分享。

avatar 人工智能6S服务平台