基于 Flutter-OH 3.44.9-devDart 3.12.2在 Windows 10 22H2 上全程實測通過開發(fā)工具 DevEco Studio 26HarmonyOS SDK compatibleSdkVersion 5.1.0(18) / compileSdkVersion 26.0.0.105真機環(huán)節(jié)在一臺**鴻蒙 PCOpenHarmony 6.1.1API 24arm642in1 形態(tài)**上驗證。文中所有源碼分析、改動內(nèi)容、構建輸出、真機效果均為實際環(huán)境抓取可放心對照復現(xiàn)。前言OpenHarmony × Flutter 社區(qū)資源社區(qū)主頁CPF-Flutter —— OpenHarmony Flutter 生態(tài)維護組織Flutter-OH 主倉庫CPF-Flutter/flutter_flutter —— SDK 與 Engine 的 OpenHarmony 適配版本三方庫適配與開發(fā)文檔OpenHarmony-Flutter —— 生態(tài)庫適配清單與開發(fā)規(guī)范官方示例與開發(fā)指南openharmony-tpc/flutter_samples —— 環(huán)境搭建指導、FAQ 與示例工程鴻蒙化適配倉庫oh-flutter/onesignal_flutter —— 本文 onesignal_flutter 的 OpenHarmony 適配版本環(huán)境搭好之后還沒搭的看這篇 Flutter 鴻蒙環(huán)境搭建指南下一步就是給項目引入三方庫。本文以 onesignal_flutter推送通知插件為例完整演示從fork 原倉庫 → 編寫 ArkTS 原生插件 → flutter create 生成宿主 → 構建 → 真機驗證的全流程。這是一個9 個 MethodChannel、50 方法的復雜插件比 in_app_update 的單 Channel 場景更具代表性。OneSignal 是海外主流的免費推送通知服務類似國內(nèi)的極光推送、個推提供推送通知、應用內(nèi)消息、用戶標簽管理、會話追蹤等能力。鴻蒙上沒有 OneSignal SDK必須用 ArkTS 原生樁實現(xiàn)來模擬全部接口。一、插件分析onesignal_flutter 做了什么1.1 基本信息onesignal_flutter 是 OneSignal 官方 Flutter SDKAndroid 和 iOS 側分別對接各自的 OneSignal Native SDK。項目內(nèi)容庫名onesignal_flutter適配基于版本5.6.10上游 pub.dev 最新 5.7.1適配倉庫基于 5.6.10 fork功能推送通知、應用內(nèi)消息、用戶標簽、會話追蹤主要 APIinitialize()、login()、addTags()、consentGiven()、Notifications.addClickListener() 等原生依賴Android: OneSignal Android SDKiOS: OneSignal iOS SDK1.2 為什么這個庫必須寫原生代碼onesignal_flutter 的 Dart 層完全通過 9 個 MethodChannel 調用原生能力// lib/onesignal_flutter.dart原插件源碼 static MethodChannel _channel const MethodChannel(OneSignal); static Futurevoid initialize(String appId) async { await _channel.invokeMethod(OneSignal#initialize, {appId: appId}); await Future.wait([ InAppMessages.lifecycleInit(), User.lifecycleInit(), User.pushSubscription.lifecycleInit(), Notifications.lifecycleInit(), ]); }// lib/src/notifications.dart MethodChannel _channel const MethodChannel(OneSignal#notifications); Futurevoid lifecycleInit() async { _permission await _channel.invokeMethod(OneSignal#permission); return await _channel.invokeMethod(OneSignal#lifecycleInit); }// lib/src/pushsubscription.dart MethodChannel _channel const MethodChannel(OneSignal#pushsubscription); Futurevoid lifecycleInit() async { _token await _channel.invokeMethod(OneSignal#pushSubscriptionToken); _id await _channel.invokeMethod(OneSignal#pushSubscriptionId); _optedIn await _channel.invokeMethod(OneSignal#pushSubscriptionOptedIn); return await _channel.invokeMethod(OneSignal#lifecycleInit); }9 個 Channel 各自負責不同功能模塊Dart 側只是一個遙控器——真正的推送注冊、令牌獲取、用戶管理全部由原生側完成。鴻蒙上沒有 OneSignal SDK必須用 hilog 日志樁模擬全部接口。1.3 9 個 Channel 全景序號Channel 名稱功能模塊Dart 側文件1OneSignal主通道初始化、登錄、授權onesignal_flutter.dart2OneSignal#debug調試日志級別src/debug.dart3OneSignal#inappmessages應用內(nèi)消息src/inappmessages.dart4OneSignal#liveactivities實時活動iOSsrc/liveactivities.dart5OneSignal#pushsubscription推送訂閱狀態(tài)src/pushsubscription.dart6OneSignal#user用戶管理src/user.dart7OneSignal#location位置共享src/location.dart8OneSignal#notifications通知管理src/notifications.dart9OneSignal#session會話追蹤src/session.dart1.4 適配策略fork 模式和 in_app_update 一樣采用 fork 原倉庫 添加 ohos 平臺的方式Fork 原倉庫保留全部原始文件android/、ios/、lib/、test/ 等不動在 pubspec.yaml 中添加 ohos 平臺聲明創(chuàng)建 ohos/ 目錄作為 HAR 模塊編寫 ArkTS 原生插件用 flutter create --platforms ohos 生成標準 example 宿主工程在生成的模板上添加插件注冊代碼為什么不創(chuàng)建獨立 OHOS 包fork 模式的好處是原插件的 Dart 層代碼lib/完全復用Android/iOS 側也不受影響一個倉庫同時支持三個平臺。二、適配流程從 fork 到 ArkTS 原生插件2.1 克隆原倉庫cd D:\Flutters git clone --depth 1 https://github.com/OneSignal/OneSignal-Flutter-SDK.git onesignal_flutter_ohos使用 --depth 1 淺克隆因為原倉庫歷史較大?？寺『蟊Ａ羧吭嘉募谠谢A上添加 ohos 相關內(nèi)容。2.2 修改 pubspec.yaml添加 ohos 平臺聲明修改前name: onesignal_flutter version: 5.6.10 flutter: plugin: platforms: android: package: com.onesignal.flutter pluginClass: OneSignalPlugin ios: pluginClass: OneSignalPlugin修改后name: onesignal_flutter_ohos version: 5.6.10ohos flutter: plugin: platforms: android: package: com.onesignal.flutter pluginClass: OneSignalPlugin ios: pluginClass: OneSignalPlugin ohos: pluginClass: OneSignalOhosPlugin三個關鍵改動name 改為 onesignal_flutter_ohos以 _ohos 結尾是社區(qū)約定version 追加 ohos 后綴ohos 平臺聲明 pluginClass: OneSignalOhosPlugin——這就是后面要寫的 ArkTS 插件類名2.3 創(chuàng)建 ohos/ HAR 模塊在項目根目錄創(chuàng)建 ohos/ 目錄完整結構如下ohos/ ├── src/main/ets/components/plugin/ │ └── OneSignalOhosPlugin.ets ← ArkTS 原生插件核心實現(xiàn)218 行 ├── src/main/module.json5 ← HAR 模塊元信息 ├── index.ets ← HAR 模塊入口 ├── oh-package.json5 ← HAR 依賴聲明 ├── build-profile.json5 ← 構建配置 ├── hvigorfile.ts ← hvigor 構建腳本 └── BuildProfile.ets ← 構建變量oh-package.json5HAR 依賴聲明{ name: onesignal_flutter_ohos, version: 1.0.0, description: HarmonyOS NEXT OneSignal plugin (hilog-based stub), main: index.ets, license: MIT, dependencies: { ohos/flutter_ohos: file:../har } }index.etsHAR 入口導出插件類import OneSignalOhosPlugin from ./src/main/ets/components/plugin/OneSignalOhosPlugin; export default OneSignalOhosPlugin;module.json5HAR 模塊元信息{ module: { name: onesignal_flutter_ohos, type: har, description: OneSignal plugin for OpenHarmony, deviceTypes: [phone, tablet, 2in1] } }2.4 編寫 ArkTS 原生插件核心這是整個適配的核心文件 OneSignalOhosPlugin.ets。由于鴻蒙沒有 OneSignal SDK所有方法采用 hilog 日志樁實現(xiàn)——記錄調用日志并返回安全默認值。插件需要實現(xiàn) FlutterPlugin 和 MethodCallHandler 兩個接口在 onAttachedToEngine 中創(chuàng)建全部 9 個 MethodChannelimport { FlutterPlugin, FlutterPluginBinding, MethodCall, MethodCallHandler, MethodChannel, MethodResult, } from ohos/flutter_ohos; import hilog from ohos.hilog; const TAG OneSignal; // All 9 channel names matching Dart side const CHANNEL_MAIN OneSignal; const CHANNEL_DEBUG OneSignal#debug; const CHANNEL_INAPPMESSAGES OneSignal#inappmessages; const CHANNEL_LIVEACTIVITIES OneSignal#liveactivities; const CHANNEL_PUSHSUBSCRIPTION OneSignal#pushsubscription; const CHANNEL_USER OneSignal#user; const CHANNEL_LOCATION OneSignal#location; const CHANNEL_NOTIFICATIONS OneSignal#notifications; const CHANNEL_SESSION OneSignal#session; export default class OneSignalOhosPlugin implements FlutterPlugin, MethodCallHandler { private channels: Mapstring, MethodChannel new Map(); private appId: string ; private loggedIn: boolean false; private logLevel: number 0; private consentRequired: boolean false; private consentGiven: boolean false; private paused: boolean false; private triggers: Recordstring, string {}; private tags: Recordstring, string {}; private aliases: Recordstring, string {}; getUniqueClassName(): string { return OneSignalOhosPlugin; } onAttachedToEngine(binding: FlutterPluginBinding): void { const messenger binding.getBinaryMessenger(); // Create all 9 channels const channelNames [ CHANNEL_MAIN, CHANNEL_DEBUG, CHANNEL_INAPPMESSAGES, CHANNEL_LIVEACTIVITIES, CHANNEL_PUSHSUBSCRIPTION, CHANNEL_USER, CHANNEL_LOCATION, CHANNEL_NOTIFICATIONS, CHANNEL_SESSION ]; for (const name of channelNames) { const ch new MethodChannel(messenger, name); ch.setMethodCallHandler(this); this.channels.set(name, ch); } hilog.info(0x0001, TAG, OneSignal OHOS plugin attached, %{public}d channels registered, channelNames.length); } onDetachedFromEngine(binding: FlutterPluginBinding): void { this.channels.forEach((ch) { ch.setMethodCallHandler(null); }); this.channels.clear(); } onMethodCall(call: MethodCall, result: MethodResult): void { const method call.method; hilog.debug(0x0001, TAG, onMethodCall: %{public}s, method); try { this.routeMethod(method, call, result); } catch (e) { hilog.error(0x0001, TAG, Error handling %{public}s: %{public}s, method, String(e)); result.success(null); } } }routeMethod 方法統(tǒng)一路由所有調用按功能模塊分組處理private routeMethod(method: string, call: MethodCall, result: MethodResult): void { // Main channel methods switch (method) { case OneSignal#initialize: this.appId (call.argument(appId) as string) ?? ; hilog.info(0x0001, TAG, Initialized with appId: %{public}s, this.appId); result.success(null); return; case OneSignal#login: this.loggedIn true; hilog.info(0x0001, TAG, Login: %{public}s, call.argument(externalId) as string ?? ); result.success(null); return; case OneSignal#loginWithJWT: this.loggedIn true; result.success(null); return; case OneSignal#logout: this.loggedIn false; result.success(null); return; case OneSignal#consentGiven: this.consentGiven (call.argument(granted) as boolean) ?? false; result.success(null); return; case OneSignal#consentRequired: this.consentRequired (call.argument(required) as boolean) ?? false; result.success(null); return; } // Debug channel methods if (method.startsWith(OneSignal#)) { const sub method.substring(OneSignal#.length); switch (sub) { case setLogLevel: this.logLevel (call.argument(logLevel) as number) ?? 0; result.success(null); return; case getLogLevel: result.success({ console: this.logLevel, visual: this.logLevel }); return; // InAppMessages methods case addTrigger: case addTriggers: case removeTrigger: case removeTriggers: case clearTriggers: case paused: case arePaused: case lifecycleInit: if (sub arePaused) { result.success(this.paused); return; } if (sub paused) { this.paused (call.args as boolean) ?? false; } result.success(null); return; // LiveActivities methods case enterLiveActivity: case exitLiveActivity: case setupDefault: case startDefault: result.success(null); return; // PushSubscription methods case pushSubscriptionToken: result.success(); return; case pushSubscriptionId: result.success(); return; case pushSubscriptionOptedIn: result.success(false); return; case getPermission: result.success({ status: 0, hasPermission: false }); return; case getSubscription: result.success({ id: , token: , enabled: false }); return; // User methods case addAlias: case addAliases: case removeAlias: case removeAliases: case addTag: case addTags: case removeTag: case removeTags: case getTags: result.success(this.tags); return; case addEmail: case removeEmail: case addSms: case removeSms: result.success(null); return; // Location methods case requestPermission: case isShared: case setShared: result.success(sub isShared ? false : null); return; // Notifications methods case permission: result.success(false); return; case permissionNative: result.success(false); return; case canRequest: result.success(true); return; case requestPermission: result.success(false); return; case clearAll: case removeNotification: case removeGroupedNotifications: result.success(null); return; case addForegroundLifecycleListener: case removeForegroundLifecycleListener: case addClickListener: case removeClickListener: case addWillDisplayListener: case removeWillDisplayListener: result.success(null); return; // Session methods case addOutcome: case addUniqueOutcome: case addOutcomes: result.success(null); return; } } // Default: not implemented but return success to avoid crashes hilog.warn(0x0001, TAG, Method not implemented: %{public}s, method); result.success(null); }2.5 關鍵設計決策解析9 個 Channel 共用一個 Handler和 in_app_update 的 1 個 MethodChannel 1 個 EventChannel 不同OneSignal 有 9 個 MethodChannel。ArkTS 側用一個 OneSignalOhosPlugin 實例同時處理所有 Channel——所有 Channel 的 setMethodCallHandler 都指向 this然后通過方法名前綴 OneSignal# 統(tǒng)一路由。Channel 名稱保持原樣const CHANNEL_MAIN OneSignal; const CHANNEL_NOTIFICATIONS OneSignal#notifications; const CHANNEL_PUSHSUBSCRIPTION OneSignal#pushsubscription; // ... 共 9 個所有 Channel 名稱與原插件完全一致。這意味著 Dart 側的 lib/ 目錄下所有源碼零改動——原插件的 Dart 代碼不需要任何修改就能和 ArkTS 原生側通信。hilog 日志樁而非真實 SDK鴻蒙上沒有 OneSignal SDK所以所有方法采用 hilog 日志樁實現(xiàn)記錄調用參數(shù)返回安全默認值。這不是偷懶——對于插件適配驗證來說確保 MethodChannel 通信鏈路暢通是第一步后續(xù)可以逐步替換為真實的推送能力如鴻蒙的 pushKit。返回值類型必須嚴格匹配 Dart 側這是本次適配中最關鍵的發(fā)現(xiàn)。Dart 側的變量類型決定了 ArkTS 側必須返回對應類型// notifications.dart bool _permission false; // 非空 bool _permission await _channel.invokeMethod(OneSignal#permission);// pushsubscription.dart String? _token; // 可空 String _token await _channel.invokeMethod(OneSignal#pushSubscriptionToken);如果 ArkTS 側 permission 返回 0int而不是 falseboolDart 側類型轉換直接崩潰。同理 pushSubscriptionToken 返回 null 或空字符串都可以因為 String? 可空但 permission 必須返回 bool。三、example 宿主工程flutter create 生成標準模板3.1 生成 ohos 宿主工程原倉庫的 example 目錄是 examples/demo/OneSignal 有多個示例應用。在該目錄下執(zhí)行cd D:\Flutters\onesignal_flutter_ohos\examples\demo flutter create --platformsohos .這條命令會在 examples/demo/ 下生成 ohos/ 目錄約 39 個文件包含標準的鴻蒙應用模板。注意路徑差異OneSignal 原倉庫使用 examples/demo/ 而不是常見的 example/所以生成的宿主工程在 examples/demo/ohos/比一般插件多一層目錄。3.2 修改 examples/demo/pubspec.yaml原 demo 應用依賴了大量第三方插件shared_preferences、provider、flutter_dotenv、http、url_launcher 等這些插件均未適配 OHOS。直接用會導致啟動崩潰。將 pubspec.yaml 精簡為最小依賴name: demo description: OneSignal OHOS Test App publish_to: none version: 1.0.01 environment: sdk: ^3.7.0 dependencies: flutter: sdk: flutter onesignal_flutter_ohos: path: ../../ dev_dependencies: flutter_test: sdk: flutter flutter: uses-material-design: true同時替換 lib/main.dart 為最小化測試頁面僅依賴 flutter onesignal_flutter_ohos避免未適配插件導致啟動崩潰。3.3 修改 import 路徑// 原來 import package:onesignal_flutter/onesignal_flutter.dart; // 改為 import package:onesignal_flutter_ohos/onesignal_flutter.dart;lib/ 目錄下所有 Dart 文件的內(nèi)部 import 也需要從 package:onesignal_flutter/ 改為 package:onesignal_flutter_ohos/。3.4 補全 deviceTypes 和權限// examples/demo/ohos/entry/src/main/module.json5 { module: { name: entry, type: entry, deviceTypes: [phone, tablet, 2in1], requestPermissions: [ {name: ohos.permission.INTERNET} ] } }3.5 添加插件注冊代碼// examples/demo/ohos/entry/src/main/ets/plugins/GeneratedPluginRegistrant.ets import { FlutterEngine, Log } from ohos/flutter_ohos; import OneSignalOhosPlugin from onesignal_flutter_ohos; const TAG GeneratedPluginRegistrant; export class GeneratedPluginRegistrant { static registerWith(flutterEngine: FlutterEngine) { try { flutterEngine.getPlugins()?.add(new OneSignalOhosPlugin()); } catch (e) { Log.e(TAG, Tried to register plugins with FlutterEngine ( flutterEngine ) failed.); Log.e(TAG, Received exception while registering, e); } } }3.6 entry 模塊依賴 HAR// examples/demo/ohos/entry/oh-package.json5 { name: entry, version: 1.0.0, dependencies: { onesignal_flutter_ohos: file:../../../../ohos } }注意路徑深度由于 demo 在 examples/demo/ 下需要四級 …/ 才能回到項目根目錄的 ohos/。四、構建與真機驗證4.1 DevEco Studio 配置調試簽名DevEco Studio → 文件 → 打開 → 選擇 examples/demo/ohos 目錄文件 → 項目結構 → 簽名配置 → 勾選自動生成簽名登錄華為賬號證書自動填充點確定4.2 執(zhí)行 flutter pub getcd D:\Flutters\onesignal_flutter_ohos\examples\demo flutter pub get4.3 構建運行在 DevEco Studio 中點運行按鈕或命令行構建flutter build hap --release編譯輸出Dart ArkTS 全部通過僅命令行簽名失敗 hvigor Finished :entry:defaultFlutterTask... after 16 s 768 ms hvigor Finished :entry:defaultCompileResource... after 355 ms hvigor Finished :entry:defaultBuildJS... after 5 ms4.4 真機效果驗證測試頁面提供四個按鈕覆蓋 OneSignal 的核心功能按鈕功能調用方法初始化SDK 初始化 lifecycleInitOneSignal.initialize()登錄用戶登錄OneSignal.login()設置標簽用戶標簽管理OneSignal.User.addTags()同意授權隱私授權OneSignal.consentGiven()驗證狀態(tài)匯總驗證項狀態(tài)說明依賴解析flutter pub get通過依賴正常解析Dart 編譯通過無編譯錯誤ArkTS 編譯通過218 行原生插件編譯成功真機運行通過UI 正常顯示四個按鈕可點擊9 個 Channel 注冊通過全部 Channel 正常創(chuàng)建initialize lifecycleInit通過初始化鏈路完整執(zhí)行Dart ? ArkTS 類型匹配通過bool/int/string 返回值類型正確五、常見問題 FAQQ1OneSignal 原倉庫有 10 個 Java 文件和 9 個 ChannelArkTS 側怎么對應ArkTS 側用一個插件類處理全部 9 個 Channel。關鍵是在 onAttachedToEngine 中循環(huán)創(chuàng)建所有 Channel并統(tǒng)一指向同一個 Handler// ohos/src/main/ets/components/plugin/OneSignalOhosPlugin.ets onAttachedToEngine(binding: FlutterPluginBinding): void { const messenger binding.getBinaryMessenger(); const channelNames [ CHANNEL_MAIN, CHANNEL_DEBUG, CHANNEL_INAPPMESSAGES, CHANNEL_LIVEACTIVITIES, CHANNEL_PUSHSUBSCRIPTION, CHANNEL_USER, CHANNEL_LOCATION, CHANNEL_NOTIFICATIONS, CHANNEL_SESSION ]; for (const name of channelNames) { const ch new MethodChannel(messenger, name); ch.setMethodCallHandler(this); // 所有 Channel 共用一個 Handler this.channels.set(name, ch); } }然后在 routeMethod 中通過方法名前綴統(tǒng)一路由。這比創(chuàng)建 9 個獨立 Handler 簡潔得多。Q2鴻蒙沒有 OneSignal SDK推送功能能用嗎當前實現(xiàn)是 hilog 日志樁——所有方法調用會被記錄到系統(tǒng)日志并返回安全默認值。推送注冊、令牌獲取等實際功能需要后續(xù)對接鴻蒙的 pushKit華為推送服務來真正實現(xiàn)。適配驗證階段的重點是確保 MethodChannel 通信鏈路暢通、Dart 側調用不會崩潰。功能實現(xiàn)可以逐步迭代。Q3初始化時遇到類型轉換崩潰怎么辦OneSignal 的 initialize() 會級聯(lián)調用 4 個 lifecycleInit()每個 lifecycleInit 都會通過 MethodChannel 獲取返回值。Dart 側對返回值類型有嚴格要求// notifications.dart — bool 類型不能返回 int bool _permission false; _permission await _channel.invokeMethod(OneSignal#permission); // pushsubscription.dart — String? 類型可空 String? _token; _token await _channel.invokeMethod(OneSignal#pushSubscriptionToken);ArkTS 側必須返回完全匹配的類型permission 返回 falsebool而非 0intpushSubscriptionToken 返回 ‘’string而非 null。類型不匹配會直接導致 Dart 側類型轉換異常表現(xiàn)為初始化失敗或應用崩潰。Q4原 demo 應用依賴了 shared_preferences 等未適配插件怎么處理OneSignal 原倉庫的 examples/demo 依賴了 shared_preferences、provider、flutter_dotenv、http 等第三方插件這些插件均未適配 OHOS。直接運行會因 MissingPluginException 崩潰。解決方案是精簡 pubspec.yaml只保留 flutter SDK 和 onesignal_flutter_ohos同時將 main.dart 替換為最小化測試頁面。這樣可以在不依賴任何未適配插件的情況下驗證核心功能。六、總結本文完整記錄了 onesignal_flutter 插件從 fork 到鴻蒙 PC 真機驗證的全流程采用 fork 模式保留原倉庫全部文件用 flutter create --platforms ohos 生成標準宿主工程模板編寫 218 行 ArkTS 原生插件代碼在一個插件類中處理 9 個 MethodChannel 的 50 方法調用通過 hilog 日志樁模擬 OneSignal SDK 的全部接口。Dart 側源碼零改動所有 Channel 名稱與原插件保持一致。核心經(jīng)驗多 Channel 插件的適配關鍵在于統(tǒng)一路由設計——一個 Handler 處理所有 Channel通過方法名前綴分發(fā)比創(chuàng)建多個獨立 Handler 更簡潔。返回值類型必須嚴格匹配 Dart 側的變量類型bool 不能返回 intstring 不能返回 null非空類型時。動手前建議先查一眼 Flutter OH 三方庫適配列表很多熱門庫已有人適配過別重復造輪子。參考資料CPF-Flutter 社區(qū)主頁CPF-Flutter/flutter_flutterFlutter-OH 主倉庫oh-flutter/onesignal_flutter鴻蒙化適配倉庫Flutter OH 三方庫適配列表OneSignal/OneSignal-Flutter-SDK 原庫源碼oh-flutter 社區(qū)適配參考Flutter 鴻蒙環(huán)境搭建指南HarmonyOS pushKit 推送服務文檔Flutter OH 官方示例與 FAQ