做视力保护提醒类App最核心的功能其实不在UI上而在通知设置这一环。提醒能不能准时出现、用户能不能按自己的节奏开关、App退到后台甚至被杀之后提醒还能不能弹出来这些都比界面好不好看重要得多。最近我把一个Flutter项目完整适配到OpenHarmony平台正好在通知模块上重建了一遍从通知发布到定时提醒再到App内设置页都踩了不少坑也把这一套机制摸清了。这篇文章就把我在项目里的实际方案、核心代码和排查经验整理出来给正在做同类App、或者准备把Flutter应用迁移到OpenHarmony的朋友一个参考。这个项目的形态很简单一个常驻的护眼提醒工具按20-20-20法则工作——每用眼20分钟提醒用户看20英尺外至少20秒同时支持自定义休息间隔和提醒开关。技术栈是Flutter做UI和业务逻辑OpenHarmony原生层提供通知与系统级调度能力。如果你正在做工具类、效率类、健康提醒类App或者对Flutter在OpenHarmony上的适配方式感兴趣这篇内容应该能帮你少走不少弯路。1. 项目整体设计思路为什么“通知”是这类App的命门1.1 视力保护场景的需求拆解视力提醒类产品的核心场景并不复杂用户在电脑前连续工作一段时间系统到点提醒他休息、远眺、做眼保健操。可一旦落到产品设计上需求就会拆成三个层次。第一层是“什么时候提醒”。这里涉及提醒的触发策略常见的有固定间隔提醒、每天特定时段提醒、久坐超时提醒等。我的做法是让用户选择30分钟、45分钟或60分钟为一轮每轮结束时弹出一条休息提醒。第二层是“提醒什么内容”。同样的休息提醒文案可以区分成“短休息”——只需要远眺20秒和“长休息”——建议起身活动3分钟让用户根据当下情境选择是否响应。第三层是“用户能不能控制”。这层最容易被忽视却是用户留存的关键。如果App每隔几分钟就强推一条通知用户一定会去系统设置里关掉整个App的通知权限到时候什么提醒都到不了。所以我把通知设置拆成了两个维度一个是用户维度的设置页包含总开关、不同类型提醒的独立开关、提醒间隔选择另一个是系统维度的通知渠道能力要让不同类型的提醒在系统通知设置里也分类展示用户可以单独关闭某一类而不是只能一揽子关掉。这才是通知设置模块真正的工程含义。1.2 为什么选择 Flutter for OpenHarmony项目最早是Flutter写的一套跨端代码原本目标平台是Android和iOS。后来业务要求覆盖OpenHarmony生态我需要评估两条路一条是单独写一个ArkTS原生版本另一条是在现有Flutter工程上做适配。对比之后我选了后者。原因很直接Flutter的UI层和业务逻辑层基本可以原样复用我的页面、状态管理、本地存储都是纯Dart实现不需要动。需要重写的只有原生能力层——通知发布、定时提醒调度、系统设置跳转这些本来依赖Android API或iOS API的部分。如果用ArkTS重写整个AppUI、状态管理、数据层都要重来一遍成本至少多出两倍。这里要提前说明一个现状官方Flutter SDK并不直接支持OpenHarmony需要采用OpenHarmony社区维护的Flutter适配分支也就是flutter_flutter。这个分支提供了构建OpenHarmony产物所需的engine和工具链同时保留了Flutter的标准API。项目里Flutter侧的代码、第三方纯Dart插件基本都能跑但任何涉及原生的能力比如通知、震动、传感器都需要自己封装MethodChannel来调OpenHarmony侧API跟Android插件开发时写PlatformChannel的思路非常像。1.3 通知设置模块的边界划分动手之前我先在项目里把“通知设置”划分成三块职责避免后面写着写着混成一锅粥。第一块是通知发布能力负责把一条通知投递到系统通知中心包括设置通知标题、内容、所属slot类型、通知ID。第二块是提醒调度能力决定什么时候触发通知。这里我没有用Flutter的Timer或者后台运行来做而是直接用系统的代理提醒能力让系统在指定时间点弹出通知App进程即使被系统回收也不影响触发。第三块是设置状态管理包含App内设置页的UI状态、本地持久化以及和系统通知设置的联动。这三块职责分别对应OpenHarmony的notificationManager、reminderAgentManager和App自己的偏好管理模块。把它们拆清楚之后不管是写代码还是排查问题边界都清晰很多。2. OpenHarmony通知能力原理解析2.1 NotificationRequest 与 slotType通知的基础结构在OpenHarmony上发布一条通知核心是构造一个NotificationRequest对象它的结构大致分三层。最外层是请求本身包含通知ID、slotType槽位类型、欲发布的内容中间是内容层声明内容类型和具体内容体最内层是normal字段承载实际展示的标题、正文、附加文案。写一段最基础的通知发布代码大致是下面这样import notificationManager from ohos.notificationManager; let request: notificationManager.NotificationRequest { id: 1001, slotType: notificationManager.SlotType.SERVICE_INFORMATION, content: { notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT, normal: { title: 该休息一下了, text: 站起来活动活动看看远处, additionalText: 护眼小卫士 } } }; notificationManager.publish(request).then(() { console.info(通知发布成功); }).catch((err) { console.error(通知发布失败: ${JSON.stringify(err)}); });这里的slotType是整个通知体系中最重要的概念它决定了通知在系统设置里的分类也影响通知的打扰强度。我整理了一下常用的几种类型slotType分类含义打扰强度建议用途SOCIAL_COMMUNICATION社交通讯强提示适合消息类好友消息、聊天提醒SERVICE_INFORMATION服务提醒普通提示休息提醒、日程提醒CONTENT_INFORMATION内容资讯普通提示新闻类、阅读类推送OTHER_TYPES其他类型较弱提示可能被静默无足轻重的后台信息实际开发中我让不同类型的护眼提醒使用不同的slotType。比如“久坐起身提醒”用SERVICE_INFORMATION“每日护眼操提醒”用CONTENT_INFORMATION。这样用户在系统设置里能分别关闭某一类而不是因为单一槽位被关掉就完全收不到提醒。2.2 定时提醒的正确姿势代理提醒视力提醒App最尴尬的场景是用户打开了权限但App进程被系统回收Flutter里的Timer全部失效到点提醒自然就没了。所以定时提醒绝对不能完全依赖Dart层的定时器。OpenHarmony提供了一类专门解决这个问题的能力叫做代理提醒对应reminderAgentManager。使用方式是把提醒请求注册到系统侧由系统在指定时间到点时直接发布通知。即使App进程已经不存在通知照样能弹出来。我做调研的时候把它和另外两个方案放在一起对比过用ArkTS的Timer并不靠谱进程一旦被回收就失效跟Flutter Timer的处境一样。用闹钟类接口alarmManager也能到点提醒但它主要面向用户明确设置的绝对时间闹钟需要申请额外权限在护眼这种反复注册、动态调整的场景下使用不够方便。WorkScheduler适合延迟执行后台任务比如数据同步、资源预加载它的调度粒度不保证精确到秒用于提醒类场景体验不好。代理提醒的注册接口很简单权限申请则需要在module.json5中声明{ requestPermissions: [ { name: ohos.permission.PUBLISH_AGENT_REMINDER } ] }提醒对象的构造方式和直接发布通知有些类似也需要指定提醒ID、标题、内容以及到点后使用的通知ID和slotType。这块后面实操章节我会给完整示例。2.3 用户开关模型App内设置与系统设置怎么配合OpenHarmony系统里通知的最终控制权在用户手里。用户可以在系统设置-通知管理里关闭整个App的通知权限也可以单独关闭某个slotType的通知还可以设置锁屏是否显示通知、是否允许横幅提醒。这些开关在系统层是独立的App无法通过代码强制打开。所以我在设计App内通知设置页时做了一个关键决定App内的开关负责“业务层”的注册与取消——开关打开时去系统注册代理提醒关闭时取消注册同时提供一个“检查系统通知权限”的入口引导用户进入系统设置页确保系统层的总开关是开启状态。两层开关必须同时打开提醒才能真正生效。另外要注意OpenHarmony的通知发布接口本身并不要求用户在运行时点弹窗授权这跟iOS的推送授权不同。普通通知默认就能发但是否弹出横幅、是否显示在锁屏、是否响铃取决于系统设置。开发者能做的只有把通知合理分类并在用户收不到通知时给他一条清晰的引导路径。3. Flutter侧接入方案MethodChannel封装与平台降级3.1 Dart侧统一封装通知服务在Flutter工程里我用一个Dart的NotifyService类把和原生通知相关的方法统一封装起来上层页面完全不感知平台差异。通道名我取的是com.example.visionguard/notify里面暴露的方法包括publish、cancel、cancelAll。代码大致如下import package:flutter/services.dart; class NotifyService { static const MethodChannel _channel MethodChannel(com.example.visionguard/notify); /// 发布一条普通通知 static Futurebool publish({ required int id, required String title, required String text, required String slotType, }) async { try { final bool result await _channel.invokeMethod(publish, { id: id, title: title, text: text, slotType: slotType, }); return result; } on PlatformException catch (e) { debugPrint(发布通知失败: ${e.code} ${e.message}); return false; } } /// 按通知ID取消通知 static Futurevoid cancel(int id) async { try { await _channel.invokeMethod(cancel, {id: id}); } on PlatformException catch (e) { debugPrint(取消通知失败: ${e.code} ${e.message}); } } /// 取消当前App全部通知 static Futurevoid cancelAll() async { try { await _channel.invokeMethod(cancelAll); } on PlatformException catch (e) { debugPrint(取消全部通知失败: ${e.code} ${e.message}); } } }为什么用单一MethodChannel而不是每个方法一个Channel因为MethodChannel在Flutter和原生侧都有创建和注册成本方法多了以后管理混乱。我习惯一个服务对应一个Channel方法名在invokeMethod里区分这样新增能力时只需要在两边各加一个case不必新增通道。3.2 ArkTS侧实现通道与通知能力OpenHarmony原生侧的通道实现核心是给同一个MethodChannel注册方法处理器解析Dart侧传过来的参数再调用OpenHarmony通知API。我这里的实现结构大致是这样import notificationManager from ohos.notificationManager; // 注册方法通道具体包名以你当前SDK生成的为准 function registerNotifyChannel(channel: MethodChannel) { channel.setMethodCallHandler(async (call) { const args call.arguments as Recordstring, string | number; switch (call.method) { case publish: { const slotType parseSlotType(args.slotType as string); const request { id: args.id as number, slotType: slotType, content: { notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT, normal: { title: args.title as string, text: args.text as string, }, }, }; try { await notificationManager.publish(request); return true; } catch (e) { console.error(publish failed: ${JSON.stringify(e)}); return false; } } case cancel: { try { await notificationManager.cancel(args.id as number); return true; } catch (e) { return false; } } case cancelAll: { try { await notificationManager.cancelAll(); return true; } catch (e) { return false; } } default: return null; } }); }这里面的parseSlotType是我写的一个字符串到枚举的转换函数因为Dart侧传过来的slotType是字符串而OpenHarmony侧是枚举类型。转换逻辑很简单就是switch映射service对应SERVICE_INFORMATIONcontent对应CONTENT_INFORMATIONsocial对应SOCIAL_COMMUNICATION默认回落为OTHER_TYPES。需要注意的是OpenHarmony不同API版本的导入路径可能有差异我在开发时切过几版SDK发现部分类名、包名在不同版本里有细微改动。最稳妥的办法是打开工程里SDK生成的d.ts文件直接确认当前版本的标准写法别直接拿网上的旧代码复制。3.3 非OpenHarmony平台的降级处理因为项目本身是跨端的我除了OpenHarmony还要照顾Android和iOS。最简单的方式是在运行期检测平台OpenHarmony走自研的MethodChannel方案Android/iOS则调用现有的本地通知插件比如flutter_local_notifications。我在Dart层做了个统一接口Futurebool publishReminder(ReminderModel model) async { if (Platform.isOpenHarmony) { return NotifyService.publish( id: model.id, title: model.title, text: model.content, slotType: model.slotType, ); } // Android/iOS 走已有插件逻辑 return LocalNotifyPlugin.publish(model); }这样业务层只需要关心ReminderModel不需要关心底层是哪个平台也方便以后继续扩展新的平台适配。4. 实操过程与核心环节实现4.1 环境准备创建支持 OpenHarmony 的 Flutter 工程先交代一下工程的搭建过程。我用的是OpenHarmony社区的flutter_flutter分支因为官方Flutter SDK目前还不支持构建OpenHarmony的hap包。步骤分四步。第一步安装DevEco Studio并配置好OpenHarmony SDK这部分跟普通OpenHarmony开发一样。第二步下载flutter_flutter分支到本地把里面的bin目录加进PATH用flutter --version确认当前生效的是OpenHarmony分支。第三步使用flutter create --platforms ohos .在当前目录补齐OpenHarmony的ohos工程壳工程。第四步用DevEco Studio打开工程根目录下的ohos目录配置签名和证书之后就能在模拟器或真机上运行了。这里容易被坑的是flutter命令的环境变量。如果你的机器上同时装了官方Flutter SDK和OpenHarmony分支的Flutter SDK一定要确认命令行里实际调用的是哪个。我一开始没注意PATH顺序跑了半天工程里一直不生成ohos目录排查了一圈才发现是SDK选错了。还有一点OpenHarmony版本的Flutter引擎、Dart SDK版本都可能比官方版本滞后一些依赖第三方纯Dart包时要注意版本兼容最好先在工程里跑一遍flutter pub get看看有没有版本冲突。4.2 发布一条基础通知的完整过程工程搭好、MethodChannel两端的注册都完成之后我先做的最基础验证就是在按钮点击事件里发布一条立即通知确认整条链路是通的。Dart侧调用final ok await NotifyService.publish( id: 1001, title: 休息时间到, text: 试试通知是否正常弹出, slotType: service, );ArkTS侧收到调用后发布到系统通知中心此时在系统的通知栏里就能看到这条通知。我在这个阶段重点验证了通知ID的覆盖规则同一个ID再次发布新通知会替换旧通知不会新增一条。这个特性在后面的场景里很有用比如同一个提醒需要更新倒计时文案时直接发同一条ID的通知即可。这里要特别留意slotType对用户体验的影响。我测试时发现如果用OTHER_TYPES发布的通知在没有开启横幅模式的情况下可能只进通知中心不弹横幅、不响铃用户根本感知不到。所以视力提醒这种需要强触达的通知全部统一使用SERVICE_INFORMATION类型在大多数系统设置下会带横幅弹窗提醒。4.3 用代理提醒实现“每45分钟休息一次”基础的立即通知只能验证链路真正的护眼提醒必须依赖代理提醒。我按需求把用户设置的提醒间隔转换成ReminderRequestTimer注册到reminderAgentManager。注册成功后会返回一个reminderId这个ID必须保存下来取消提醒的时候要用。核心代码大致是这样import reminderAgentManager from ohos.reminderAgentManager; function publishRestReminder(intervalSeconds: number) { let timer { reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER, triggerTimeInSeconds: intervalSeconds, title: 该休息一下了, content: 离开屏幕向远处看20秒, notificationId: 2001, slotType: reminderAgentManager.SlotType.SERVICE_INFORMATION }; reminderAgentManager.publishReminder(timer).then((reminderId: number) { console.info(代理提醒注册成功, id${reminderId}); // 保存 reminderId }).catch((err) { console.error(代理提醒注册失败: ${JSON.stringify(err)}); }); }注意triggerTimeInSeconds的单位是秒。如果用户设置的是45分钟传入的就是45 * 60我曾经在联调时写错过单位结果通知在45秒后弹出用户体感上像是被App骚扰了。关于周期性重复提醒不同SDK版本对周期字段的支持差异较大。我采取的方案比较保守不依赖系统周期字段而是把用户一天的处理分成多个一次性提醒。比如从用户开启功能开始每间隔45分钟注册一条提醒当天的提醒注册完成后第一条触发后检查是否还有后续提醒没有了就不再做处理。这样逻辑完全可控也不会被不同版本的API差异卡住。取消提醒时调用reminderAgentManager.cancelReminder(reminderId)即可。把reminderId和业务场景绑定可以在用户切换设置时精准取消某一类提醒而不会误伤其他提醒。我这里是直接封装了一个ReminderStore以业务类型为维度保存reminderId设置页里每个开关都有独立的注册和取消流程。4.4 App内通知设置页的具体实现设置页是用户管理提醒的唯一入口。我用的Flutter页面结构分成三个区域顶部是总开关中间是三类提醒各自的开关底部是提醒间隔选择。总开关的交互逻辑是打开时检查系统通知能力是否正常如果正常注册第一轮提醒关闭时取消全部代理提醒并清空reminderId记录。三个子开关分别控制“短休息提醒”“长休息提醒”“每日护眼操提醒”每个开关变化时Dart层调用对应的方法去注册或取消对应类型的提醒。状态持久化用shared_preferences包保存保存的字段包括总开关状态、三个子开关状态和间隔配置。每次App启动时读取这些状态如果总开关是开着的就根据子开关状态把当天的提醒重新注册一遍。这一步很容易漏用户重启手机后系统侧的提醒记录可能会被清掉App冷启动时的状态恢复逻辑必须补位。UI实现上用SwitchListTile就够核心是状态变更后的联动逻辑。我在代码里把所有提醒的注册逻辑收敛到了一个方法里Futurevoid _syncReminders() { // 先取消全部旧提醒 // 再根据最新开关状态重新注册 }这样做的好处是避免状态混乱。比如用户把总开关开着又关掉了某个子开关再重新打开直接执行一遍同步逻辑把当前设置下的提醒重新注册一遍比逐项比较增量状态要稳得多。5. 常见问题与排查技巧实录5.1 通知不弹出的问题排查表我在联调阶段遇到最多的问题就是“代码明明发布成功了但通知栏就是空的”。这类问题大多数不在代码逻辑而在系统设置和slotType的搭配上。我整理了一个排查表实际排查时按这个顺序走很快现象可能原因处理方式publish返回false系统通知服务被禁用引导用户到系统设置打开通知权限publish返回true但无横幅当前slotType被静默改用SERVICE_INFORMATION类型的slot通知只在锁屏界面缺失锁屏通知被关闭在系统设置中开启锁屏通知通知有声音但无内容横幅模式被关闭让用户在系统设置中打开横幅通知同一提醒只显示一条旧内容通知ID重复被覆盖为不同提醒分配不同ID杀进程后提醒不触发代理提醒没有注册成功检查PUBLISH_AGENT_REMINDER权限另外分享一个调试技巧发布通知后用DevEco的日志窗口先过滤“notification”能直接看到系统通知服务打印的发布结果。报错信息往往比代码里的catch信息详细得多能直接定位到slotType非法还是内容字段缺失。5.2 代理提醒不触发的排查思路代理提醒的排查更隐蔽因为发布时publishReminder可能返回成功但到了时间点什么都不弹。我遇到过的原因主要有四种。第一种是权限没声明。module.json5里没有加ohos.permission.PUBLISH_AGENT_REMINDER接口虽然能调用但提醒不会真正被系统采纳。第二种是App在设置里被用户关掉了通知能力代理提醒到点时系统发布通知会被拦下来。第三种是时间单位算错这个排查起来最快直接算一下设置的时间和实际弹出的时间差就行。第四种是同一时间点注册了多条相同条件的提醒后面的记录把前面的覆盖了导致部分提醒丢失。针对第四种我的建议是给每条代理提醒生成唯一且可追溯的ID。我的做法是用业务类型加时间戳组成reminderId的关联字段既能去重也能在取消时精确定位。5.3 Flutter 与 ArkTS 通道不通的典型情况MethodChannel在OpenHarmony上的表现总体稳定最容易出的问题集中在注册时机。如果Dart侧在ArkTS通道处理器还没注册完成时就调用了invokeMethod就会报MissingPluginException。这类问题通常在App冷启动后立刻调通知接口时出现。我的处理方案是等待Flutter引擎和原生通道都就绪后再触发注册。具体做法是在原生侧主动先完成setMethodCallHandler的注册不依赖Dart侧调用Dart侧在流程启动时先做一次探测调用失败时稍后重试。避免在onCreate之类过早的生命周期里直接发通知。排查通道问题时我一般会在ArkTS的setMethodCallHandler入口先打一条日志打印call.method和call.arguments。如果日志没打出来说明通道未注册或者通道名不一致如果日志打出来但Dart侧拿不到返回值大概率是异步处理链写错了注意处理器一定要返回Future值。5.4 打包与上架过程中需要注意的合规点用Flutter做完OpenHarmony适配后最终要产出hap包并通过上架审核。这一步除了常规的签名配置还要注意一个叫XTSSA认证的东西它全称是OpenHarmony兼容性认证不通过的话应用很难进入官方应用市场。在做XTSSA认证测试时通知模块会被重点检查应用必须在用户明确授权或合理引导后才会注册提醒通知内容不能含有误导、诱导性文案设置页中的开关状态和系统实际行为要一致。我遇到过一次审核反馈说应用在后台频繁注册代理提醒被判定为打扰用户。后面我把默认间隔从30分钟调整为45分钟并在首次开启时主动说明提醒频率审核才通过。另外打包时的hap产物如果接入了第三方SDK要核对有没有超出隐私声明的数据采集行为。护眼提醒类App本身不涉及敏感权限但必须尽量减少权限申请数量。我项目的最终权限只有PUBLISH_AGENT_REMINDER和INTERNET后者还是为了检查更新用的。结语一些实在的话做完了这个项目我最深的体会是跨端框架能解决的是UI和业务逻辑的复用问题而系统级体验比如通知到底能不能按时到、按预期到、按设置到最终还得回到原生能力层去解决。Flutter for OpenHarmony给了我们一套可以复用的开发范式但通知设置这类底层交互必须花时间把OpenHarmony的通知体系和代理提醒机制吃透。最后分享一个我自己反复用到的小技巧把通知ID、代理提醒ID和业务场景做一张对应关系表写在代码注释里。这个项目里我的ID规划是这样的——1000-1999段分配给即时通知2000-2999段分配给定时提醒3000-3999段预留给未来新增的提醒类型。因为通知ID直接决定能不能精准取消、能不能避免覆盖提前规划好后面排查问题会省很多时间。如果你也在做类似的项目试试这个方法应该能帮你少踩几个坑。
Flutter适配OpenHarmony：视力提醒App通知模块实战解析
做视力保护提醒类App最核心的功能其实不在UI上而在通知设置这一环。提醒能不能准时出现、用户能不能按自己的节奏开关、App退到后台甚至被杀之后提醒还能不能弹出来这些都比界面好不好看重要得多。最近我把一个Flutter项目完整适配到OpenHarmony平台正好在通知模块上重建了一遍从通知发布到定时提醒再到App内设置页都踩了不少坑也把这一套机制摸清了。这篇文章就把我在项目里的实际方案、核心代码和排查经验整理出来给正在做同类App、或者准备把Flutter应用迁移到OpenHarmony的朋友一个参考。这个项目的形态很简单一个常驻的护眼提醒工具按20-20-20法则工作——每用眼20分钟提醒用户看20英尺外至少20秒同时支持自定义休息间隔和提醒开关。技术栈是Flutter做UI和业务逻辑OpenHarmony原生层提供通知与系统级调度能力。如果你正在做工具类、效率类、健康提醒类App或者对Flutter在OpenHarmony上的适配方式感兴趣这篇内容应该能帮你少走不少弯路。1. 项目整体设计思路为什么“通知”是这类App的命门1.1 视力保护场景的需求拆解视力提醒类产品的核心场景并不复杂用户在电脑前连续工作一段时间系统到点提醒他休息、远眺、做眼保健操。可一旦落到产品设计上需求就会拆成三个层次。第一层是“什么时候提醒”。这里涉及提醒的触发策略常见的有固定间隔提醒、每天特定时段提醒、久坐超时提醒等。我的做法是让用户选择30分钟、45分钟或60分钟为一轮每轮结束时弹出一条休息提醒。第二层是“提醒什么内容”。同样的休息提醒文案可以区分成“短休息”——只需要远眺20秒和“长休息”——建议起身活动3分钟让用户根据当下情境选择是否响应。第三层是“用户能不能控制”。这层最容易被忽视却是用户留存的关键。如果App每隔几分钟就强推一条通知用户一定会去系统设置里关掉整个App的通知权限到时候什么提醒都到不了。所以我把通知设置拆成了两个维度一个是用户维度的设置页包含总开关、不同类型提醒的独立开关、提醒间隔选择另一个是系统维度的通知渠道能力要让不同类型的提醒在系统通知设置里也分类展示用户可以单独关闭某一类而不是只能一揽子关掉。这才是通知设置模块真正的工程含义。1.2 为什么选择 Flutter for OpenHarmony项目最早是Flutter写的一套跨端代码原本目标平台是Android和iOS。后来业务要求覆盖OpenHarmony生态我需要评估两条路一条是单独写一个ArkTS原生版本另一条是在现有Flutter工程上做适配。对比之后我选了后者。原因很直接Flutter的UI层和业务逻辑层基本可以原样复用我的页面、状态管理、本地存储都是纯Dart实现不需要动。需要重写的只有原生能力层——通知发布、定时提醒调度、系统设置跳转这些本来依赖Android API或iOS API的部分。如果用ArkTS重写整个AppUI、状态管理、数据层都要重来一遍成本至少多出两倍。这里要提前说明一个现状官方Flutter SDK并不直接支持OpenHarmony需要采用OpenHarmony社区维护的Flutter适配分支也就是flutter_flutter。这个分支提供了构建OpenHarmony产物所需的engine和工具链同时保留了Flutter的标准API。项目里Flutter侧的代码、第三方纯Dart插件基本都能跑但任何涉及原生的能力比如通知、震动、传感器都需要自己封装MethodChannel来调OpenHarmony侧API跟Android插件开发时写PlatformChannel的思路非常像。1.3 通知设置模块的边界划分动手之前我先在项目里把“通知设置”划分成三块职责避免后面写着写着混成一锅粥。第一块是通知发布能力负责把一条通知投递到系统通知中心包括设置通知标题、内容、所属slot类型、通知ID。第二块是提醒调度能力决定什么时候触发通知。这里我没有用Flutter的Timer或者后台运行来做而是直接用系统的代理提醒能力让系统在指定时间点弹出通知App进程即使被系统回收也不影响触发。第三块是设置状态管理包含App内设置页的UI状态、本地持久化以及和系统通知设置的联动。这三块职责分别对应OpenHarmony的notificationManager、reminderAgentManager和App自己的偏好管理模块。把它们拆清楚之后不管是写代码还是排查问题边界都清晰很多。2. OpenHarmony通知能力原理解析2.1 NotificationRequest 与 slotType通知的基础结构在OpenHarmony上发布一条通知核心是构造一个NotificationRequest对象它的结构大致分三层。最外层是请求本身包含通知ID、slotType槽位类型、欲发布的内容中间是内容层声明内容类型和具体内容体最内层是normal字段承载实际展示的标题、正文、附加文案。写一段最基础的通知发布代码大致是下面这样import notificationManager from ohos.notificationManager; let request: notificationManager.NotificationRequest { id: 1001, slotType: notificationManager.SlotType.SERVICE_INFORMATION, content: { notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT, normal: { title: 该休息一下了, text: 站起来活动活动看看远处, additionalText: 护眼小卫士 } } }; notificationManager.publish(request).then(() { console.info(通知发布成功); }).catch((err) { console.error(通知发布失败: ${JSON.stringify(err)}); });这里的slotType是整个通知体系中最重要的概念它决定了通知在系统设置里的分类也影响通知的打扰强度。我整理了一下常用的几种类型slotType分类含义打扰强度建议用途SOCIAL_COMMUNICATION社交通讯强提示适合消息类好友消息、聊天提醒SERVICE_INFORMATION服务提醒普通提示休息提醒、日程提醒CONTENT_INFORMATION内容资讯普通提示新闻类、阅读类推送OTHER_TYPES其他类型较弱提示可能被静默无足轻重的后台信息实际开发中我让不同类型的护眼提醒使用不同的slotType。比如“久坐起身提醒”用SERVICE_INFORMATION“每日护眼操提醒”用CONTENT_INFORMATION。这样用户在系统设置里能分别关闭某一类而不是因为单一槽位被关掉就完全收不到提醒。2.2 定时提醒的正确姿势代理提醒视力提醒App最尴尬的场景是用户打开了权限但App进程被系统回收Flutter里的Timer全部失效到点提醒自然就没了。所以定时提醒绝对不能完全依赖Dart层的定时器。OpenHarmony提供了一类专门解决这个问题的能力叫做代理提醒对应reminderAgentManager。使用方式是把提醒请求注册到系统侧由系统在指定时间到点时直接发布通知。即使App进程已经不存在通知照样能弹出来。我做调研的时候把它和另外两个方案放在一起对比过用ArkTS的Timer并不靠谱进程一旦被回收就失效跟Flutter Timer的处境一样。用闹钟类接口alarmManager也能到点提醒但它主要面向用户明确设置的绝对时间闹钟需要申请额外权限在护眼这种反复注册、动态调整的场景下使用不够方便。WorkScheduler适合延迟执行后台任务比如数据同步、资源预加载它的调度粒度不保证精确到秒用于提醒类场景体验不好。代理提醒的注册接口很简单权限申请则需要在module.json5中声明{ requestPermissions: [ { name: ohos.permission.PUBLISH_AGENT_REMINDER } ] }提醒对象的构造方式和直接发布通知有些类似也需要指定提醒ID、标题、内容以及到点后使用的通知ID和slotType。这块后面实操章节我会给完整示例。2.3 用户开关模型App内设置与系统设置怎么配合OpenHarmony系统里通知的最终控制权在用户手里。用户可以在系统设置-通知管理里关闭整个App的通知权限也可以单独关闭某个slotType的通知还可以设置锁屏是否显示通知、是否允许横幅提醒。这些开关在系统层是独立的App无法通过代码强制打开。所以我在设计App内通知设置页时做了一个关键决定App内的开关负责“业务层”的注册与取消——开关打开时去系统注册代理提醒关闭时取消注册同时提供一个“检查系统通知权限”的入口引导用户进入系统设置页确保系统层的总开关是开启状态。两层开关必须同时打开提醒才能真正生效。另外要注意OpenHarmony的通知发布接口本身并不要求用户在运行时点弹窗授权这跟iOS的推送授权不同。普通通知默认就能发但是否弹出横幅、是否显示在锁屏、是否响铃取决于系统设置。开发者能做的只有把通知合理分类并在用户收不到通知时给他一条清晰的引导路径。3. Flutter侧接入方案MethodChannel封装与平台降级3.1 Dart侧统一封装通知服务在Flutter工程里我用一个Dart的NotifyService类把和原生通知相关的方法统一封装起来上层页面完全不感知平台差异。通道名我取的是com.example.visionguard/notify里面暴露的方法包括publish、cancel、cancelAll。代码大致如下import package:flutter/services.dart; class NotifyService { static const MethodChannel _channel MethodChannel(com.example.visionguard/notify); /// 发布一条普通通知 static Futurebool publish({ required int id, required String title, required String text, required String slotType, }) async { try { final bool result await _channel.invokeMethod(publish, { id: id, title: title, text: text, slotType: slotType, }); return result; } on PlatformException catch (e) { debugPrint(发布通知失败: ${e.code} ${e.message}); return false; } } /// 按通知ID取消通知 static Futurevoid cancel(int id) async { try { await _channel.invokeMethod(cancel, {id: id}); } on PlatformException catch (e) { debugPrint(取消通知失败: ${e.code} ${e.message}); } } /// 取消当前App全部通知 static Futurevoid cancelAll() async { try { await _channel.invokeMethod(cancelAll); } on PlatformException catch (e) { debugPrint(取消全部通知失败: ${e.code} ${e.message}); } } }为什么用单一MethodChannel而不是每个方法一个Channel因为MethodChannel在Flutter和原生侧都有创建和注册成本方法多了以后管理混乱。我习惯一个服务对应一个Channel方法名在invokeMethod里区分这样新增能力时只需要在两边各加一个case不必新增通道。3.2 ArkTS侧实现通道与通知能力OpenHarmony原生侧的通道实现核心是给同一个MethodChannel注册方法处理器解析Dart侧传过来的参数再调用OpenHarmony通知API。我这里的实现结构大致是这样import notificationManager from ohos.notificationManager; // 注册方法通道具体包名以你当前SDK生成的为准 function registerNotifyChannel(channel: MethodChannel) { channel.setMethodCallHandler(async (call) { const args call.arguments as Recordstring, string | number; switch (call.method) { case publish: { const slotType parseSlotType(args.slotType as string); const request { id: args.id as number, slotType: slotType, content: { notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT, normal: { title: args.title as string, text: args.text as string, }, }, }; try { await notificationManager.publish(request); return true; } catch (e) { console.error(publish failed: ${JSON.stringify(e)}); return false; } } case cancel: { try { await notificationManager.cancel(args.id as number); return true; } catch (e) { return false; } } case cancelAll: { try { await notificationManager.cancelAll(); return true; } catch (e) { return false; } } default: return null; } }); }这里面的parseSlotType是我写的一个字符串到枚举的转换函数因为Dart侧传过来的slotType是字符串而OpenHarmony侧是枚举类型。转换逻辑很简单就是switch映射service对应SERVICE_INFORMATIONcontent对应CONTENT_INFORMATIONsocial对应SOCIAL_COMMUNICATION默认回落为OTHER_TYPES。需要注意的是OpenHarmony不同API版本的导入路径可能有差异我在开发时切过几版SDK发现部分类名、包名在不同版本里有细微改动。最稳妥的办法是打开工程里SDK生成的d.ts文件直接确认当前版本的标准写法别直接拿网上的旧代码复制。3.3 非OpenHarmony平台的降级处理因为项目本身是跨端的我除了OpenHarmony还要照顾Android和iOS。最简单的方式是在运行期检测平台OpenHarmony走自研的MethodChannel方案Android/iOS则调用现有的本地通知插件比如flutter_local_notifications。我在Dart层做了个统一接口Futurebool publishReminder(ReminderModel model) async { if (Platform.isOpenHarmony) { return NotifyService.publish( id: model.id, title: model.title, text: model.content, slotType: model.slotType, ); } // Android/iOS 走已有插件逻辑 return LocalNotifyPlugin.publish(model); }这样业务层只需要关心ReminderModel不需要关心底层是哪个平台也方便以后继续扩展新的平台适配。4. 实操过程与核心环节实现4.1 环境准备创建支持 OpenHarmony 的 Flutter 工程先交代一下工程的搭建过程。我用的是OpenHarmony社区的flutter_flutter分支因为官方Flutter SDK目前还不支持构建OpenHarmony的hap包。步骤分四步。第一步安装DevEco Studio并配置好OpenHarmony SDK这部分跟普通OpenHarmony开发一样。第二步下载flutter_flutter分支到本地把里面的bin目录加进PATH用flutter --version确认当前生效的是OpenHarmony分支。第三步使用flutter create --platforms ohos .在当前目录补齐OpenHarmony的ohos工程壳工程。第四步用DevEco Studio打开工程根目录下的ohos目录配置签名和证书之后就能在模拟器或真机上运行了。这里容易被坑的是flutter命令的环境变量。如果你的机器上同时装了官方Flutter SDK和OpenHarmony分支的Flutter SDK一定要确认命令行里实际调用的是哪个。我一开始没注意PATH顺序跑了半天工程里一直不生成ohos目录排查了一圈才发现是SDK选错了。还有一点OpenHarmony版本的Flutter引擎、Dart SDK版本都可能比官方版本滞后一些依赖第三方纯Dart包时要注意版本兼容最好先在工程里跑一遍flutter pub get看看有没有版本冲突。4.2 发布一条基础通知的完整过程工程搭好、MethodChannel两端的注册都完成之后我先做的最基础验证就是在按钮点击事件里发布一条立即通知确认整条链路是通的。Dart侧调用final ok await NotifyService.publish( id: 1001, title: 休息时间到, text: 试试通知是否正常弹出, slotType: service, );ArkTS侧收到调用后发布到系统通知中心此时在系统的通知栏里就能看到这条通知。我在这个阶段重点验证了通知ID的覆盖规则同一个ID再次发布新通知会替换旧通知不会新增一条。这个特性在后面的场景里很有用比如同一个提醒需要更新倒计时文案时直接发同一条ID的通知即可。这里要特别留意slotType对用户体验的影响。我测试时发现如果用OTHER_TYPES发布的通知在没有开启横幅模式的情况下可能只进通知中心不弹横幅、不响铃用户根本感知不到。所以视力提醒这种需要强触达的通知全部统一使用SERVICE_INFORMATION类型在大多数系统设置下会带横幅弹窗提醒。4.3 用代理提醒实现“每45分钟休息一次”基础的立即通知只能验证链路真正的护眼提醒必须依赖代理提醒。我按需求把用户设置的提醒间隔转换成ReminderRequestTimer注册到reminderAgentManager。注册成功后会返回一个reminderId这个ID必须保存下来取消提醒的时候要用。核心代码大致是这样import reminderAgentManager from ohos.reminderAgentManager; function publishRestReminder(intervalSeconds: number) { let timer { reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER, triggerTimeInSeconds: intervalSeconds, title: 该休息一下了, content: 离开屏幕向远处看20秒, notificationId: 2001, slotType: reminderAgentManager.SlotType.SERVICE_INFORMATION }; reminderAgentManager.publishReminder(timer).then((reminderId: number) { console.info(代理提醒注册成功, id${reminderId}); // 保存 reminderId }).catch((err) { console.error(代理提醒注册失败: ${JSON.stringify(err)}); }); }注意triggerTimeInSeconds的单位是秒。如果用户设置的是45分钟传入的就是45 * 60我曾经在联调时写错过单位结果通知在45秒后弹出用户体感上像是被App骚扰了。关于周期性重复提醒不同SDK版本对周期字段的支持差异较大。我采取的方案比较保守不依赖系统周期字段而是把用户一天的处理分成多个一次性提醒。比如从用户开启功能开始每间隔45分钟注册一条提醒当天的提醒注册完成后第一条触发后检查是否还有后续提醒没有了就不再做处理。这样逻辑完全可控也不会被不同版本的API差异卡住。取消提醒时调用reminderAgentManager.cancelReminder(reminderId)即可。把reminderId和业务场景绑定可以在用户切换设置时精准取消某一类提醒而不会误伤其他提醒。我这里是直接封装了一个ReminderStore以业务类型为维度保存reminderId设置页里每个开关都有独立的注册和取消流程。4.4 App内通知设置页的具体实现设置页是用户管理提醒的唯一入口。我用的Flutter页面结构分成三个区域顶部是总开关中间是三类提醒各自的开关底部是提醒间隔选择。总开关的交互逻辑是打开时检查系统通知能力是否正常如果正常注册第一轮提醒关闭时取消全部代理提醒并清空reminderId记录。三个子开关分别控制“短休息提醒”“长休息提醒”“每日护眼操提醒”每个开关变化时Dart层调用对应的方法去注册或取消对应类型的提醒。状态持久化用shared_preferences包保存保存的字段包括总开关状态、三个子开关状态和间隔配置。每次App启动时读取这些状态如果总开关是开着的就根据子开关状态把当天的提醒重新注册一遍。这一步很容易漏用户重启手机后系统侧的提醒记录可能会被清掉App冷启动时的状态恢复逻辑必须补位。UI实现上用SwitchListTile就够核心是状态变更后的联动逻辑。我在代码里把所有提醒的注册逻辑收敛到了一个方法里Futurevoid _syncReminders() { // 先取消全部旧提醒 // 再根据最新开关状态重新注册 }这样做的好处是避免状态混乱。比如用户把总开关开着又关掉了某个子开关再重新打开直接执行一遍同步逻辑把当前设置下的提醒重新注册一遍比逐项比较增量状态要稳得多。5. 常见问题与排查技巧实录5.1 通知不弹出的问题排查表我在联调阶段遇到最多的问题就是“代码明明发布成功了但通知栏就是空的”。这类问题大多数不在代码逻辑而在系统设置和slotType的搭配上。我整理了一个排查表实际排查时按这个顺序走很快现象可能原因处理方式publish返回false系统通知服务被禁用引导用户到系统设置打开通知权限publish返回true但无横幅当前slotType被静默改用SERVICE_INFORMATION类型的slot通知只在锁屏界面缺失锁屏通知被关闭在系统设置中开启锁屏通知通知有声音但无内容横幅模式被关闭让用户在系统设置中打开横幅通知同一提醒只显示一条旧内容通知ID重复被覆盖为不同提醒分配不同ID杀进程后提醒不触发代理提醒没有注册成功检查PUBLISH_AGENT_REMINDER权限另外分享一个调试技巧发布通知后用DevEco的日志窗口先过滤“notification”能直接看到系统通知服务打印的发布结果。报错信息往往比代码里的catch信息详细得多能直接定位到slotType非法还是内容字段缺失。5.2 代理提醒不触发的排查思路代理提醒的排查更隐蔽因为发布时publishReminder可能返回成功但到了时间点什么都不弹。我遇到过的原因主要有四种。第一种是权限没声明。module.json5里没有加ohos.permission.PUBLISH_AGENT_REMINDER接口虽然能调用但提醒不会真正被系统采纳。第二种是App在设置里被用户关掉了通知能力代理提醒到点时系统发布通知会被拦下来。第三种是时间单位算错这个排查起来最快直接算一下设置的时间和实际弹出的时间差就行。第四种是同一时间点注册了多条相同条件的提醒后面的记录把前面的覆盖了导致部分提醒丢失。针对第四种我的建议是给每条代理提醒生成唯一且可追溯的ID。我的做法是用业务类型加时间戳组成reminderId的关联字段既能去重也能在取消时精确定位。5.3 Flutter 与 ArkTS 通道不通的典型情况MethodChannel在OpenHarmony上的表现总体稳定最容易出的问题集中在注册时机。如果Dart侧在ArkTS通道处理器还没注册完成时就调用了invokeMethod就会报MissingPluginException。这类问题通常在App冷启动后立刻调通知接口时出现。我的处理方案是等待Flutter引擎和原生通道都就绪后再触发注册。具体做法是在原生侧主动先完成setMethodCallHandler的注册不依赖Dart侧调用Dart侧在流程启动时先做一次探测调用失败时稍后重试。避免在onCreate之类过早的生命周期里直接发通知。排查通道问题时我一般会在ArkTS的setMethodCallHandler入口先打一条日志打印call.method和call.arguments。如果日志没打出来说明通道未注册或者通道名不一致如果日志打出来但Dart侧拿不到返回值大概率是异步处理链写错了注意处理器一定要返回Future值。5.4 打包与上架过程中需要注意的合规点用Flutter做完OpenHarmony适配后最终要产出hap包并通过上架审核。这一步除了常规的签名配置还要注意一个叫XTSSA认证的东西它全称是OpenHarmony兼容性认证不通过的话应用很难进入官方应用市场。在做XTSSA认证测试时通知模块会被重点检查应用必须在用户明确授权或合理引导后才会注册提醒通知内容不能含有误导、诱导性文案设置页中的开关状态和系统实际行为要一致。我遇到过一次审核反馈说应用在后台频繁注册代理提醒被判定为打扰用户。后面我把默认间隔从30分钟调整为45分钟并在首次开启时主动说明提醒频率审核才通过。另外打包时的hap产物如果接入了第三方SDK要核对有没有超出隐私声明的数据采集行为。护眼提醒类App本身不涉及敏感权限但必须尽量减少权限申请数量。我项目的最终权限只有PUBLISH_AGENT_REMINDER和INTERNET后者还是为了检查更新用的。结语一些实在的话做完了这个项目我最深的体会是跨端框架能解决的是UI和业务逻辑的复用问题而系统级体验比如通知到底能不能按时到、按预期到、按设置到最终还得回到原生能力层去解决。Flutter for OpenHarmony给了我们一套可以复用的开发范式但通知设置这类底层交互必须花时间把OpenHarmony的通知体系和代理提醒机制吃透。最后分享一个我自己反复用到的小技巧把通知ID、代理提醒ID和业务场景做一张对应关系表写在代码注释里。这个项目里我的ID规划是这样的——1000-1999段分配给即时通知2000-2999段分配给定时提醒3000-3999段预留给未来新增的提醒类型。因为通知ID直接决定能不能精准取消、能不能避免覆盖提前规划好后面排查问题会省很多时间。如果你也在做类似的项目试试这个方法应该能帮你少踩几个坑。
