Flutter跨端实践：基于OpenHarmony的通知公告模块开发

1. 复盘高校通知业务：公告模块为什么值得单独做

1.1 四六级报名的通知链路与用户痛点

我在做这个项目之前，一直觉得"通知公告"就是套一个列表页、塞几个接口、上拉加载下拉刷新，工作量大不到哪去。真正跟教务处的老师聊完需求、再把四六级报名的完整流程走了一遍之后，才发现这个模块远没有想象中那么简单。

四六级考试在高校里的通知链路大概是这样的：考试院下发报名通知到学校教务处，教务处再通过官网、OA、辅导员群一层层传递，最后落到学生端。这条链路有几个天然痛点。第一，信息传递层级太多，学生看到通知的时间差很长，经常是报名已经开始了才有人知道。第二，不同院系、不同年级的学生关心的通知内容不一样——大一新生关心"我能不能报"，大二大三学生关心"名额剩多少"，毕业班学生关心"最后一次机会错过了怎么办"。第三，考试相关的通知往往附带大量格式复杂的文件，比如报名操作手册PDF、考场安排Excel、诚信考试承诺书，这些文件在手机端打开一直是个问题。

所以通知公告模块看似是个公用信息流，实际上是一个承担了"时效性、针对性、多格式承载"三大职责的业务模块。如果只是简单地把后台发布的文章按时间倒序排列给用户，那这个模块上线之后一定会被骂。

1.2 Flutter × OpenHarmony 组合的可行性判断

接下来说选型。这个项目比较特殊，学校内部正在推进 OpenHarmony 生态的试点，一体机、阅报屏、校园信息终端都在逐步切换。但学生端的App又不能只跑在 OpenHarmony 设备上，大量学生用的还是 Android 和 iOS 手机。于是"同一套代码，覆盖手机与国产系统终端"就成了硬性约束。

Flutter 无疑是最合适的方案。核心原因有三点：

• Flutter 的渲染引擎是自绘的，不依赖系统原生控件，理论上只要把 Engine 移植到目标平台上就能跑，OpenHarmony 的适配正好走的是这条路。
• 四六级报名系统的 UI 组件不算复杂，主要是列表、表单、富文本、图表，这些恰好是 Flutter 擅长的领域。
• 团队里已经有 Flutter 经验的成员，不需要为了 OpenHarmony 单独拉起一支原生开发队伍。

这里我想多说一句，很多人一听到"跨端"就兴奋，觉得一套代码到处跑，实际上跨端是有代价的。OpenHarmony 跟 Android 虽然都是 Linux 内核衍生系，但它们的应用沙箱、权限模型、System UI 都存在差异。比如 OpenHarmony 的通知服务走的是自己的 Notification Kit，角标逻辑跟 Android 的桌面角标实现也完全不同。所以跨端方案解决的是"UI 和业务逻辑复用"的问题，而不是"所有平台能力无脑复用"。这个认知必须在项目启动前对齐，否则后面每个平台通道的联调都会变成扯皮现场。

1.3 模块边界：通知公告不该和报名流程耦死

需求评审的时候，产品经理最初提的方案是：在报名流程页面顶部加一个"公告轮播"，同时首页放一个"最新通知"入口。这个方案我直接否了。

原因很简单。四六级报名是强时效流程，每年只在特定时间段开放几个星期，页面访问量集中在报名窗口期。而通知公告是全年都有产出的模块，开学通知、缴费提醒、准考证打印、成绩公布、证书领取，每个阶段都有内容。如果把公告嵌在报名流程里，等到报名期一过，这个模块就跟着"死亡"了，后续的通知内容完全失去出口。

所以我把模块边界做了明确划分：公告通知是一个独立的、全局可访问的模块，报名流程通过"指定公告ID跳转"的方式引述公告内容，而不是把公告组件塞进报名页面。这样做的直接收益是：通知的数据源可以独立维护，后台运营可以灵活地给公告打标签、设置置顶、限定可见院系，前端不需要跟着业务方反复改代码。

这个边界划分在技术上的影响是深远的——它让我在设计数据模型时，就意识到公告不是"报名系统的附属品"，而是一个拥有独立的分类体系、发布状态、接收对象范围的内容实体。后面实现的 Tab 分类、院系过滤、已读状态同步，都建立在这样一个清晰的边界前提上。

2. 环境准备：OpenHarmony设备适配与Flutter引擎接入

2.1 RK3568设备树的选择逻辑

