Flutter/OpenHarmony 三方库适配实战：jpush_flutter 推送兼容层-北京尧图网络

Flutter/OpenHarmony 三方库适配实战jpush_flutter 推送兼容层一、项目信息项目内容仓库名称jpush-flutter-pluginDart 包名jpush_flutterAtomGit 仓库地址https://atomgit.com/oh-flutter/jpush-flutter-plugin上游适配版本3.5.9OHOS 适配版本3.5.9-ohos.1方法通道jpushOHOS 原生入口JPushPlugin示例包名com.example.jpush_exampleHAP 产物example/build/ohos/hap/entry-default-unsigned.hap当前状态已完成分析、测试、构建和模拟器启动验证并已推送到main环境搭建与版本下面是本次适配实际使用的环境。环境搭建过程这里不再展开直接看 Flutter OH 环境搭建指南。项目版本/说明Flutter OH3.44.9ohos-0.0.1-canary1Dart3.12.2DevEco Studio26.0.0HarmonyOS SDKAPI 26目标仓库jpush-flutter-plugin二、这个库为什么需要 OHOS 适配JPush 的 Dart 层并没有直接依赖 Android 类它把业务操作集中到一条MethodChannel(jpush)上staticfinalJPush_instanceJPush.private(constMethodChannel(jpush),constLocalPlatform());这条设计让适配边界变得很清楚业务页面 | | JPush Dart API v MethodChannel(jpush) | -- Android JPush SDK -- iOS JPush SDK -- OHOS JPushPlugin本次新增真正困难的不是创建 MethodChannel而是 OpenHarmony 当前没有可验证的JPush 原生 SDK。如果把setup、getRegistrationID或setTags直接返回成功业务会误以为设备已经注册并能收到远端推送这比明确返回不支持更容易造成线上问题。因此本次适配分成两层工程层完成 OHOS 插件发现、HAR 构建、插件注册和通道存活。能力层只实现可验证的平台版本与适配版本查询其他远端推送能力返回jpush_unsupported。三、先让 Flutter OHOS 找到插件根pubspec.yaml保留 Android 和 iOS 声明只增加 OHOS 入口并把版本标记为 OHOS 适配版本version:3.5.9-ohos.1environment:sdk:3.2.0 4.0.0flutter:plugin:platforms:android:package:com.jiguang.jpushpluginClass:JPushPluginios:pluginClass:JPushPluginohos:pluginClass:JPushPlugin这里有几个容易被忽略的点pluginClass必须和index.ets最终导出的默认类一致。Dart SDK 下限从旧工程的过低版本提升到3.2.0才能与当前 Flutter OH工具链一致。platform依赖解析到3.2.0示例代码中的过时 API 同步更新。版本追加-ohos.1避免与上游原版本混淆。OHOS 模块是 HAR不是应用工程所以它的hvigorfile.ts使用harTasksimport{harTasks}fromohos/hvigor-ohos-plugin;exportdefault{system:harTasks,plugins:[],};index.ets负责把 ArkTS 插件类交给 Flutter 生成的注册器importJPushPluginfrom./src/main/ets/components/plugin/JPushPlugin;exportdefaultJPushPlugin;如果这一层缺少任何一环都会出现类似问题缺失位置典型现象pubspec.yaml无ohosFlutter 不生成 OHOS 插件注册代码hvigorfile.ts使用appTasksHAR 构建任务类型错误index.ets没有默认导出ArkTS 注册器找不到插件类HAR 模块名与依赖不一致ohpm 依赖解析失败通道名不一致Dart 调用抛出MissingPluginExceptionOHOS 工程目录创建本次适配前上游仓库没有ohos/目录。适配分支上按 Flutter OH 的插件工程约束创建平台目录再把 ArkTS 入口接入pubspec.yamlgitswitch-cyour-ohos-adaptation-branchflutter create--platformsohos.工程生成后至少保留以下边界ohos/ ├── index.ets ├── oh-package.json5 └── src/main/ ├── module.json5 └── ets/components/plugin/示例工程还需要生成example/ohos/并在插件pubspec.yaml的flutter.plugin.platforms.ohos中声明pluginClass只创建目录、没有注册入口Dart 方法通道仍然不会工作。四、ArkTS 插件的最小完整实现JPushPlugin.ets保留和 Dart 完全一致的通道名constCHANNELjpush;constUNSUPPORTEDjpush_unsupported;exportdefaultclassJPushPluginimplementsFlutterPlugin,MethodCallHandler{privatechannel:MethodChannel|nullnull;getUniqueClassName():string{returnJPushPlugin;}onAttachedToEngine(binding:FlutterPluginBinding):void{this.channelnewMethodChannel(binding.getBinaryMessenger(),CHANNEL,);this.channel.setMethodCallHandler(this);}onDetachedFromEngine(binding:FlutterPluginBinding):void{if(this.channel!null){this.channel.setMethodCallHandler(null);this.channelnull;}}方法分发只返回两类结果onMethodCall(call:MethodCall,result:MethodResult):void{switch(call.method){casegetPlatformVersion:result.success(OHOS);return;casegetSDKVersion:result.success(jpush_flutter OHOS adapter 3.5.9-ohos.1,);return;default:result.error(UNSUPPORTED,${call.method}: JPush SDK is not available on OpenHarmony.,null,);return;}}Dart 侧新增两个轻量查询方法示例和业务都能验证插件是否真正注册FutureStringgetPlatformVersion()async{finalString?versionawait_channel.invokeMethodString(getPlatformVersion);returnversion??Unknown;}FutureStringgetSDKVersion()async{finalString?versionawait_channel.invokeMethodString(getSDKVersion);returnversion??Unknown;}这段 ArkTS 分发的核心价值是让失败可诊断result.success只用于已经验证的平台能力。result.error携带稳定错误码Dart 可以精准判断 OHOS 尚未接入。onDetachedFromEngine清理 handler避免引擎重建后残留旧通道。不实现假的 Registration ID也不返回伪造 Tag 列表。五、Dart 层保持原调用方式上游JPush继续使用静态单例业务代码不需要为 OHOS 写另一套 APIfinalJPushjpushJPush();finalStringplatformawaitjpush.getPlatformVersion();debugPrint(platform);// OHOS远端推送方法仍按上游方式调用但 OHOS 会返回PlatformExceptiontry{finalMapdynamic,dynamictagsawaitjpush.setTags([openharmony,flutter,]);debugPrint($tags);}onPlatformExceptioncatch(error){if(error.codejpush_unsupported){debugPrint(OHOS 尚未接入 JPush 原生 SDK);}else{rethrow;}}这里刻意没有修改 Dart API 的签名。未来接入真实 OHOS SDK 时只需要替换ArkTS 分支业务层不用迁移。六、同步修复 Dart 和示例工程适配过程中同时处理了几处会阻断当前工具链的问题LocalNotification构造参数从过时的required改为required。示例中的MaterialStateProperty更新为WidgetStateProperty。清理示例未使用的mockito、test和jmessage_flutter。替换过时测试 API使用TestDefaultBinaryMessengerBinding注册 Mock 通道。使用当前 Flutter OH 工具链生成example/ohos。增加getPlatformVersion和getSDKVersion公开方法并让示例首屏显示真实注册结果。根测试验证通道契约test(OHOS adapter exposes the jpush channel contract,()async{expect(awaitchannel.invokeMethodString(getPlatformVersion),OHOS,);expect(awaitchannel.invokeMethodString(getSDKVersion),contains(3.5.9-ohos.1),);});这类测试不能验证远端推送但可以阻止通道名、版本号和插件分发被后续改动意外破坏。七、示例页面验证插件注册示例保留上游的推送操作按钮并通过状态区域展示平台调用结果finalStringversionawaitjpush.getPlatformVersion();setState((){debugLabelOHOS plugin:$version;});图 1OpenHarmony 模拟器上的 jpush_flutter 示例首屏。页面已加载插件通道和示例按钮均可访问。截图中的状态区显示插件注册结果通知、Tag、Alias 和角标按钮仍然保留是因为它们展示上游能力边界并不代表这些业务已经在 OHOS 上接通。点击后应看到稳定、可解释的jpush_unsupported而不是静默成功。八、HAP 构建与测试本次实际执行的核心命令flutter analyze fluttertestcdexample flutter analyze fluttertestflutter build hap--debug--no-codesign验证结果检查项结果根包 analyze通过No issues found根包测试通过示例 analyze通过No issues found示例测试通过HAP 构建通过产物entry-default-unsigned.hap安装和启动命令hdcinstall-r\example/build/ohos/hap/entry-default-unsigned.hap hdc shell aa start\-aEntryAbility\-bcom.example.jpush_example最终验证中的真实日志start ability successfully. 10-19 01:08:51.405 5205 5205 D ... Flutter: FlutterNapi -- called onFirstFrame isPreload:0进程5205在首帧后稳定存活验证没有停留在“构建成功但启动即退出”。版本与提交基线项目版本/地址上游包jpush_flutter上游最新版本3.5.9文章目标基线3.5.9-ohos.1当前已发布 TAG3.5.9-ohos.1适配分支main目标最新 TAG3.5.9-ohos.1最终提交2ab687b版本号更新只代表文章和适配分支的基线已对齐涉及上游 API 变更时仍需在该 TAG 上重新运行 Dart 测试、ArkTS 编译、HAP 安装和真机回归。参考资料和仓库地址适配仓库主页适配分支 main当前已发布 TAG 3.5.9-ohos.1目标最新 TAG 3.5.9-ohos.1最终提交 2ab687bArkTS 通道实现鸿蒙适配说明pub.dev 包页面pub.dev 3.5.9 版本页上游仓库Flutter 官方插件与平台通道文档Flutter OH 鸿蒙 SDK 仓库HarmonyOS 开发者官方文档欢迎加入 CPF-Flutter 鸿蒙社区。九、常见问题与定位顺序1.MissingPluginException按以下顺序检查pubspec.yaml是否存在ohos.pluginClass。example/ohos的生成插件注册文件是否包含JPushPlugin。index.ets是否默认导出同一个类。ArkTS 和 Dart 的通道是否都叫jpush。2. HAP 能安装但启动失败先卸载旧包再安装当前构建。不同 Flutter Engine 和插件 HAR 混装可能在插件注册阶段崩溃。验证日志必须检查onFirstFrame仅aa start返回成功不足以证明首帧完成。3. 为什么远端推送仍失败这是预期能力边界。当前 OHOS 实现只完成了工程与通道兼容没有接入 JPush原生 OHOS SDK。下一步需要 SDK 方案、账号 AppKey、包名、签名、通知权限和真实设备通道共同验证。适配过程 FAQ 与解决方案为什么上游没有ohos/目录OHOS 平台目录由适配分支创建不在上游主干中混入平台代码。创建目录后必须同时补齐oh-package.json5、index.ets、module.json5和pubspec.yaml的平台声明。方法通道没有返回怎么排查按pubspec.yaml - GeneratedPluginRegistrant - index.ets - MethodChannel 名称 - AbilityContext的顺序核对ArkTS 日志中没有对应 channel 时优先检查插件注册而不是业务 Dart 代码。模拟器截图为什么不能等同于真机当前文章中的截图是 HarmonyOS 模拟器验证证据能证明 HAP 安装、启动和通道链路涉及蓝牙、推送、账号、传感器、后台任务和系统窗口时仍需补真机截图和设备型号。升级上游版本时应该做什么先确认上游最新版本和 API 变更再更新适配分支、TAG、README.OpenHarmony_CN.md最后重新执行测试、构建、安装和截图回归。十、后续适配路线接入或实现可验证的 JPush OHOS 原生 SDK。实现 Registration ID、setup、Tag 和 Alias。接入通知授权、本地通知和通知点击事件。增加 OHOS 通知事件的 EventChannel 或方法回传。使用真机验证通知显示、后台唤醒、厂商通道和冷热启动参数。已推送到 AtomGitmainREADME、验证记录和清单同步使用正式地址。十一、目录结构jpush-flutter-plugin_ohos/ ├── lib/jpush_flutter.dart ├── ohos/ │ ├── build-profile.json5 │ ├── hvigorfile.ts │ ├── index.ets │ └── src/main/ets/components/plugin/JPushPlugin.ets ├── example/ │ ├── lib/main.dart │ └── ohos/ ├── test/jpush_flutter_test.dart ├── photos/jpush_ohos.jpeg ├── verification.md ├── CHANGELOG.md └── README.md十二、总结这次适配没有把“能编译”当作最终结果而是建立了完整证据链pubspec OHOS 声明 | v HAR 构建和 index.ets 导出 | v GeneratedPluginRegistrant 注册 | v MethodChannel(jpush) 分发 | v analyze test HAP build | v hdc 安装 aa start onFirstFrame 进程存活对于没有原生 OHOS SDK 的推送能力正确结果不是返回假成功而是保留统一API、给出稳定错误码并把真实 SDK 接入列为明确的下一步。仓库名称jpush-flutter-plugin仓库地址https://atomgit.com/oh-flutter/jpush-flutter-plugin欢迎加入 CPF-Flutter 社区一起交流Flutter 三方库 OpenHarmony 适配、HAP 构建和模拟器/真机验证经验https://atomgit.com/CPF-Flutter

Flutter/OpenHarmony 三方库适配实战：jpush_flutter 推送兼容层

相关推荐

黑客松（Hackathon）通常要求在 24–72 小时内完成从需求拆解、原型设计、前端页面、接口联调到演示交付的全流程

【NeurIPS 2024】Super Consistency：景观超一致性，学习率为何能跨规模迁移｜从缩放极限理论视角

Codex 一键安装包，本地 AI 编程环境真的不用硬配

更多资讯

从“你油饼吗”到意图路由：Python中文谐音纠错实战

文本归一化与规则引擎：营销引流文本检测实战

H100 显存预算怎么做：先算权重与 KV，再谈混合精度

帧级语音分类实战：Python实现与时间轴定位

OCR与条码二维码识别：OpenCV+pyzbar+PaddleOCR实践

DLSS Unlocked 游戏内叠加菜单怎么用？OptiScaler.ini 帧生成与超分参数全解析

今日更新

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本周精选

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？