 OpenHarmony 鴻蒙適配實(shí)戰(zhàn)：OneSignal 推送通知插件 ArkTS 原生適配全流程)
基于 Flutter-OH 3.44.9-devDart 3.12.2在 Windows 10 22H2 上全程實(shí)測(cè)通過(guò)開(kāi)發(fā)工具 DevEco Studio 26HarmonyOS SDK compatibleSdkVersion 5.1.0(18) / compileSdkVersion 26.0.0.105真機(jī)環(huán)節(jié)在一臺(tái)**鴻蒙 PCOpenHarmony 6.1.1API 24arm642in1 形態(tài)**上驗(yàn)證。文中所有源碼分析、改動(dòng)內(nèi)容、構(gòu)建輸出、真機(jī)效果均為實(shí)際環(huán)境抓取可放心對(duì)照復(fù)現(xiàn)。前言O(shè)penHarmony × Flutter 社區(qū)資源社區(qū)主頁(yè)CPF-Flutter —— OpenHarmony Flutter 生態(tài)維護(hù)組織Flutter-OH 主倉(cāng)庫(kù)CPF-Flutter/flutter_flutter —— SDK 與 Engine 的 OpenHarmony 適配版本三方庫(kù)適配與開(kāi)發(fā)文檔OpenHarmony-Flutter —— 生態(tài)庫(kù)適配清單與開(kāi)發(fā)規(guī)范官方示例與開(kāi)發(fā)指南openharmony-tpc/flutter_samples —— 環(huán)境搭建指導(dǎo)、FAQ 與示例工程鴻蒙化適配倉(cāng)庫(kù)oh-flutter/onesignal_flutter —— 本文 onesignal_flutter 的 OpenHarmony 適配版本環(huán)境搭好之后還沒(méi)搭的看這篇 Flutter 鴻蒙環(huán)境搭建指南下一步就是給項(xiàng)目引入三方庫(kù)。本文以 onesignal_flutter推送通知插件為例完整演示從fork 原倉(cāng)庫(kù) → 編寫(xiě) ArkTS 原生插件 → flutter create 生成宿主 → 構(gòu)建 → 真機(jī)驗(yàn)證的全流程。這是一個(gè)9 個(gè) MethodChannel、50 方法的復(fù)雜插件比 in_app_update 的單 Channel 場(chǎng)景更具代表性。OneSignal 是海外主流的免費(fèi)推送通知服務(wù)類(lèi)似國(guó)內(nèi)的極光推送、個(gè)推提供推送通知、應(yīng)用內(nèi)消息、用戶(hù)標(biāo)簽管理、會(huì)話(huà)追蹤等能力。鴻蒙上沒(méi)有 OneSignal SDK必須用 ArkTS 原生樁實(shí)現(xiàn)來(lái)模擬全部接口。一、插件分析onesignal_flutter 做了什么1.1 基本信息onesignal_flutter 是 OneSignal 官方 Flutter SDKAndroid 和 iOS 側(cè)分別對(duì)接各自的 OneSignal Native SDK。項(xiàng)目?jī)?nèi)容庫(kù)名onesignal_flutter適配基于版本5.6.10上游 pub.dev 最新 5.7.1適配倉(cāng)庫(kù)基于 5.6.10 fork功能推送通知、應(yīng)用內(nèi)消息、用戶(hù)標(biāo)簽、會(huì)話(huà)追蹤主要 APIinitialize()、login()、addTags()、consentGiven()、Notifications.addClickListener() 等原生依賴(lài)Android: OneSignal Android SDKiOS: OneSignal iOS SDK1.2 為什么這個(gè)庫(kù)必須寫(xiě)原生代碼onesignal_flutter 的 Dart 層完全通過(guò) 9 個(gè) MethodChannel 調(diào)用原生能力// 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 個(gè) Channel 各自負(fù)責(zé)不同功能模塊Dart 側(cè)只是一個(gè)遙控器——真正的推送注冊(cè)、令牌獲取、用戶(hù)管理全部由原生側(cè)完成。鴻蒙上沒(méi)有 OneSignal SDK必須用 hilog 日志樁模擬全部接口。1.3 9 個(gè) Channel 全景序號(hào)Channel 名稱(chēng)功能模塊Dart 側(cè)文件1OneSignal主通道初始化、登錄、授權(quán)onesignal_flutter.dart2OneSignal#debug調(diào)試日志級(jí)別src/debug.dart3OneSignal#inappmessages應(yīng)用內(nèi)消息src/inappmessages.dart4OneSignal#liveactivities實(shí)時(shí)活動(dòng)iOSsrc/liveactivities.dart5OneSignal#pushsubscription推送訂閱狀態(tài)src/pushsubscription.dart6OneSignal#user用戶(hù)管理src/user.dart7OneSignal#location位置共享src/location.dart8OneSignal#notifications通知管理src/notifications.dart9OneSignal#session會(huì)話(huà)追蹤src/session.dart1.4 適配策略fork 模式和 in_app_update 一樣采用 fork 原倉(cāng)庫(kù) 添加 ohos 平臺(tái)的方式Fork 原倉(cāng)庫(kù)保留全部原始文件android/、ios/、lib/、test/ 等不動(dòng)在 pubspec.yaml 中添加 ohos 平臺(tái)聲明創(chuàng)建 ohos/ 目錄作為 HAR 模塊編寫(xiě) ArkTS 原生插件用 flutter create --platforms ohos 生成標(biāo)準(zhǔn) example 宿主工程在生成的模板上添加插件注冊(cè)代碼為什么不創(chuàng)建獨(dú)立 OHOS 包fork 模式的好處是原插件的 Dart 層代碼lib/完全復(fù)用Android/iOS 側(cè)也不受影響一個(gè)倉(cāng)庫(kù)同時(shí)支持三個(gè)平臺(tái)。二、適配流程從 fork 到 ArkTS 原生插件2.1 克隆原倉(cāng)庫(kù)cd D:\Flutters git clone --depth 1 https://github.com/OneSignal/OneSignal-Flutter-SDK.git onesignal_flutter_ohos使用 --depth 1 淺克隆因?yàn)樵瓊}(cāng)庫(kù)歷史較大?？寺『蟊Ａ羧吭嘉募谠谢A(chǔ)上添加 ohos 相關(guān)內(nèi)容。2.2 修改 pubspec.yaml添加 ohos 平臺(tái)聲明修改前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三個(gè)關(guān)鍵改動(dòng)name 改為 onesignal_flutter_ohos以 _ohos 結(jié)尾是社區(qū)約定version 追加 ohos 后綴ohos 平臺(tái)聲明 pluginClass: OneSignalOhosPlugin——這就是后面要寫(xiě)的 ArkTS 插件類(lèi)名2.3 創(chuàng)建 ohos/ HAR 模塊在項(xiàng)目根目錄創(chuàng)建 ohos/ 目錄完整結(jié)構(gòu)如下ohos/ ├── src/main/ets/components/plugin/ │ └── OneSignalOhosPlugin.ets ← ArkTS 原生插件核心實(shí)現(xiàn)218 行 ├── src/main/module.json5 ← HAR 模塊元信息 ├── index.ets ← HAR 模塊入口 ├── oh-package.json5 ← HAR 依賴(lài)聲明 ├── build-profile.json5 ← 構(gòu)建配置 ├── hvigorfile.ts ← hvigor 構(gòu)建腳本 └── BuildProfile.ets ← 構(gòu)建變量oh-package.json5HAR 依賴(lài)聲明{ 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 入口導(dǎo)出插件類(lèi)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 編寫(xiě) ArkTS 原生插件核心這是整個(gè)適配的核心文件 OneSignalOhosPlugin.ets。由于鴻蒙沒(méi)有 OneSignal SDK所有方法采用 hilog 日志樁實(shí)現(xiàn)——記錄調(diào)用日志并返回安全默認(rèn)值。插件需要實(shí)現(xiàn) FlutterPlugin 和 MethodCallHandler 兩個(gè)接口在 onAttachedToEngine 中創(chuàng)建全部 9 個(gè) 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)一路由所有調(diào)用按功能模塊分組處理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 關(guān)鍵設(shè)計(jì)決策解析9 個(gè) Channel 共用一個(gè) Handler和 in_app_update 的 1 個(gè) MethodChannel 1 個(gè) EventChannel 不同OneSignal 有 9 個(gè) MethodChannel。ArkTS 側(cè)用一個(gè) OneSignalOhosPlugin 實(shí)例同時(shí)處理所有 Channel——所有 Channel 的 setMethodCallHandler 都指向 this然后通過(guò)方法名前綴 OneSignal# 統(tǒng)一路由。Channel 名稱(chēng)保持原樣const CHANNEL_MAIN OneSignal; const CHANNEL_NOTIFICATIONS OneSignal#notifications; const CHANNEL_PUSHSUBSCRIPTION OneSignal#pushsubscription; // ... 共 9 個(gè)所有 Channel 名稱(chēng)與原插件完全一致。這意味著 Dart 側(cè)的 lib/ 目錄下所有源碼零改動(dòng)——原插件的 Dart 代碼不需要任何修改就能和 ArkTS 原生側(cè)通信。hilog 日志樁而非真實(shí) SDK鴻蒙上沒(méi)有 OneSignal SDK所以所有方法采用 hilog 日志樁實(shí)現(xiàn)記錄調(diào)用參數(shù)返回安全默認(rèn)值。這不是偷懶——對(duì)于插件適配驗(yàn)證來(lái)說(shuō)確保 MethodChannel 通信鏈路暢通是第一步后續(xù)可以逐步替換為真實(shí)的推送能力如鴻蒙的 pushKit。返回值類(lèi)型必須嚴(yán)格匹配 Dart 側(cè)這是本次適配中最關(guān)鍵的發(fā)現(xiàn)。Dart 側(cè)的變量類(lèi)型決定了 ArkTS 側(cè)必須返回對(duì)應(yīng)類(lèi)型// notifications.dart bool _permission false; // 非空 bool _permission await _channel.invokeMethod(OneSignal#permission);// pushsubscription.dart String? _token; // 可空 String _token await _channel.invokeMethod(OneSignal#pushSubscriptionToken);如果 ArkTS 側(cè) permission 返回 0int而不是 falseboolDart 側(cè)類(lèi)型轉(zhuǎn)換直接崩潰。同理 pushSubscriptionToken 返回 null 或空字符串都可以因?yàn)?String? 可空但 permission 必須返回 bool。三、example 宿主工程flutter create 生成標(biāo)準(zhǔn)模板3.1 生成 ohos 宿主工程原倉(cāng)庫(kù)的 example 目錄是 examples/demo/OneSignal 有多個(gè)示例應(yīng)用。在該目錄下執(zhí)行cd D:\Flutters\onesignal_flutter_ohos\examples\demo flutter create --platformsohos .這條命令會(huì)在 examples/demo/ 下生成 ohos/ 目錄約 39 個(gè)文件包含標(biāo)準(zhǔn)的鴻蒙應(yīng)用模板。注意路徑差異OneSignal 原倉(cāng)庫(kù)使用 examples/demo/ 而不是常見(jiàn)的 example/所以生成的宿主工程在 examples/demo/ohos/比一般插件多一層目錄。3.2 修改 examples/demo/pubspec.yaml原 demo 應(yīng)用依賴(lài)了大量第三方插件shared_preferences、provider、flutter_dotenv、http、url_launcher 等這些插件均未適配 OHOS。直接用會(huì)導(dǎo)致啟動(dòng)崩潰。將 pubspec.yaml 精簡(jiǎn)為最小依賴(lài)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同時(shí)替換 lib/main.dart 為最小化測(cè)試頁(yè)面僅依賴(lài) flutter onesignal_flutter_ohos避免未適配插件導(dǎo)致啟動(dòng)崩潰。3.3 修改 import 路徑// 原來(lái) 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 補(bǔ)全 deviceTypes 和權(quán)限// examples/demo/ohos/entry/src/main/module.json5 { module: { name: entry, type: entry, deviceTypes: [phone, tablet, 2in1], requestPermissions: [ {name: ohos.permission.INTERNET} ] } }3.5 添加插件注冊(cè)代碼// 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 模塊依賴(lài) HAR// examples/demo/ohos/entry/oh-package.json5 { name: entry, version: 1.0.0, dependencies: { onesignal_flutter_ohos: file:../../../../ohos } }注意路徑深度由于 demo 在 examples/demo/ 下需要四級(jí) …/ 才能回到項(xiàng)目根目錄的 ohos/。四、構(gòu)建與真機(jī)驗(yàn)證4.1 DevEco Studio 配置調(diào)試簽名DevEco Studio → 文件 → 打開(kāi) → 選擇 examples/demo/ohos 目錄文件 → 項(xiàng)目結(jié)構(gòu) → 簽名配置 → 勾選自動(dòng)生成簽名登錄華為賬號(hào)證書(shū)自動(dòng)填充點(diǎn)確定4.2 執(zhí)行 flutter pub getcd D:\Flutters\onesignal_flutter_ohos\examples\demo flutter pub get4.3 構(gòu)建運(yùn)行在 DevEco Studio 中點(diǎn)運(yùn)行按鈕或命令行構(gòu)建flutter build hap --release編譯輸出Dart ArkTS 全部通過(guò)僅命令行簽名失敗 hvigor Finished :entry:defaultFlutterTask... after 16 s 768 ms hvigor Finished :entry:defaultCompileResource... after 355 ms hvigor Finished :entry:defaultBuildJS... after 5 ms4.4 真機(jī)效果驗(yàn)證測(cè)試頁(yè)面提供四個(gè)按鈕覆蓋 OneSignal 的核心功能按鈕功能調(diào)用方法初始化SDK 初始化 lifecycleInitOneSignal.initialize()登錄用戶(hù)登錄OneSignal.login()設(shè)置標(biāo)簽用戶(hù)標(biāo)簽管理OneSignal.User.addTags()同意授權(quán)隱私授權(quán)OneSignal.consentGiven()驗(yàn)證狀態(tài)匯總驗(yàn)證項(xiàng)狀態(tài)說(shuō)明依賴(lài)解析flutter pub get通過(guò)依賴(lài)正常解析Dart 編譯通過(guò)無(wú)編譯錯(cuò)誤ArkTS 編譯通過(guò)218 行原生插件編譯成功真機(jī)運(yùn)行通過(guò)UI 正常顯示四個(gè)按鈕可點(diǎn)擊9 個(gè) Channel 注冊(cè)通過(guò)全部 Channel 正常創(chuàng)建initialize lifecycleInit通過(guò)初始化鏈路完整執(zhí)行Dart ? ArkTS 類(lèi)型匹配通過(guò)bool/int/string 返回值類(lèi)型正確五、常見(jiàn)問(wèn)題 FAQQ1OneSignal 原倉(cāng)庫(kù)有 10 個(gè) Java 文件和 9 個(gè) ChannelArkTS 側(cè)怎么對(duì)應(yīng)ArkTS 側(cè)用一個(gè)插件類(lèi)處理全部 9 個(gè) Channel。關(guān)鍵是在 onAttachedToEngine 中循環(huán)創(chuàng)建所有 Channel并統(tǒng)一指向同一個(gè) 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 共用一個(gè) Handler this.channels.set(name, ch); } }然后在 routeMethod 中通過(guò)方法名前綴統(tǒng)一路由。這比創(chuàng)建 9 個(gè)獨(dú)立 Handler 簡(jiǎn)潔得多。Q2鴻蒙沒(méi)有 OneSignal SDK推送功能能用嗎當(dāng)前實(shí)現(xiàn)是 hilog 日志樁——所有方法調(diào)用會(huì)被記錄到系統(tǒng)日志并返回安全默認(rèn)值。推送注冊(cè)、令牌獲取等實(shí)際功能需要后續(xù)對(duì)接鴻蒙的 pushKit華為推送服務(wù)來(lái)真正實(shí)現(xiàn)。適配驗(yàn)證階段的重點(diǎn)是確保 MethodChannel 通信鏈路暢通、Dart 側(cè)調(diào)用不會(huì)崩潰。功能實(shí)現(xiàn)可以逐步迭代。Q3初始化時(shí)遇到類(lèi)型轉(zhuǎn)換崩潰怎么辦OneSignal 的 initialize() 會(huì)級(jí)聯(lián)調(diào)用 4 個(gè) lifecycleInit()每個(gè) lifecycleInit 都會(huì)通過(guò) MethodChannel 獲取返回值。Dart 側(cè)對(duì)返回值類(lèi)型有嚴(yán)格要求// notifications.dart — bool 類(lèi)型不能返回 int bool _permission false; _permission await _channel.invokeMethod(OneSignal#permission); // pushsubscription.dart — String? 類(lèi)型可空 String? _token; _token await _channel.invokeMethod(OneSignal#pushSubscriptionToken);ArkTS 側(cè)必須返回完全匹配的類(lèi)型permission 返回 falsebool而非 0intpushSubscriptionToken 返回 ‘’string而非 null。類(lèi)型不匹配會(huì)直接導(dǎo)致 Dart 側(cè)類(lèi)型轉(zhuǎn)換異常表現(xiàn)為初始化失敗或應(yīng)用崩潰。Q4原 demo 應(yīng)用依賴(lài)了 shared_preferences 等未適配插件怎么處理OneSignal 原倉(cāng)庫(kù)的 examples/demo 依賴(lài)了 shared_preferences、provider、flutter_dotenv、http 等第三方插件這些插件均未適配 OHOS。直接運(yùn)行會(huì)因 MissingPluginException 崩潰。解決方案是精簡(jiǎn) pubspec.yaml只保留 flutter SDK 和 onesignal_flutter_ohos同時(shí)將 main.dart 替換為最小化測(cè)試頁(yè)面。這樣可以在不依賴(lài)任何未適配插件的情況下驗(yàn)證核心功能。六、總結(jié)本文完整記錄了 onesignal_flutter 插件從 fork 到鴻蒙 PC 真機(jī)驗(yàn)證的全流程采用 fork 模式保留原倉(cāng)庫(kù)全部文件用 flutter create --platforms ohos 生成標(biāo)準(zhǔn)宿主工程模板編寫(xiě) 218 行 ArkTS 原生插件代碼在一個(gè)插件類(lèi)中處理 9 個(gè) MethodChannel 的 50 方法調(diào)用通過(guò) hilog 日志樁模擬 OneSignal SDK 的全部接口。Dart 側(cè)源碼零改動(dòng)所有 Channel 名稱(chēng)與原插件保持一致。核心經(jīng)驗(yàn)多 Channel 插件的適配關(guān)鍵在于統(tǒng)一路由設(shè)計(jì)——一個(gè) Handler 處理所有 Channel通過(guò)方法名前綴分發(fā)比創(chuàng)建多個(gè)獨(dú)立 Handler 更簡(jiǎn)潔。返回值類(lèi)型必須嚴(yán)格匹配 Dart 側(cè)的變量類(lèi)型bool 不能返回 intstring 不能返回 null非空類(lèi)型時(shí)。動(dòng)手前建議先查一眼 Flutter OH 三方庫(kù)適配列表很多熱門(mén)庫(kù)已有人適配過(guò)別重復(fù)造輪子。參考資料CPF-Flutter 社區(qū)主頁(yè)CPF-Flutter/flutter_flutterFlutter-OH 主倉(cāng)庫(kù)oh-flutter/onesignal_flutter鴻蒙化適配倉(cāng)庫(kù)Flutter OH 三方庫(kù)適配列表OneSignal/OneSignal-Flutter-SDK 原庫(kù)源碼oh-flutter 社區(qū)適配參考Flutter 鴻蒙環(huán)境搭建指南HarmonyOS pushKit 推送服務(wù)文檔Flutter OH 官方示例與 FAQ Flutter 三方庫(kù) OpenHarmony 鴻蒙適配實(shí)戰(zhàn)：OneSignal 推送通知插件 ArkTS 原生適配全流程
基于 Flutter-OH 3.44.9-devDart 3.12.2在 Windows 10 22H2 上全程實(shí)測(cè)通過(guò)開(kāi)發(fā)工具 DevEco Studio 26HarmonyOS SDK compatibleSdkVersion 5.1.0(18) / compileSdkVersion 26.0.0.105真機(jī)環(huán)節(jié)在一臺(tái)**鴻蒙 PCOpenHarmony 6.1.1API 24arm642in1 形態(tài)**上驗(yàn)證。文中所有源碼分析、改動(dòng)內(nèi)容、構(gòu)建輸出、真機(jī)效果均為實(shí)際環(huán)境抓取可放心對(duì)照復(fù)現(xiàn)。前言O(shè)penHarmony × Flutter 社區(qū)資源社區(qū)主頁(yè)CPF-Flutter —— OpenHarmony Flutter 生態(tài)維護(hù)組織Flutter-OH 主倉(cāng)庫(kù)CPF-Flutter/flutter_flutter —— SDK 與 Engine 的 OpenHarmony 適配版本三方庫(kù)適配與開(kāi)發(fā)文檔OpenHarmony-Flutter —— 生態(tài)庫(kù)適配清單與開(kāi)發(fā)規(guī)范官方示例與開(kāi)發(fā)指南openharmony-tpc/flutter_samples —— 環(huán)境搭建指導(dǎo)、FAQ 與示例工程鴻蒙化適配倉(cāng)庫(kù)oh-flutter/onesignal_flutter —— 本文 onesignal_flutter 的 OpenHarmony 適配版本環(huán)境搭好之后還沒(méi)搭的看這篇 Flutter 鴻蒙環(huán)境搭建指南下一步就是給項(xiàng)目引入三方庫(kù)。本文以 onesignal_flutter推送通知插件為例完整演示從fork 原倉(cāng)庫(kù) → 編寫(xiě) ArkTS 原生插件 → flutter create 生成宿主 → 構(gòu)建 → 真機(jī)驗(yàn)證的全流程。這是一個(gè)9 個(gè) MethodChannel、50 方法的復(fù)雜插件比 in_app_update 的單 Channel 場(chǎng)景更具代表性。OneSignal 是海外主流的免費(fèi)推送通知服務(wù)類(lèi)似國(guó)內(nèi)的極光推送、個(gè)推提供推送通知、應(yīng)用內(nèi)消息、用戶(hù)標(biāo)簽管理、會(huì)話(huà)追蹤等能力。鴻蒙上沒(méi)有 OneSignal SDK必須用 ArkTS 原生樁實(shí)現(xiàn)來(lái)模擬全部接口。一、插件分析onesignal_flutter 做了什么1.1 基本信息onesignal_flutter 是 OneSignal 官方 Flutter SDKAndroid 和 iOS 側(cè)分別對(duì)接各自的 OneSignal Native SDK。項(xiàng)目?jī)?nèi)容庫(kù)名onesignal_flutter適配基于版本5.6.10上游 pub.dev 最新 5.7.1適配倉(cāng)庫(kù)基于 5.6.10 fork功能推送通知、應(yīng)用內(nèi)消息、用戶(hù)標(biāo)簽、會(huì)話(huà)追蹤主要 APIinitialize()、login()、addTags()、consentGiven()、Notifications.addClickListener() 等原生依賴(lài)Android: OneSignal Android SDKiOS: OneSignal iOS SDK1.2 為什么這個(gè)庫(kù)必須寫(xiě)原生代碼onesignal_flutter 的 Dart 層完全通過(guò) 9 個(gè) MethodChannel 調(diào)用原生能力// 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 個(gè) Channel 各自負(fù)責(zé)不同功能模塊Dart 側(cè)只是一個(gè)遙控器——真正的推送注冊(cè)、令牌獲取、用戶(hù)管理全部由原生側(cè)完成。鴻蒙上沒(méi)有 OneSignal SDK必須用 hilog 日志樁模擬全部接口。1.3 9 個(gè) Channel 全景序號(hào)Channel 名稱(chēng)功能模塊Dart 側(cè)文件1OneSignal主通道初始化、登錄、授權(quán)onesignal_flutter.dart2OneSignal#debug調(diào)試日志級(jí)別src/debug.dart3OneSignal#inappmessages應(yīng)用內(nèi)消息src/inappmessages.dart4OneSignal#liveactivities實(shí)時(shí)活動(dòng)iOSsrc/liveactivities.dart5OneSignal#pushsubscription推送訂閱狀態(tài)src/pushsubscription.dart6OneSignal#user用戶(hù)管理src/user.dart7OneSignal#location位置共享src/location.dart8OneSignal#notifications通知管理src/notifications.dart9OneSignal#session會(huì)話(huà)追蹤src/session.dart1.4 適配策略fork 模式和 in_app_update 一樣采用 fork 原倉(cāng)庫(kù) 添加 ohos 平臺(tái)的方式Fork 原倉(cāng)庫(kù)保留全部原始文件android/、ios/、lib/、test/ 等不動(dòng)在 pubspec.yaml 中添加 ohos 平臺(tái)聲明創(chuàng)建 ohos/ 目錄作為 HAR 模塊編寫(xiě) ArkTS 原生插件用 flutter create --platforms ohos 生成標(biāo)準(zhǔn) example 宿主工程在生成的模板上添加插件注冊(cè)代碼為什么不創(chuàng)建獨(dú)立 OHOS 包fork 模式的好處是原插件的 Dart 層代碼lib/完全復(fù)用Android/iOS 側(cè)也不受影響一個(gè)倉(cāng)庫(kù)同時(shí)支持三個(gè)平臺(tái)。二、適配流程從 fork 到 ArkTS 原生插件2.1 克隆原倉(cāng)庫(kù)cd D:\Flutters git clone --depth 1 https://github.com/OneSignal/OneSignal-Flutter-SDK.git onesignal_flutter_ohos使用 --depth 1 淺克隆因?yàn)樵瓊}(cāng)庫(kù)歷史較大?？寺『蟊Ａ羧吭嘉募谠谢A(chǔ)上添加 ohos 相關(guān)內(nèi)容。2.2 修改 pubspec.yaml添加 ohos 平臺(tái)聲明修改前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三個(gè)關(guān)鍵改動(dòng)name 改為 onesignal_flutter_ohos以 _ohos 結(jié)尾是社區(qū)約定version 追加 ohos 后綴ohos 平臺(tái)聲明 pluginClass: OneSignalOhosPlugin——這就是后面要寫(xiě)的 ArkTS 插件類(lèi)名2.3 創(chuàng)建 ohos/ HAR 模塊在項(xiàng)目根目錄創(chuàng)建 ohos/ 目錄完整結(jié)構(gòu)如下ohos/ ├── src/main/ets/components/plugin/ │ └── OneSignalOhosPlugin.ets ← ArkTS 原生插件核心實(shí)現(xiàn)218 行 ├── src/main/module.json5 ← HAR 模塊元信息 ├── index.ets ← HAR 模塊入口 ├── oh-package.json5 ← HAR 依賴(lài)聲明 ├── build-profile.json5 ← 構(gòu)建配置 ├── hvigorfile.ts ← hvigor 構(gòu)建腳本 └── BuildProfile.ets ← 構(gòu)建變量oh-package.json5HAR 依賴(lài)聲明{ 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 入口導(dǎo)出插件類(lèi)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 編寫(xiě) ArkTS 原生插件核心這是整個(gè)適配的核心文件 OneSignalOhosPlugin.ets。由于鴻蒙沒(méi)有 OneSignal SDK所有方法采用 hilog 日志樁實(shí)現(xiàn)——記錄調(diào)用日志并返回安全默認(rèn)值。插件需要實(shí)現(xiàn) FlutterPlugin 和 MethodCallHandler 兩個(gè)接口在 onAttachedToEngine 中創(chuàng)建全部 9 個(gè) 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)一路由所有調(diào)用按功能模塊分組處理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 關(guān)鍵設(shè)計(jì)決策解析9 個(gè) Channel 共用一個(gè) Handler和 in_app_update 的 1 個(gè) MethodChannel 1 個(gè) EventChannel 不同OneSignal 有 9 個(gè) MethodChannel。ArkTS 側(cè)用一個(gè) OneSignalOhosPlugin 實(shí)例同時(shí)處理所有 Channel——所有 Channel 的 setMethodCallHandler 都指向 this然后通過(guò)方法名前綴 OneSignal# 統(tǒng)一路由。Channel 名稱(chēng)保持原樣const CHANNEL_MAIN OneSignal; const CHANNEL_NOTIFICATIONS OneSignal#notifications; const CHANNEL_PUSHSUBSCRIPTION OneSignal#pushsubscription; // ... 共 9 個(gè)所有 Channel 名稱(chēng)與原插件完全一致。這意味著 Dart 側(cè)的 lib/ 目錄下所有源碼零改動(dòng)——原插件的 Dart 代碼不需要任何修改就能和 ArkTS 原生側(cè)通信。hilog 日志樁而非真實(shí) SDK鴻蒙上沒(méi)有 OneSignal SDK所以所有方法采用 hilog 日志樁實(shí)現(xiàn)記錄調(diào)用參數(shù)返回安全默認(rèn)值。這不是偷懶——對(duì)于插件適配驗(yàn)證來(lái)說(shuō)確保 MethodChannel 通信鏈路暢通是第一步后續(xù)可以逐步替換為真實(shí)的推送能力如鴻蒙的 pushKit。返回值類(lèi)型必須嚴(yán)格匹配 Dart 側(cè)這是本次適配中最關(guān)鍵的發(fā)現(xiàn)。Dart 側(cè)的變量類(lèi)型決定了 ArkTS 側(cè)必須返回對(duì)應(yīng)類(lèi)型// notifications.dart bool _permission false; // 非空 bool _permission await _channel.invokeMethod(OneSignal#permission);// pushsubscription.dart String? _token; // 可空 String _token await _channel.invokeMethod(OneSignal#pushSubscriptionToken);如果 ArkTS 側(cè) permission 返回 0int而不是 falseboolDart 側(cè)類(lèi)型轉(zhuǎn)換直接崩潰。同理 pushSubscriptionToken 返回 null 或空字符串都可以因?yàn)?String? 可空但 permission 必須返回 bool。三、example 宿主工程flutter create 生成標(biāo)準(zhǔn)模板3.1 生成 ohos 宿主工程原倉(cāng)庫(kù)的 example 目錄是 examples/demo/OneSignal 有多個(gè)示例應(yīng)用。在該目錄下執(zhí)行cd D:\Flutters\onesignal_flutter_ohos\examples\demo flutter create --platformsohos .這條命令會(huì)在 examples/demo/ 下生成 ohos/ 目錄約 39 個(gè)文件包含標(biāo)準(zhǔn)的鴻蒙應(yīng)用模板。注意路徑差異OneSignal 原倉(cāng)庫(kù)使用 examples/demo/ 而不是常見(jiàn)的 example/所以生成的宿主工程在 examples/demo/ohos/比一般插件多一層目錄。3.2 修改 examples/demo/pubspec.yaml原 demo 應(yīng)用依賴(lài)了大量第三方插件shared_preferences、provider、flutter_dotenv、http、url_launcher 等這些插件均未適配 OHOS。直接用會(huì)導(dǎo)致啟動(dòng)崩潰。將 pubspec.yaml 精簡(jiǎn)為最小依賴(lài)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同時(shí)替換 lib/main.dart 為最小化測(cè)試頁(yè)面僅依賴(lài) flutter onesignal_flutter_ohos避免未適配插件導(dǎo)致啟動(dòng)崩潰。3.3 修改 import 路徑// 原來(lái) 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 補(bǔ)全 deviceTypes 和權(quán)限// examples/demo/ohos/entry/src/main/module.json5 { module: { name: entry, type: entry, deviceTypes: [phone, tablet, 2in1], requestPermissions: [ {name: ohos.permission.INTERNET} ] } }3.5 添加插件注冊(cè)代碼// 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 模塊依賴(lài) HAR// examples/demo/ohos/entry/oh-package.json5 { name: entry, version: 1.0.0, dependencies: { onesignal_flutter_ohos: file:../../../../ohos } }注意路徑深度由于 demo 在 examples/demo/ 下需要四級(jí) …/ 才能回到項(xiàng)目根目錄的 ohos/。四、構(gòu)建與真機(jī)驗(yàn)證4.1 DevEco Studio 配置調(diào)試簽名DevEco Studio → 文件 → 打開(kāi) → 選擇 examples/demo/ohos 目錄文件 → 項(xiàng)目結(jié)構(gòu) → 簽名配置 → 勾選自動(dòng)生成簽名登錄華為賬號(hào)證書(shū)自動(dòng)填充點(diǎn)確定4.2 執(zhí)行 flutter pub getcd D:\Flutters\onesignal_flutter_ohos\examples\demo flutter pub get4.3 構(gòu)建運(yùn)行在 DevEco Studio 中點(diǎn)運(yùn)行按鈕或命令行構(gòu)建flutter build hap --release編譯輸出Dart ArkTS 全部通過(guò)僅命令行簽名失敗 hvigor Finished :entry:defaultFlutterTask... after 16 s 768 ms hvigor Finished :entry:defaultCompileResource... after 355 ms hvigor Finished :entry:defaultBuildJS... after 5 ms4.4 真機(jī)效果驗(yàn)證測(cè)試頁(yè)面提供四個(gè)按鈕覆蓋 OneSignal 的核心功能按鈕功能調(diào)用方法初始化SDK 初始化 lifecycleInitOneSignal.initialize()登錄用戶(hù)登錄OneSignal.login()設(shè)置標(biāo)簽用戶(hù)標(biāo)簽管理OneSignal.User.addTags()同意授權(quán)隱私授權(quán)OneSignal.consentGiven()驗(yàn)證狀態(tài)匯總驗(yàn)證項(xiàng)狀態(tài)說(shuō)明依賴(lài)解析flutter pub get通過(guò)依賴(lài)正常解析Dart 編譯通過(guò)無(wú)編譯錯(cuò)誤ArkTS 編譯通過(guò)218 行原生插件編譯成功真機(jī)運(yùn)行通過(guò)UI 正常顯示四個(gè)按鈕可點(diǎn)擊9 個(gè) Channel 注冊(cè)通過(guò)全部 Channel 正常創(chuàng)建initialize lifecycleInit通過(guò)初始化鏈路完整執(zhí)行Dart ? ArkTS 類(lèi)型匹配通過(guò)bool/int/string 返回值類(lèi)型正確五、常見(jiàn)問(wèn)題 FAQQ1OneSignal 原倉(cāng)庫(kù)有 10 個(gè) Java 文件和 9 個(gè) ChannelArkTS 側(cè)怎么對(duì)應(yīng)ArkTS 側(cè)用一個(gè)插件類(lèi)處理全部 9 個(gè) Channel。關(guān)鍵是在 onAttachedToEngine 中循環(huán)創(chuàng)建所有 Channel并統(tǒng)一指向同一個(gè) 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 共用一個(gè) Handler this.channels.set(name, ch); } }然后在 routeMethod 中通過(guò)方法名前綴統(tǒng)一路由。這比創(chuàng)建 9 個(gè)獨(dú)立 Handler 簡(jiǎn)潔得多。Q2鴻蒙沒(méi)有 OneSignal SDK推送功能能用嗎當(dāng)前實(shí)現(xiàn)是 hilog 日志樁——所有方法調(diào)用會(huì)被記錄到系統(tǒng)日志并返回安全默認(rèn)值。推送注冊(cè)、令牌獲取等實(shí)際功能需要后續(xù)對(duì)接鴻蒙的 pushKit華為推送服務(wù)來(lái)真正實(shí)現(xiàn)。適配驗(yàn)證階段的重點(diǎn)是確保 MethodChannel 通信鏈路暢通、Dart 側(cè)調(diào)用不會(huì)崩潰。功能實(shí)現(xiàn)可以逐步迭代。Q3初始化時(shí)遇到類(lèi)型轉(zhuǎn)換崩潰怎么辦OneSignal 的 initialize() 會(huì)級(jí)聯(lián)調(diào)用 4 個(gè) lifecycleInit()每個(gè) lifecycleInit 都會(huì)通過(guò) MethodChannel 獲取返回值。Dart 側(cè)對(duì)返回值類(lèi)型有嚴(yán)格要求// notifications.dart — bool 類(lèi)型不能返回 int bool _permission false; _permission await _channel.invokeMethod(OneSignal#permission); // pushsubscription.dart — String? 類(lèi)型可空 String? _token; _token await _channel.invokeMethod(OneSignal#pushSubscriptionToken);ArkTS 側(cè)必須返回完全匹配的類(lèi)型permission 返回 falsebool而非 0intpushSubscriptionToken 返回 ‘’string而非 null。類(lèi)型不匹配會(huì)直接導(dǎo)致 Dart 側(cè)類(lèi)型轉(zhuǎn)換異常表現(xiàn)為初始化失敗或應(yīng)用崩潰。Q4原 demo 應(yīng)用依賴(lài)了 shared_preferences 等未適配插件怎么處理OneSignal 原倉(cāng)庫(kù)的 examples/demo 依賴(lài)了 shared_preferences、provider、flutter_dotenv、http 等第三方插件這些插件均未適配 OHOS。直接運(yùn)行會(huì)因 MissingPluginException 崩潰。解決方案是精簡(jiǎn) pubspec.yaml只保留 flutter SDK 和 onesignal_flutter_ohos同時(shí)將 main.dart 替換為最小化測(cè)試頁(yè)面。這樣可以在不依賴(lài)任何未適配插件的情況下驗(yàn)證核心功能。六、總結(jié)本文完整記錄了 onesignal_flutter 插件從 fork 到鴻蒙 PC 真機(jī)驗(yàn)證的全流程采用 fork 模式保留原倉(cāng)庫(kù)全部文件用 flutter create --platforms ohos 生成標(biāo)準(zhǔn)宿主工程模板編寫(xiě) 218 行 ArkTS 原生插件代碼在一個(gè)插件類(lèi)中處理 9 個(gè) MethodChannel 的 50 方法調(diào)用通過(guò) hilog 日志樁模擬 OneSignal SDK 的全部接口。Dart 側(cè)源碼零改動(dòng)所有 Channel 名稱(chēng)與原插件保持一致。核心經(jīng)驗(yàn)多 Channel 插件的適配關(guān)鍵在于統(tǒng)一路由設(shè)計(jì)——一個(gè) Handler 處理所有 Channel通過(guò)方法名前綴分發(fā)比創(chuàng)建多個(gè)獨(dú)立 Handler 更簡(jiǎn)潔。返回值類(lèi)型必須嚴(yán)格匹配 Dart 側(cè)的變量類(lèi)型bool 不能返回 intstring 不能返回 null非空類(lèi)型時(shí)。動(dòng)手前建議先查一眼 Flutter OH 三方庫(kù)適配列表很多熱門(mén)庫(kù)已有人適配過(guò)別重復(fù)造輪子。參考資料CPF-Flutter 社區(qū)主頁(yè)CPF-Flutter/flutter_flutterFlutter-OH 主倉(cāng)庫(kù)oh-flutter/onesignal_flutter鴻蒙化適配倉(cāng)庫(kù)Flutter OH 三方庫(kù)適配列表OneSignal/OneSignal-Flutter-SDK 原庫(kù)源碼oh-flutter 社區(qū)適配參考Flutter 鴻蒙環(huán)境搭建指南HarmonyOS pushKit 推送服務(wù)文檔Flutter OH 官方示例與 FAQ