开发过程中第一个让我头疼的不是 Flutter 代码，而是 OpenHarmony 的设备适配。项目里用的测试设备是 RK3568 开发板，但 RK3568 的设备树（Device Tree）在 OpenHarmony 仓库里有好几套，社区里经常有人问"到底该选哪一个"。我在这个坑里来回折腾了两三天，梳理清楚后其实逻辑并不复杂。

先解释一下背景。RK3568 是瑞芯微的一颗四核 A55 芯片，OpenHarmony 官方和瑞芯微分别维护了适配它的 kernel 与 device 配置。经常出现的有 rk3568、rk3568-mpi、rk3568-evb 等变体，它们的差异主要在开发板型号的外设配置上——网卡型号、显示屏接口、音频 Codec、USB 布局都不一样。选错了设备树，最典型的现象是：系统能开机，但网口不通、屏幕不亮或者触摸无响应。

我的建议是，不要凭文件名猜，直接用命令查板子硬件信息。在 OpenHarmony 系统启动后，执行 cat /proc/device-tree/model 可以拿到设备型号，再对照 vendor 目录下的配置进行选择。如果板子是自己公司定制的，那就要基于官方默认设备树裁剪外设节点，而不是硬套某一个现成的 dtb。

这里的核心教训是：设备树不是越新越好，而是跟硬件外设匹配才算好。社区里很多人一上来就选最新的设备树文件，结果触摸屏驱动冲突，反过来抱怨系统不稳定。其实问题出在设备树与板子外设不完全匹配。

2.2 Flutter for OpenHarmony 的版本配套

Flutter 官方目前对 OpenHarmony 的支持是通过社区 flutter_flutter 的 OpenHarmony 分支来做的，版本节奏会落后于 Flutter 主线。我当时选的是 Flutter 3.7 对应的 OpenHarmony 适配版本，Dart 版本限定在 2.19 左右。这个版本信息必须提前确认，否则后面做原生插件对接时，版本不匹配会引发各种诡异问题。

我在环境搭建时踩到最狠的一个坑，是 Gradle 插件加载方式。Flutter 的 OpenHarmony 工程第一次构建时，会触发 flutter pub get 并解析 dev.flutter.flutter-plugin-loader 插件，如果插件版本跟 Flutter 版本不匹配，会出现类似 you are applying flutter's main gradle plugin imperatively using the apply script 的报错。这行报错的字面意思很绕，但根本原因只有一个——build.gradle 里插件应用方式不对。

Flutter 主流的 Gradle 集成方式经历了两个阶段：老版本用 apply from: "$flutterRoot/packages/flutter_tools/gradle/flutter.gradle" 这种方式，新版本则要求改用 plugins { id 'dev.flutter.flutter-plugin-loader' version '1.0.0' } 的声明式插件加载。OpenHarmony 的适配层在早期版本里同时兼容了这两种方式，但兼容逻辑有 Bug，导致新版本 Flutter 工具链在 OpenHarmony 工程里误走老路径。

解决方案也很直白：查看 ohos 工程目录下的 build.gradle，明确使用声明式插件加载，并且保证 dev.flutter.flutter-plugin-loader 的版本号在本地 Flutter SDK 的 bin/cache 中存在。如果不存在，就手动执行一次 flutter precache --ohos 之类的命令，把对应平台的基础构件拉下来。这个排查过程比较枯燥，但值得完整走一遍，因为它是 Flutter 与 OpenHarmony 工程结合的底层逻辑。

2.3 从零跑通 Flutter 空工程

环境配套理清后，跑通一个空工程是建立信心的关键步骤。我的操作路径是这样的：

1. 在 DevEco Studio 中新建一个 OpenHarmony 标准的 Stage 模型工程，确认包名、版本号与后续发布到应用市场的预期一致。
2. 在工程根目录初始化 Flutter Module，把 Flutter 工程放在 ohos 目录的同级位置，保持两个工程目录互不干扰。
3. 执行 flutter pub get 后在 ohos 工程里执行构建，把 Flutter Engine 与 OpenHarmony 原生壳工程链接起来。
4. 修改 Entry 模块的 module.json5，配置权限声明，至少包含网络权限和通知权限。

这里我特别想强调第一步。很多从 Android 转过来的人习惯把包名写成 com.example.app，这在调试时没问题，但 OpenHarmony 应用的 bundleName 一旦发布后是不能随意变更的，因为它和签名证书、AGC 后台的 App ID 是绑定的。我见过不止一个项目在联调尾声才想起改包名，结果重签证书、重配后台，白白浪费了两三天。

