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

晚霞的不甘

432人浏览 · 2026-10-17 19:26:19

晚霞的不甘 · 2026-10-17 19:26:19 发布

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

本地通知是应用与用户保持连接的基础设施。awesome_notifications 是 Flutter 生态里功能最全的通知库之一：通知渠道、计划任务、角标、事件回调一应俱全，方法面超过 40 个。把它带到鸿蒙时，通道契约的完整度是第一位的。

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

适配仓库： oh-flutter/awesome_notifications

适配分支： feat/ohos_awesome_notifications_0.12.1

适配 TAG： 0.12.1-ohos.2

一、先看最终效果

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

图 2：点击“初始化通知组件”后返回 true，初始化流程完成。

验证点	实测结果	证据
Flutter OH 3.47 工程构建	通过	`entry-default-signed.hap`
安装、启动（真机）	通过	图 1
`initialize`	返回 `true`	图 2
`isNotificationAllowed`	真实读取系统开关	图 3
`createNotification`	系统通知真实发布	图 4 / 图 5

图 3：点击“查询通知权限”后返回 isNotificationAllowed = false——这是系统通知开关的真实读取结果，用户在系统里授权后即变为 true。

图 4：点击“创建测试通知”后返回 createNotification = true，通知已提交系统发布。

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

这条库的方法集中在名为 awesome_notifications 的 MethodChannel 上：

Dart AwesomeNotifications
  -> MethodChannel('awesome_notifications')
  -> Android NotificationManager / iOS UNUserNotificationCenter
  -> 通知创建、渠道管理、权限、角标、事件

方法用常量定义（CHANNEL_METHOD_*），从 createNewNotification、cancelNotification 到 requestNotifications、getBadgeCount，覆盖面很广。本次适配把 45 个方法常量逐一映射。

三、实际环境

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

组件	版本
Flutter OH	`3.47.4-ohos-1.0.4`
Dart	`3.13.3`
DevEco Studio	`26.0.0 Release`
HarmonyOS SDK	API 26
测试设备	华为畅享 90 Pro Max，HarmonyOS `7.0.0.105`（API 26）
目标库	`awesome_notifications 0.12.1`

flutter --version
hdc list targets

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

上游包地址是 https://github.com/rafaelsetragni/awesome_notifications，版本 0.12.1 使用 Apache-2.0 License。适配前我在 AtomGit 目标组织中搜索了同名库，没有找到可以直接使用的 OHOS 实现。

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

git clone https://atomgit.com/oh-flutter/awesome_notifications.git
cd awesome_notifications
git switch feat/ohos_awesome_notifications_0.12.1
git log --oneline -5

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

git switch -c feat/ohos_awesome_notifications_0.12.1

关键目录如下：

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

pubspec.yaml 中的关键声明是：

flutter:
  plugin:
    platforms:
      ohos:
        pluginClass: AwesomeNotificationsPlugin

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

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

private async createNotification(call: MethodCall): Promise<boolean> {
  // flutter_ohos 把 MAP 解码成 ES Map，必须用 Map.get 取值
  const content = this.getArgValue(call.args, 'content') as Map<string, Object>;
  const id = this.getArgValue(content, 'id') as number;
  const title = this.getArgValue(content, 'title') as string;
  const body = this.getArgValue(content, 'body') as string;

  if (!notificationManager.isNotificationEnabledSync()) {
    await notificationManager.requestEnableNotification(this.ability!.context);
  }
  await notificationManager.publish({
    id: id,
    content: {
      notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
      normal: { title: title, text: body },
    },
  });
  return true;
}

方法	OpenHarmony 实现
`isNotificationAllowed`	`notificationManager.isNotificationEnabledSync()`
`requestNotifications`	`requestEnableNotification()` 拉起系统授权
`createNotification`	`notificationManager.publish()` 真实发布
`cancel` / `dismiss`	`notificationManager.cancel()` / `cancelAll()`
角标类	`getBadgeNumber()` / `setBadgeNumber()`

通知发布后下拉通知栏可以直接看到：

图 5：下拉通知栏可见该应用发布的真实通知。

七、构建配置与签名

示例工程的目标 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:
  awesome_notifications:
    git:
      url: https://atomgit.com/oh-flutter/awesome_notifications.git
      ref: 0.12.1-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。真机上按本文的截图顺序逐一点击按钮完成验证。

十、适配结果和当前边界

通知能力已完整接入。唯一的平台限制是日程通知（schedule）：鸿蒙的代理提醒需要 PUBLISH_AGENT_REMINDER 权限（受限），普通应用拿不到，本实现把这类调用明确标注为能力边界，不伪造执行结果。即时通知（publish）完整可用。

十一、FAQ

Q1：初始化返回 true 意味着什么？

现象： 通知渠道由鸿蒙系统统一管理，初始化只确认通知能力可用。
解决方法： 按返回 true 继续后续调用。
验证结果： 验证返回 true。

Q2：带日程的通知为什么没有立即弹出？

现象： 日程通知依赖受限权限 PUBLISH_AGENT_REMINDER，普通应用无法申请；即时通知不受影响。
解决方法： 即时通知直接用 createNotification，定时类需求由应用侧到点后再调用。
验证结果： 真机即时通知发布成功，通知栏可见。

Q3：为什么方法这么多？

现象： 上游覆盖通知、日程、角标、权限等多个维度，鸿蒙端按能力分别接入或标注限制。
解决方法： 按需调用。
验证结果： 各自语义已在表中说明。

十二、总结

awesome_notifications 0.12.1 已接入鸿蒙的通知系统：用 notificationManager 实现真实的权限查询、授权弹窗、通知发布、取消与角标读写。真机上成功发布通知并在通知栏看到。

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

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

开源鸿蒙跨平台开发者社区

开源鸿蒙跨平台开发社区汇聚开发者与厂商，共建“一次开发，多端部署”的开源生态，致力于降低跨端开发门槛，推动万物智联创新。

更多推荐

React Native iOS 项目搭建

开源鸿蒙跨平台开发者社区

矩阵正则化在编译阶段的真实收益：三个大厂开源片段的重写与汇编对照

矩阵正则化在编译阶段显著提升性能：对百度brpc、字节跳动sonic-rs、华为OpenHarmony的三个百行级代码片段重写为查表式矩阵化结构后，指令数降为1/4~1/12，条件分支清零，代码体积缩小至1/9~1/13，实测热路径性能提升9%~33%。关闭编译器优化后，结果真实反映手写逻辑收益，验证了“并列选项查表优于分支”的核心法则。