去年年中，我接了手一个不算大但足够折腾的项目：在 OpenHarmony 设备上做一个生活助手 App，最核心的模块是收入分析统计——记录每笔收入，按日、周、月、年汇总，算分类占比，再看趋势。当时团队里没有人正经碰过鸿蒙生态，我又不想放弃 Flutter 那套跨端优势，于是直接选了 Flutter for OpenHarmony 的方案。等真上手才发现，这条路能走通，但不是每条路都通畅。
这篇就把收入分析统计这条完整链路拆开给你看，从工程搭建、数据层设计、原生桥接到图表渲染，把我踩过的坑、后来确定下来的方案、以及可以直接抄的代码思路，一次性讲清楚。适合已经写过一段时间 Flutter、准备往 OpenHarmony 上迁移的开发者。如果你只是听说过 OpenHarmony 但完全没上手，也能通过这篇文章建立一条清晰的实战路线。
1. 项目思路与技术选型：为什么是 Flutter for OpenHarmony
1.1 这个项目到底要解决什么问题
生活助手这个词其实很宽泛，但落到我们项目里，需求非常具体：用户每天可能产生多笔收入，比如工资、兼职、红包、理财收益，每一笔收入都需要记下来，并且能够随时查看“我最近赚了多少”“哪一类收入占大头”“这个月环比上个月有没有起色”。
收入分析统计模块要承担三件事：录入与存储、聚合与计算、可视化展示。录入看着简单，但涉及分类选择、备注、时间修正；聚合计算要支持按日、周、月、年多维度切换；展示则要兼顾列表明细和图表概览。如果只是临时用，完全可以靠 Excel 手动统计，但做成 App 就意味着要处理本地持久化、页面状态、各种异常输入，以及对旧数据的增量修改。
选择 OpenHarmony 作为运行平台，是因为项目目标设备跑的是开源鸿蒙系统，和通用 Android 设备不能直接互换。但业务逻辑本身又非常通用，未来还想复用回 Android / iOS 甚至 Windows 桌面端。这种“平台冷门、逻辑通用”的组合，天然就适合 Flutter 这种跨端框架介入。
1.2 Flutter、ArkUI 与原生开发怎么选
OpenHarmony 官方主推的 UI 框架是 ArkUI，基于 ArkTS 语言和声明式语法。从纯粹“适配系统”的角度看，ArkUI 肯定是最贴合 OpenHarmony 的，但问题在于，我们团队对 ArkTS 不熟，而且团队内部还有一批现成的 Flutter 业务代码积累，包括状态管理、自定义图表组件、数据校验逻辑，这些代码在 OpenHarmony 上用 ArkUI 重写一遍，周期不可控。
Flutter for OpenHarmony 的思路就不一样：Flutter 的 UI 层代码几乎不需要改，状态管理、路由、主题这些机制全部保留，只是底层渲染和平台通道做了 OpenHarmony 适配。上层的 Dart 代码完全可以跨 Android、iOS、Windows 复用。对我们来说，这就是“一套代码多端覆盖”的核心价值。
另一点是，Flutter 在图表绘制和动画表现上确实成熟。收入统计分析最吃 UI 的部分是图表：柱状图、折线图、饼图、趋势面积图。Flutter 里用 CustomPaint 或者成熟的图表库都能做，交互手感也稳定。ArkUI 虽然也有 Canvas 组件，但社区组件生态明显还没有跟上，真要画一套复杂交互图表，开发成本会高不少。
当然，也得客观说缺点。OpenHarmony 上的 Flutter 生态还处于“持续追赶”的状态，很多第三方插件默认支持的是 Android/iOS，到了 OpenHarmony 上要么自己适配，要么绕道走平台通道。所以项目里我定了一个原则：能用 Dart 层解决的，绝不依赖原生插件；必须走原生能力的，统一封装成平台通道接口。
1.3 目前生态基础与版本选择
做技术选型时最怕的是“框架还在半成品状态”。我专门查了 OpenHarmony SIG 组维护的 Flutter 分支，发现它已经有一套相对独立的构建链路，OpenHarmony SDK 配合 DevEco Studio 可以打包出能在鸿蒙设备上跑的应用。支持的 Flutter 版本也稳定在 3.x 系列，和社区主流版本基本保持同步。
实际动手时，我建议直接照官方分支的 release 来，不要追 Flutter 的新大版本。比如我当时用的是 3.x 分支，整个团队开发下来，Dart 语言特性、Widget 体系、渲染流程都和标准 Flutter 保持一致，没遇到“API 对不上”的断裂感。渲染引擎方面，OpenHarmony 适配当前更多还是走 Skia 路线，Impeller 在 OpenHarmony 上的表现要看分支进展，至少现阶段不要指望默认启用。这个认知能帮你少走弯路：别拿网上关于 Impeller 性能提升的文章直接套到 OpenHarmony 项目上。
2. 工程搭建与项目结构设计
2.1 开发环境准备：DevEco Studio、SDK 与 Flutter 分支
第一步是搭环境。你需要同时装两套东西：OpenHarmony 的开发环境，和 OpenHarmony 分支的 Flutter SDK。
我实际的顺序是：先装 DevEco Studio，并且把 OpenHarmony SDK 配置好，保证能用 DevEco 建一个空白鸿蒙工程并跑起来。这一步的目的是验证设备连接、签名、打包链路是通的，别一上来就混合 Flutter，否则出了问题根本分不清是 Flutter 的问题还是鸿蒙工程的问题。
接着准备 Flutter SDK。不能直接用官方 Flutter 版本，要去 OpenHarmony SIG 维护的 flutter_flutter 仓库拉取对应发布分支。仓库拉下来后，把 SDK 路径配到环境变量，命令行执行flutter doctor确认 OpenHarmony 相关项被识别。再连上开发板或模拟器，用 hdc 命令（OpenHarmony 的设备调试工具）确认设备在线。
一个小建议：DevEco Studio 的版本和 OpenHarmony SDK 的版本，一定要以官方文档的兼容矩阵为准。我最初图省事，装了最新版 IDE，结果和 Flutter 分支指定的 SDK 版本不匹配，签名打包阶段折腾了两天。后来按文档严格对齐版本，编译一次通过。
2.2 创建项目：从标准 Flutter 工程到 ohos 平台目录
环境就绪后，用 Flutter 命令行创建标准工程：
flutter create income_assistant创建出来的项目默认带 android、ios、web 等目录。这里的关键在于，OpenHarmony 分支的 Flutter 工具链支持生成 ohos 平台工程目录，你会看到类似ohos/entry的结构，这就是鸿蒙侧的宿主工程。如果工具链版本没有直接识别，也可以比照官方模板手工补齐，但不推荐，因为涉及 Module 配置文件、Ablity 声明、构建脚本，手写容易漏。
工程跑起来后，大致目录结构是：
income_assistant/ ├── lib/ │ ├── main.dart │ ├── domain/ # 实体与业务规则 │ ├── data/ # 数据源、仓库实现 │ ├── presentation/ # 页面、组件、状态管理 │ └── platform_bridge/ # 平台通道封装 ├── ohos/ │ └── entry/ │ └── src/main/ets # 鸿蒙原生侧代码我特意把platform_bridge独立出来，是因为收入统计功能里免不了调用原生能力：数据库访问、文件读写、系统分享、日历事件等。这些调用统一收敛在一个目录，后续换平台、换实现方式，影响面可控。
2.3 代码组织：Dart 库拆分用不用 part
项目代码量上来后，模块化就变成刚需。收入分析统计这个功能，我拆了三层：数据仓库层、统计计算层、页面展示层。这三层如果全堆在一个文件里，后面维护会特别痛苦。
Dart 里组织库代码有两种方式：export组合公开接口，part/part of拆分内部实现。热搜词里有人问 Flutter 中 part 的用法，这里正好说一下实战感受。
同一个库内部逻辑非常长、又不希望对外暴露内部拆分文件时，part是合理的。我把统计计算模块拆成五个 part 文件，比如income_statistics.dart作为主库，aggregation.dart、category.dart、trend.dart作为 part。主库文件负责对外接口，part 文件实现具体算法，外部 import 主库就够了，内部细节不会泄漏到 import 方。
但我的经验是，part 不要滥用。跨库互相引用时，part 没有独立的作用域边界，容易形成隐式耦合。团队协作时，新人不清楚某个符号来自哪个 part，定位代码也得来回跳。如果拆分仅仅是“文件太长”，优先考虑抽成独立库然后 export；只有在一个大状态机或一组强内聚函数的内部，才值得用 part。
3. 收入分析统计核心设计与数据层
3.1 数据表结构：收入明细、分类与预算
收入统计首先得有可靠的数据模型。我设计了三张核心表：income_record收入流水表、income_category收入分类表、income_budget月度预算表。
income_record是流水主表，字段包括：id、title收入名称、category_id分类外键、amount金额、record_time记录时间、remark备注、create_at/update_at时间戳。这里有一个非常容易踩的坑：金额字段千万不要用浮点数。0.1 + 0.2 这类浮点误差在统计汇总时会被放大，月度汇总后可能多出几分钱，对账很难看。我最终把金额统一换算成“分”存整数，展示时再除以 100。
income_category分类表要冗余一下图标和颜色字段，因为统计页的分类占比图需要按分类展示颜色，列表里也要显示图标。分类属于低频变更数据，可以在 App 启动时一次性缓存到内存。
income_budget表服务于“预算对比”功能。每条记录对应一个分类和一个月份，比如“3 月红包类预算 500 元”。做汇总时，把实际收入月按分类归拢后，和预算表做一次关联就能得出完成率。
3.2 数据库选型：原生 RDB 还是 SQLite
Flutter 在 Android/iOS 上最常用的本地数据库是 sqflite，但到了 OpenHarmony，这个插件没有官方适配版本，强行引入会遇到编译失败或运行期找不到插件实现的问题。
我的做法是绕开 Dart 层数据库插件，直接走平台通道，让 OpenHarmony 原生侧操作官方的关系型数据库 RDB。为什么选原生 RDB？第一，它和系统集成度最高，性能有保障；第二，OpenHarmony 提供关系型数据库的建表、增删改查、SQL 查询能力，对收入统计这种“按时间聚合、按分类分组”的需求完全够用；第三，避免额外引入适配不稳定的第三方组件。
具体分工是：Flutter 层定义统一的 Repository 接口，内部通过 MethodChannel 调原生；原生侧负责真实 SQL 执行和建表。业务层的调用看起来就像本地 API，不关心底层是不是真的跑在 SQLite 上。
3.3 统计口径与聚合计算逻辑
收入统计最怕“统计口径不一致”。月初定义好规则，写到代码里，后续别乱改。我这边定的规则是：
- 按日统计：取
record_time为当天的流水，汇总金额。 - 按周统计：以周一到周日为一个周期，汇总到周的最后一天。
- 按月统计：按自然月分组，
record_time落在当月范围内的流水都算。 - 分类占比：某时间段内，每个分类的收入金额占总收入的比例。
- 环比：本月总收入对比上月总收入的增长百分比。
- 同比：本月对比去年同期的增长百分比。
聚合计算放到原生 SQL 里做，不要把流水全量拉到 Flutter 层再 for 循环加总。数据量小的时候感受不到差异，一旦流水有上万条，全量加载的血泪教训立刻就来。举个例子，月度汇总一条 SQL 就能搞定：
SELECT category_id, SUM(amount) AS total FROM income_record WHERE record_time >= ? AND record_time < ? GROUP BY category_id;日期边界的计算建议在 Flutter 层先做，传参给原生。record_time存毫秒时间戳，查询上月区间就计算月初零点和下月零点，边界值用>= start AND < end，避免月末那天被重复统计。
数据层的设计原则就是：数据库负责“算数”，Dart 层负责“展示和交互”。统计页面只是把聚合结果喂给图表，不需要关心明细表长什么样。
4. Flutter 与 OpenHarmony 原生能力桥接
4.1 MethodChannel：调原生能力的标准姿势
收入统计模块需要多次和原生交互：初始化数据库、建表、写入收入记录、按条件查询聚合结果、删除记录。这类“调用一次等结果”的场景，统一用 MethodChannel。
Flutter 侧封装一个通道类，所有调用接口都返回 Future。以收入查询为例：
class IncomeBridge { static const channel = MethodChannel('com.income.assistant/db'); Future<List<IncomeRecord>> queryIncome({required DateTime start, required DateTime end}) async { final result = await channel.invokeMethod('queryIncome', { 'start': start.millisecondsSinceEpoch, 'end': end.millisecondsSinceEpoch, }); ... } }原生侧在ohos/entry/src/main/ets/plugin目录下新建插件类，注册同名 channel，处理queryIncome方法。原生实现里用 RDB 的查询接口执行 SQL，再把结果映射成 JSON 或 Map 返回。
这里有几个非常实际的注意点：
第一，通道名称两端必须完全一致，大小写都不能错，否则静默失败。第二，invokeMethod的参数尽量用基本类型：字符串、数字、布尔值，不要直接传 Dart 对象。原生侧收到的参数，类型解析是最容易出问题的地方。第三，耗时查询注意异步，原生侧方法回调结束时 Flutter 端才能拿到值，如果原生回调没走，Flutter 侧会一直挂着，超时后再抛 PlatformException，所以一定要在原生侧 try-catch。
4.2 EventChannel：监听数据变化与持续事件流
MethodChannel 适合“一问一答”，但生活助手场景里还有一类需求：数据在原生侧发生变化时，要主动通知 Flutter 页面刷新。比如用户通过通知栏快捷入口新增了一笔收入，或者原生侧同步完成了一笔来自其他设备的流水，这时 Flutter 页面如果还在统计页，必须刷新图表。
这类“持续事件流”用 EventChannel。我们注册了一个income_change_events通道，原生侧在 RDB 数据变更后主动向 Dart 侧发送事件。Flutter 侧：
static const eventChannel = EventChannel('com.income.assistant/events'); Stream<dynamic> get incomeChangedStream => eventChannel.receiveBroadcastStream().map((event) => event);收到事件后，触发 Cubit 重新加载数据，图表自然更新。这里我踩过一个坑：EventChannel 在页面销毁后，订阅者如果没有 cancel，原生侧还继续推事件，轻则日志刷屏，重则崩溃。所以页面生命周期里一定要配对订阅和取消。
EventChannel 的原理，简单说就是原生侧借助事件流回调，把数据源源不断地推给 Dart 层。它不适合做“查询返回值”，只适合做“持续通知”，项目里用的时候要保持这个思维。
4.3 生活助手其他原生能力怎么接入
除了数据库，生活助手通常还需要：把收入分享到微信/系统分享；打开系统日历记录提醒；选择发票图片；读取剪贴板识别收款金额。这些原生能力在 Android/iOS 上都有成熟插件，但 OpenHarmony 上很多插件不可用，只能自己写 MethodChannel。
我的建议是建立统一的PlatformBridge层，背后用工厂模式按平台分发。Dart 层业务代码只依赖抽象接口，不直接触碰 MethodChannel。这样以后如果某个插件在 OpenHarmony 上出了官方适配，替换底层实现即可，UI 层不用改。
有一次做“系统分享”需求，我在 OpenHarmony 原生侧注册了一个shareText方法，Flutter 层只需要把文本传过去，原生侧通过系统分享能力拉起分享面板。整个过程其实不复杂，但要注意“拉起系统面板”和“分享完成回调”之间存在时序，成功回调一定要绑定在分享面板关闭之后。
5. 统计页面的具体实现
5.1 基于 Cubit 的状态管理架构
统计页的交互状态，用flutter cubit来管理非常合适。收入统计数据涉及多个维度，任何一次切换月份、切换图表类型，都要触发数据加载并更新多个视图模块，如果靠 setState 散在各处，状态很快就失控了。
我的状态结构是：
class IncomeOverviewState { final DateTime currentMonth; final IncomeSummary summary; final List<CategoryStat> categoryStats; final List<TrendPoint> trend; final bool isLoading; final String? error; }IncomeOverviewCubit 对外暴露loadMonth(DateTime month)、switchChartType()、refresh()等方法。页面上的月份选择器、图表刷新按钮、下拉刷新，全部只和 Cubit 通信，页面自身不直接调用数据库接口。
这样做的好处非常直接：导航页面切换后，Cubit 实例如果挂在父级或者全局状态容器里，统计页被销毁再回来，数据还是会从 Cubit 上一次的 state 快速恢复，不需求重新加载一遍。这也顺带解决了很多人问的“Navigator 切换页面后状态丢失”问题，把数据状态提升到页面之外的 Cubit，页面状态自然不依赖 Widget 树。
5.2 月度收入柱状图和趋势折线图
图表这块我最终没有用第三方图表库，直接用 Flutter 的 CustomPaint 自绘。原因前面说了，OpenHarmony 上第三方 Flutter 插件的兼容性有待验证，而收入统计需要的图并不复杂，柱状图、折线图、饼图，自绘反而更好控制性能和交互。
柱状图展示当月每天或每周的收入，横轴是日期，纵轴是金额。绘制时核心是坐标换算：把金额最大值映射到画布高度，再把日期数量等分到画布宽度。每个柱子的宽度，我用(canvasWidth - paddingLeft - paddingRight) / dayCount * 0.6算出，留出柱间距，避免柱子紧贴看起来挤。
折线图用于趋势分析。把当月每天的收入按时间排序，依次连接每个点。折线图最需要注意的是纵轴刻度，绝不能每次都用最大值直接当顶刻度，要向上取整到“看起来舒服”的刻度。比如最大金额是 3289，我会取 3500 作为顶部刻度，这样图表不会因为坐标轴顶到天花板而显得压抑。
悬停交互上，我通过 GestureDetector 监听水平拖动，根据坐标反推当前柱子/折线点索引，再显示一个 Tooltip 显示具体金额。这里有个小技巧：反推坐标时一定要考虑 padding，很多人把图表区域和画布坐标混在一起，点出来的位置永远偏。
5.3 分类占比图与明细列表联动
分类占比我用的是饼图。饼图的绘制比柱状图稍微复杂一点，因为要按角度画扇形，还要在扇形中心拟合出占比文字。计算角度时，先求出全部分类金额总和，每个分类占比pct = amount / total * 360，再用drawArc按起始角度和 sweepAngle 画出来。
占比文字的位置，是按中分线的角度算出半径一半的坐标点。这块要特别注意，中文文字宽度和英文不一样，左侧扇形的文字往左偏、右侧往右偏，否则文字会压到扇形边缘，很难看。
明细列表和图表联动，我用一个简单的规则：点击饼图某个扇形，底部列表自动滚动到对应分类的明细区域，并高亮该分类的条目。这个联动如果每次点击都去查数据库，交互会有明显卡顿。我的做法是，分类明细在加载饼图数据时一并准备好，内存中做一个分类 ID 到数据对象的 Map，点击只做过滤和展示，响应是即时的。
页面底部再配一个收入明细列表，每条记录显示名称、分类图标、时间和金额。月度切换时，列表数据来自 Cubit 对应的时间范围，滚动位置我用 PageStorageKey 记住，切换日期后尽量回到之前浏览的位置。
6. 常见问题、性能优化与排障实录
6.1 Flutter SDK 与 Gradle 版本不匹配的编译报错
开发过程中难免会把 Flutter 分支升级，或者换一台机器重新拉依赖，这时候最容易碰到一堆构建报错。浏览器一搜索，常见的就是you are applying flutter's main gradle plugin imperatively...或者the current configured flutter sdk is not known to be fully supported.。
这类问题大概率是 Gradle 插件模板和 Flutter SDK 版本不对齐。解决方案不是去网上抄一段配置硬塞，而是把项目里的settings.gradle、build.gradle、gradle-wrapper.properties这些文件和当前 Flutter SDK 模板对比，把版本号改成 SDK 默认模板对应的值。我一度图省事，直接把报错那段删除，结果越修越乱。后来老老实实按模板对齐，一次通过。
还有一个高频报错could not determine the dependencies of task ':app:compileDebugJavaWithJavac'，一般是 JDK 版本不匹配。Flutter 3.x 系列对 JDK 版本有要求，太高太低都可能解析依赖失败。检查 JAVA_HOME，按官方文档确认对应版本，别同时装一堆 JDK 让 Gradle 猜。
6.2 中文、字体和资源文件问题
OpenHarmony 设备上跑 Flutter，中文字体大概率没问题，但如果你用了自定义字体文件，要注意字体资源在 ohos 工程里打包是否正常。我遇到过FontManifest.json缺少字体记录的情况，页面上的中文全部变成方块，排查了很久才发现是字体资源没被 native 工程打进去。
解决方式有两个方向：一是在 Flutter 侧用rootBundle.load手动加载字体数据，通过FontLoader注册到引擎；二是检查pubspec.yaml的 assets 声明和 ohos 工程的资源配置。如果图省事，我建议优先用系统内置字体，生活助手这种应用没必要为了一点点视觉效果承担字体加载的兼容风险。
图片资源也类似。网络图片没有太大问题，本地 assets 图片就要验证 ohos 目录是否同步，否则开发机上正常、真机上下载资源后一片空白。
6.3 Navigator 切换页面后状态丢失的真相
很多人问 Flutter Navigator 切换页面后到底会不会丢失状态。答案是：要看页面是不是被销毁。默认路由 push 出栈时，原页面会被销毁，里面 setState 维护的状态自然没了。如果只是压栈隐藏，状态大概率保留。
做生活助手时，我要保证从“收入录入页”返回“统计页”后，统计页的月份选择、滚动位置、图表类型还在，不能重新变回初始状态。这里我用了三招：
第一，把跨页面共享的数据状态提升到 Cubit/全局 Store，页面只是状态的“投影”，销毁重建后能立刻恢复。
第二，用 PageStorageKey 保存列表滚动位置，配合PageStorage机制，即使页面重建，滚动偏移也能恢复。
第三，对于底部 Tab 这类切换场景，用IndexedStack或AutomaticKeepAliveClientMixin让页面常驻，而不是反复销毁创建。
6.4 渲染引擎与性能优化经验
OpenHarmony 上 Flutter 的默认渲染路径，我实测下来和桌面端逻辑一致，基本走 Skia。Impeller 在 OpenHarmony 上的适配情况，建议以 SIG 分支的发布说明为准，项目里不要显式开启它，等生态成熟再切不迟。
性能方面，收入统计页最容易卡的是图表绘制。自绘图表时，每次 setState 都重绘全部柱子/折线，如果数据量大或者设备性能一般，掉帧明显。我的优化办法是：把不变化的背景刻度缓存成CustomPaint的静态部分，只让数据部分参与重绘；列表使用懒加载，News 的一个ListView.builder就够了，千万别用Column包所有条目。
数据库聚合查询的耗时控制在 10ms 以内，这条经验很重要。如果发现原生查询耗时太大，检查是不是没建索引。record_time和category_id这两个字段要建联合索引，查询效率会有质的提升。我最初没建索引，流水到 5000 条时，月度统计已经能感觉到明显等待，建索引之后数据量到几万条也很轻松。
6.5 插件适配与平台桥接的几个提醒
做 OpenHarmony 的 Flutter 项目，一定要有“凡是插件都要验证”的心态。社区吹得再响的插件，放到 OpenHarmony 上可能直接用不了。我在项目里遇到的典型情况是：第三方插件构建时依赖了 Android 的 API，编译期直接失败；或者编译通过，运行期 MethodChannel 没有注册，方法调用没有任何响应。
排查这类问题的思路，先用 Flutter 的日志和原生侧日志对照。如果不能确认插件是否往 OpenHarmony 上适配过，最快的解决方案就是：删除插件依赖，自己写一层 MethodChannel。平台通道这种方案，虽然代码多写一点，但可控性极高，项目的可持续维护性反而更好。
最后再分享一点我个人的经验：做跨端项目，别以为“能跑起来”就是结束。收入统计这类功能，涉及数据准确性、日期边界、金额精度、UI 状态，任何一个细节没严格验证，用户用起来都会出问题。建议在核心模块里把关键逻辑写成单元测试，比如金额舍入、日期区间计算、分类汇总逻辑，这些测试跨平台复用，会给你省下大量手工回归的时间。
如果后面还要继续扩展，我的建议是先把“收入分析统计”做成一个独立的功能模块，保持和原生侧的桥接接口稳定。这样不管未来是增加一个“预算管理”模块，还是接入云端同步，甚至把整套生活助手迁移到其他平台上，核心代码都能原样带走，你只需要替换平台桥接层而已。