空工程跑通以后，我建议先做一个最小验证：在 Flutter 侧加载一张网络图片、发起一次 HTTP 请求、弹一个系统通知。这三个动作覆盖了 Flutter Engine 在 OpenHarmony 上的渲染、网络、原生通道三大基础能力。任何一个不通，都要在上业务代码之前排查掉，而不是等到列表页都写完了再回头找底层问题。

2.4 常见环境报错的现场排查

再分享两个实际遇到过的高频报错，都是环境层面容易劝退新人的。

第一个是设备连不上。DevEco Studio 的设备列表里能看到 OpenHarmony 开发板，但点 Run 时提示 OpenHarmony device not supported。这种问题通常不是设备不支持，而是设备没有开启开发者模式，或 HDC（HarmonyOS Device Connector）版本不匹配。OpenHarmony 的 HDC 和 Android 的 ADB 不是同一个工具链，不能混用。开发板的 /system 分区里内置的 HDC 服务版本如果太低，需要先通过命令行升级到与 DevEco Studio 配套的版本，再重插 USB 设备。

第二个是构建时提示找不到 ohos SDK。OpenHarmony SDK 与 HarmonyOS SDK 的 API 版本、目录结构都有差异，DevEco Studio 默认可能装的是 HarmonyOS SDK，需要在 SDK Manager 中手动添加 OpenHarmony SDK 的路径。这个坑的迷惑性在于：IDE 能正常创建工程，构建时才报错，新手会以为是代码问题，实际上纯粹是 SDK 环境问题。

3. 公告列表页：Tab分类、下拉刷新与状态管理

3.1 数据模型与接口约定

公告模块的数据模型，我是按内容实体来设计的，而非按列表展示来设计。Dart 侧的核心模型大致是这个样子：

dart复制class Announcement {
  final String id;
  final String title;
  final String category;      // exam | school | certificate
  final bool isTop;
  final int publishTime;
  final int readCount;
  final bool hasAttachment;
  final String? coverUrl;
  final String summary;
  final String? detailUrl;
}

注意我用了 category 而非 type，因为从业务视角看，公告是按"内容归类"而不是按"功能类型"划分的。后台运营可以创建任意分类，前端用本地枚举映射，这样后端不需要为新增分类而发布新版本。

接口约定上，列表接口我采用了"分类 Tab + 分页游标"的通用设计：

json复制GET /api/announcement/list
参数：category, cursor, pageSize
返回：{ "list": [...], "nextCursor": "xxx", "hasMore": true }

之所以不用传统的页码分页，是因为后台运营会频繁地置顶、下线公告，如果用户翻到第二页后第一条被下线了，第三页的内容就会整体前移，出现重复或遗漏。游标分页以 publishTime + id 作为稳定的排序维度，保证翻页过程中数据不重不漏。这个细节在开发时不容易察觉，但线上运营一旦开始高频操作，传统分页的脏数据问题立刻暴露。

3.2 状态管理选型：为什么最终选了 Riverpod

Flutter 状态管理的选型，团队内部吵了几天。当时摆在桌面上的是三个方案：Provider、Riverpod、Bloc。

先说结论，我最终选了 Riverpod。原因是我认为这个模块的状态形态天然适合 Riverpod 的响应式模型——通知公告模块的核心状态是"列表数据集合"，它需要被多个组件共享：列表页要展示，首页要显示红点，角标要展示未读数，详情页要处理已读回传。这些状态之间存在链路关系，而 Riverpod 的 Provider 可以非常自然地表达"AnnouncementListProvider 派生 unreadCountProvider"这种依赖关系。

对比之下，Bloc 在管理复杂交互流程时优势明显，但在处理"纯数据派生"的场景下需要写大量样板代码，Event、State、Bloc 三个类各写一遍，对一个列表模块来说确实有点重。Provider 足够轻量，但在编译期安全性和跨组件状态追踪上弱于 Riverpod，当项目变大后重构成本偏高。

实现上，我定义了几个核心 Provider：

dart复制final categoryProvider = StateProvider<AnnouncementCategory>(
  (ref) => AnnouncementCategory.exam,
);

final listProvider = FutureProvider.autoDispose
    .family<List<Announcement>, AnnouncementCategory>(
  (ref, category) async {
    final api = ref.read(apiClientProvider);
    final page = await api.fetchAnnouncements(category: category, cursor: null);
    return page.list;
  },
);

final unreadCountProvider = Provider<int>((ref) {
  final list = ref.watch(listProvider).maybeWhen(data: (v) => v, orElse: () => []);
  return list.where((a) => !a.isRead).length;
});

使用 autoDispose 的原因也很实际：用户切走某个分类 Tab 后，对应的列表状态就没有必要继续驻留在内存里，autoDispose 会在监听者消失时自动清理数据，避免内存堆积。这在低端 OpenHarmony 终端上尤为重要——开发板设备的内存往往只有 2GB 到 4GB，远不如主流手机宽裕。

3.3 列表UI与下拉刷新实现

列表页的 UI 结构上，我采用了"顶部分类 Tab + 下拉刷新 + 滚动加载"的标准三件套。顶部 Tab 用 TabBar 实现，分类项从接口动态获取，而非写死在代码里。这样后台新增分类时，前端只需要根据返回的分类列表动态生成 Tab 即可。

我列表项的设计上有两个细节值得说。

第一，置顶公告与普通公告在视觉上必须区分。置顶项的左侧加一条主题色竖条，并在标题前展示一个小旗帜标识。这个设计的业务价值是：学生打开列表的瞬间就能识别出哪些是重要通知，为四六级报名这种时效性极强的场景抢出几秒的决策时间。

第二，公告发布时间不能只看后端返回的时间戳做简单格式化。四六级考试通知的特殊之处在于"今天"和"昨天"的感知非常强烈，比如报名今天开始、缴费明天截止，如果发布时间显示为"2025-04-12 08:30"，学生很难一眼看出紧迫性。所以我实现了相对时间格式化：5分钟内显示"刚刚"，24小时内显示"x小时前"，7天内显示"x天前"，更早才显示具体日期。

下拉刷新我用了 Flutter 自带的 RefreshIndicator，配合 RefreshIndicator.onRefresh 回调重新执行请求。这里有一个容易踩的坑：RefreshIndicator 只能在 ListView 等可滚动组件里生效，如果你用 Column 包了 Expanded + ListView，一定记得把 physics: AlwaysScrollableScrollPhysics() 配在 ListView 上，否则下拉手势在列表未充满一屏时不会触发刷新事件。我因为这个细节排查了整整一个下午。

3.4 轮询拉新与推送兜底

列表页的下拉刷新是用户主动拉取信息的途径，但通知公告这类强时效业务不能完全依赖用户主动刷新。我的方案是"轮询拉新 + 推送兜底"双通道。

轮询策略上，考虑四六级报名期间通知更新频繁，我把应用在前台时拉新的间隔设为 60 秒；非报名期调整为 300 秒。轮询的入口放在全局，而不是只在列表页 initState 里做——因为用户可能停留在首页、我的页面，这时候也需要刷新未读角标。

实现上是用 Dart 侧一个轻量的 Timer，观察应用生命周期：

dart复制void _startPolling() {
  _timer?.cancel();
  _timer = Timer.periodic(
    Duration(seconds: _pollInterval),
    (_) => ref.read(unreadProvider.notifier).refresh(),
  );
}

轮询请求有一个必须处理的边界问题：当 App 退到后台，系统的 Timer 会被挂起，恢复前台时会连续触发多次过期回调。如果不去重，会出现网络请求雪崩。我的做法是在 AppLifecycleListener 里监听状态变化——退后台时取消 Timer，回前台时立即触发一次刷新并重新启动 Timer。这样既保证了时效性，又避免了无效的网络开销。

推送兜底则走 OpenHarmony 的通知服务，由服务端在发布新公告时主动推送一条通知，点击通知后跳转到对应公告详情页。推送通道不依赖 App 是否在前台，能够覆盖轮询无法触达的场景。

4. 公告详情页：富文本渲染与附件下载

4.1 富文本方案对比与选型

公告详情页是这个模块里技术含量最高的部分，因为后台编辑公告时使用的是富文本编辑器，产出的内容是包含 HTML 标签的字符串。而 Flutter 原生并不支持渲染 HTML，这需要引入第三方富文本组件。

我当时对比了三个方案：

最终我选择了 flutter_html，并针对它的不足做了两层优化：一层是 CSS 样式的兜底处理，另一层是特殊内容（如表格、图片）的自定义渲染 Widget。选择它的核心原因是，通知公告的 HTML 内容来自后台富文本编辑器，数据源可控，标签种类基本限定在 p、span、br、img、table、a 这些常用范围，flutter_html 对这些标签的渲染已经足够稳定。

4.2 富文本样式适配的细节

flutter_html 渲染出来是"能用"，但离"好看"还有距离。我用了几种方式把排版细节打磨到位：

首先，标题字号与正文行高需要统一覆盖。后台富文本编辑器可能输出内联样式，也可能输出带 class 的 <p> 标签，我通过 flutter_html 的 customRender 机制，统一抹掉所有内联 style，再用 Flutter 侧的默认样式表控制标题、正文、引用块的间距与行高。这样做的效果是：无论后台运营在编辑器里如何排版，前端页面始终保持一套统一的视觉规范。

其次，表格内容在手机上必须横向滚动。四六级考场安排、成绩段统计通常用表格呈现，手机屏幕宽度有限，如果不做特殊处理，表格会被压扁，内容严重错位。我的做法是给 <table> 标签的自定义 Render 包裹一层水平滚动的 SingleChildScrollView。

最后是图片的处理。富文本里的图片地址经常是外链，直接渲染会面临三类问题：加载慢、可能防盗链、宽高不适配屏幕。我在 customRender 里拦截了 img 标签，用 Image.network + 缓存配合展示，并强制把图片宽度限制为屏幕宽度的 94%，保持原比例缩放。这是提升详情页阅读体验性价比最高的一个改动。

4.3 附件下载与文件存储

公告内容经常附带附件，比如报名操作手册 PDF、考场安排 Excel、考生须知 Word。这些附件在用户场景里必须能够下载到本地，并可以被系统其他应用打开。

Flutter 侧我封装了一个 AttachmentDownloader，核心逻辑分成三步：

1. 发起下载请求，拿到文件字节流。考虑到附件体积可能达到数十兆，下载过程必须支持进度回调，UI 层用 LinearProgressIndicator 展示进度条。
2. 将文件写入应用私有目录。OpenHarmony 的应用沙箱与 Android 类似，读写公共存储需要额外权限申请。为降低权限复杂度，附件默认写入应用私有目录，再通过 FileProvider 类机制授权给其他应用读取。这个方案避免了在 OpenHarmony 上申请存储权限时遇到的白名单审核问题。
3. 下载完成后，通过 MethodChannel 调用原生端唤起可用的文件查看器，或提示用户前往文件管理应用查看。

写文件时我遇到过一个特殊问题：OpenHarmony 的沙箱路径与 Android 不同，path_provider 插件在 OpenHarmony 上如果未适配，getApplicationDocumentsDirectory() 会抛出 MissingPluginException。我当时的处理方案是降级使用原生侧路径拼接，在 MethodChannel 里把沙箱根路径作为参数传回 Flutter，再基于字符串拼接得到 downloads/attachment/ 目录。这个做法不够优雅，但在适配层还没成熟的阶段是最可靠的。

4.4 已读回传与角标联动

公告的已读状态，对用户来说是一个"看没看过"的记忆辅助，对产品来说则要支撑角标未读数的计算。已读回传我采用"进入详情即上报"的策略，而不是"滚动到底部才上报"。理由很简单——四六级通知的内容往往很长，如果要求用户滚到底部才标记已读，那么很多只看了一半的用户会一直被未读红点提示，最终产生通知疲劳，不再关心任何提醒。与其如此，不如进入详情就标记已读，把"已读"理解为"我已查看过这条内容"，而不是"我认真看完了全部细节"。

回传的接口设计为：

dart复制Future<void> markAsRead(String announcementId) async {
  await dio.post('/api/announcement/read', data: {'id': announcementId});
  ref.read(readIdsProvider.notifier).add(announcementId);
}

已读状态在本地缓存一份，用 shared_preferences 存储，每次列表加载时先读缓存过滤已读项，再异步从服务端同步已读状态。这样用户离线打开列表时，已读/未读标识仍然正确，不会因为网络问题体验降级。

角标联动方面，未读数的计算不依赖服务端单独接口，而是"总公告数 - 已读公告数"派生。这个派生关系放在 Riverpod 的 Provider 中，列表数据源一旦变化，所有依赖未读数的组件自动刷新，包括首页的红点、底部 Tab 的角标、桌面的角标数字。联动链路用响应式回调串起来后，代码量不会有任何冗余，每个组件只需要声明自己"依赖什么"，不需要手动管理状态同步。

5. 平台通道：通知、角标与权限的跨端封装

5.1 为什么通知要过平台通道

Flutter 能实现跨端复用 UI 和业务逻辑，但系统级能力比如发送本地通知、设置桌面角标、申请系统权限，依然必须依赖原生代码的调用。在 OpenHarmony 上，这些系统能力没有 Flutter 官方插件可以直接使用，必须自己写 MethodChannel。

我把公告模块所需的原生能力梳理成了三个通道：通知通道、角标通道、权限通道。每个通道只暴露最小必要的接口，避免把过多的原生逻辑塞给 Flutter 侧。

选型时还考虑过使用现成的 flutter_local_notifications 插件，但它在 OpenHarmony 上的适配状态并不理想，插件的 Android 实现依赖 Android 专属的 NotificationChannel 机制，OpenHarmony 的通知服务 API 与之差异较大。与其等待社区适配，不如直接用 MethodChannel 写一个精简实现，几周后真实使用下来，稳定性和维护成本都更可控。

5.2 MethodChannel 的接口设计

Flutter 侧的通道调用代码如下：

dart复制class NotificationBridge {
  static const platform = MethodChannel(
    'com.example.cet/notification',
  );

  static Future<void> showNotification({
    required String title,
    required String body,
    String? payload,
  }) async {
    await platform.invokeMethod('showNotification', {
      'title': title,
      'body': body,
      'payload': payload ?? '',
    });
  }

  static Future<void> setBadgeCount(int count) async {
    await platform.invokeMethod('setBadgeCount', {'count': count});
  }
}

接口设计有一个值得注意的原则：**Flutter 侧只传业务参数，原生侧负责平台差异实现。**比如 showNotification 传的是 title、body、payload，而不是通知 ID、渠道 ID 这类平台概念。通知 ID 由原生侧在实现里自动生成，渠道 ID 从配置常量读取。这样当未来需要增加 HarmonyOS NEXT 或 iOS 支持时，Flutter 侧代码完全不用动，只新增平台实现即可。

通道名称我统一加了 com.example.cet/ 前缀，避免多个 Module 并行集成时通道名冲突。

5.3 OpenHarmony 侧能力实现

OpenHarmony 侧的实现入口是 Plugin 类，核心逻辑如下：

typescript复制export class NotificationPlugin implements Plugin {
  private context: common.UIAbilityContext;

  onInitialize(context: common.UIAbilityContext): void {
    this.context = context;
  }

  onMethodCall(call: MethodCall): Promise<Object> {
    switch (call.method) {
      case 'showNotification':
        return this.showNotification(call.arguments as NotificationData);
      case 'setBadgeCount':
        return this.setBadgeCount(call.arguments as number);
      default:
        return Promise.reject(new Error(`Unsupported method: ${call.method}`));
    }
  }
}

OpenHarmony 的通知发布走 notificationManager.publish 接口，需要先构造 notificationManager.NotificationRequest。这里有个细节：OpenHarmony 的通知类型分为普通文本通知、长文本通知、图片通知、社交通知等，分别对应不同的模板类。对公告场景来说，我使用 normal 类型加上 contentTitle 和 contentText 即可满足需求。如果需要展示更丰富的内容，比如带上公告摘要图片，就要切换到图片通知类型，并额外处理好图片资源的 URI 转换。

角标方面，OpenHarmony 的 setBadgeNumber 可以设置应用图标的角标数字。但角标的生效有一个前置条件：桌面启动器必须支持角标显示，且应用需要配置 badge 权限。部分三方桌面如果不支持角标，调用不会报错但也不会显示，这一点在测试时需要提前确认，否则会误以为功能未实现。

5.4 权限申请的生命周期处理

通知权限在 OpenHarmony 上是动态申请的，不能像旧版本一样在 module.json5 里声明即可。申请的时机我选择在用户首次打开公告列表页时触发，而非 App 启动时。这个设计的逻辑是：用户刚打开 App，还没理解这个应用的价值就弹权限框，拒绝率很高。而公告列表页能直观地展示通知内容，此时引导授权"及时接收考试通知"，接受率会显著提升。

权限回调的处理我封装成了一个 Completer：

dart复制Future<bool> requestNotificationPermission() async {
  final result = await platform.invokeMethod('requestNotificationPermission');
  return result == true;
}

这里踩过一个小坑：权限弹窗是异步的，用户点击允许或拒绝后，原生侧通过 onPermissionRequestResult 回调返回结果。如果 Flutter 侧在主线程同步等待，会出现 UI 卡死。正确做法是原生侧先返回一个 Future，等权限结果回调后再 resolve 这个 Future。

还有一个容易忽略的细节：如果用户第一次拒绝了权限，之后主动去系统设置里开启，App 需要感知这个变化。我通过监听应用从后台回到前台的生命周期事件，在 onResume 时重新检查一次权限状态，并同步到 Riverpod 的通知权限 Provider。否则用户开了权限，App 里的开关状态却仍然是旧的，会造成"我明明开了怎么还是不行"的糟糕体验。

6. RK3568真机调试与HAP打包：从开发到上机的完整链路

6.1 设备连接与调试模式

OpenHarmony 开发板真机调试与 Android 有些类似，但也有不少差异。连接 RK3568 开发板后，DevEco Studio 的 Device 面板能看到设备，但 Run 按钮是可用的还是灰色，取决于设备的 HDC 服务是否正常启动。

我遇到过的典型情况是：ADB 能识别设备，但 DevEco Studio 提示 HDC server version is too low。原因是开发板烧录的 OpenHarmony 系统版本较早，HDC 服务老旧，而 DevEco Studio 自带的新版 HDC 客户端无法与它建立调试通道。解决方法是把开发板系统升级到与 IDE 配套的版本，或者手动更新开发板上的 HDC 服务。

RK3568 开发板通过 USB 连接时有个电源问题需要特别留意：部分开发板的 USB 口供电能力不足，同时给板子供电和传输数据时，会出现设备频繁断开重连。我建议使用带独立供电的 USB Hub，或者直接用支持数据同步的 Type-C 线，避免用那些"只能充电不能传数据"的劣质线。这类问题排查起来特别让人崩溃，因为设备时断时续，日志难以稳定抓取。

6.2 HAP 打包与安装部署

Flutter 代码开发完成后，打包 OpenHarmony 应用产出的是 .hap 文件。打包链路是：

code复制ohos 工程 Debug Build -> 生成 .hap -> HDC 安装到设备

调试阶段我直接用 DevEco Studio 的 Run 按钮构建并部署，这个流程与 Android Studio 差不多。但正式发布时需要走 Signing 流程，OpenHarmony 应用的签名比 Android 更严格——没有签名的 HAP 无法在真机上安装，必须先在 AGC 后台创建应用并配置签名证书。

签名证书的配置有一个关键点：bundleName、证书文件、Profile 文件三者必须一一对应。我在第一次打包时因为证书 Profile 中配置的 fingerprint 与本地签名证书不一致，安装时报 Failed to install HAP with error code: 9568312。这个错误码比较抽象，实际上就是签名信息与证书不匹配。处理方式是回到 AGC 后台，用 keytool 重新生成证书指纹并同步到 Profile。

6.3 上线遇到的两个真实问题

第一个问题是低端设备上的内存告警。RK3568 开发板只有 2GB 内存，Flutter 引擎加载 + 图片列表渲染 + 富文本详情页同时存在时，内存占用经常飙到 1.5GB 以上。问题最严重的场景是用户从列表页进入详情页，反复来回操作五六次，系统开始丢帧甚至杀掉应用进程。

我的优化组合拳有三招：

• 列表页图片统一启用 cacheWidth，只加载符合实际显示尺寸的像素数据，避免内存中保存原图。
• 详情页的富文本图片在 WebView 中渲染，通过路由切换时销毁并重建详情页，避免详情页实例常驻。
• 列表页使用 ListView.builder 惰性构建，保证屏幕外条目不创建 Widget。

第二个问题是通知通道在锁屏后的行为差异。OpenHarmony 通知在系统设置里可以配置"锁屏时是否显示通知内容"，默认可能是隐藏内容。有些学生反馈"收到通知但只看到'你有一条新通知'，看不到具体标题"。我后来在发布通知时显式设置了 lockScreenVisibilityType 为公开类型，确保锁屏状态下也能看到公告标题和摘要。当然这会涉及隐私，所以我做了一个配置项：如果公告内容包含敏感信息如个人成绩，则发布时使用隐藏内容的锁屏策略。

这里想额外说一句，真机调试与模拟器调试有本质差异，尤其是资源受限的 OpenHarmony 开发板。模拟器上流畅跑通的代码，真机上可能因内存、CPU、网络环境影响而出现完全不同的表现。所以"真机调试是最后一道防线"这句话，在跨端开发里是必须刻在心里的。

7. 体验优化：首帧时间、缓存策略与字体适配

7.1 首帧时间从2.1秒降到0.8秒

通知公告模块首帧时间最初的实测数据不太理想：RK3568 上从点击入口到列表首屏可见，平均需要 2.1 秒。这在开发阶段不太容易察觉，但一旦用户真实使用，感知就是"这个 App 有点卡"。

定位过程我分三步走。先用 Flutter DevTools 的 Timeline 记录首帧耗时分布，发现耗时集中在两个方面：网络请求串行等待和图片加载阻塞。原来列表页在 initState 里先请求分类列表，等分类返回后再请求第一个 Tab 的公告列表，这导致时间链路是串行的。网络正常时还能接受，但校园网环境一波动，首帧时间就直接拉满。

优化方案是"并行请求 + 本地缓存兜底"。分类列表和第一页公告列表同时发起请求，并且先把上一次缓存的公告列表立即展示出来，等新数据返回后做增量更新。这样用户在弱网环境下也能立刻看到内容，而不是对着一个白屏转圈。

实际操作后的耗时分拆：本地缓存展示约 0.2 秒，新数据更新在网络正常时约 0.6 秒，总体首帧耗时稳定在 0.8 秒左右。对于校园网这种高延迟场景，这个指标已经可以接受。

7.2 图片缓存与列表回收

公告列表里的封面图、详情页里的富文本图片，加载策略直接影响流畅度。Flutter 自带的 Image.network 不带缓存，页面重建时图片要重新下载，这是很大的浪费。我引入了 cached_network_image 插件，对本地磁盘缓存和内存缓存做了两层管理。

但缓存也不是万能的。缓存过期时会回源请求，如果图片 CDN 响应慢，列表滚动会明显卡顿。我的处理是在自定义的图片加载失败回调中，先展示本地占位图，并异步重试。这个体验策略让学生即便在网络波动时，也不会看到"一片灰"。

另一个容易被忽视的优化点是图片区域的内存占用。列表封面图显示宽 120 像素、高 160 像素的区域，如果不指定 cacheWidth，Flutter 会把原图（可能是 1080P 的图片）完整解码到内存，再缩放到显示区域，内存开销极高。显式指定 cacheWidth: 360 后，解码后像素只有显示所需的约三倍大小，视觉上不会糊，内存却降了一个数量级。

7.3 大字体的适配

四六级通知面向全校学生，其中不乏视力不佳的用户。系统字体设置到超大字号时，公告列表的标题容易溢出单行区域，详情页的正文行高也会显得过密。

我的适配策略是：

• 列表标题使用 maxLines: 2 加上 overflow: TextOverflow.ellipsis，允许最多两行展示，再多就省略。注意要从 TextOverflow.ellipsis 配合 softWrap: true 才能正确处理中文字符截断，否则省略号可能出现在半个字符位置。
• 详情页正文的行高不写死，而是用 height: 1.6 相对行高，基于字体大小自动缩放。
• 关键操作按钮（如"立即报名"）使用 FittedBox 包裹，避免字体放大后按钮被截断。

字体适配做完后，我用系统自带的字体缩放测试功能从 100% 到 200% 逐级验证了一遍，确保每一级都无布局错乱。这个细节可能看不出来有多重要，但对视力受限的用户来说，一个正常缩放的公告正文与一个溢出截断的公告正文，体验差距是巨大的。

8. 复盘总结与后续迭代思路

做这个模块最大的体会是：跨端开发的核心难点不在 Flutter，而在系统差异的理解与隔离。Flutter 承诺的"一次编写、到处运行"在 UI 层基本成立，但平台能力并不能自动统一。通知、角标、权限、文件存储这些系统级能力，每端都有各自的实现方式和生命周期规则，必须在项目初期就设计好抽象的边界，否则后续每个真机适配问题都会引入临时补丁，代码会越来越臃肿。

我个人的迭代思路有三条：

第一条是持续跟进 Flutter 官方与社区的 OpenHarmony 适配版本，待适配成熟后把 MethodChannel 方案替换为官方的联邦插件方案，减小编排代码。第二条是补充公告模块的离线能力，把列表与详情在 WiFi 环境下自动预取到本地，弱网时从缓存读取，这个方向对校园网环境的价值会非常大。第三条是逐步引入更细粒度的内容推荐，根据学生所在的院系、年级、报名状态，在公告列表里做优先级排序，比如大一新生优先看到报名资格说明，毕业生优先看到成绩单领取通知。

如果你正在做类似的跨端项目，我的建议是：先把平台能力通道的抽象层做扎实，再往上层堆业务功能。前两周多花点时间核对版本、跑通最小链路、在真机上验证三个基础能力，后面省下来的时间远不止两周。