这次要聊的项目是用 Flutter 在 OpenHarmony 设备上做一款逆向思维训练 App同时完整实现了学习日历模块。项目本身不算重但横跨了跨端框架适配、业务功能设计和自定义组件开发三块内容踩坑记录一大把值得拿出来复盘。先交代背景。我做 Flutter 开发有几年了对 OpenHarmony 这边的生态一直想跟进实践恰好碰到一个合适的需求——做一个帮助用户训练逆向思维的每日打卡型 App。需求不算复杂核心就两块每天一道逆向思维题以及一个带连续打卡统计的学习日历。我之所以说它“合适”是因为这个项目规模适中既能验证 Flutter 在 OpenHarmony 上的可行性又能把一个自定义组件的完整落地过程走一遍。这篇文章会把整个项目从设计到落地完整梳理一遍包括选型时的纠结、数据模型怎么定、关键代码怎么写以及在真机上调试时踩过的各种坑。如果你也在用 Flutter 做 OpenHarmony 应用或者正打算给自己的 App 加一个日历打卡功能看完应该能少走不少弯路。1. 项目整体设计与思路拆解1.1 为什么选 Flutter 做 OpenHarmony 应用三条路我为什么选这条当时摆在我面前的开发方案其实有三条路。第一条是用 ArkTS 配合 ArkUI 原生开发。这是 OpenHarmony 应用最直接的开发方式生态和工具链都是围绕它设计的理论上兼容性最好。但问题也很现实我的团队此前积累了大量的 Flutter 业务代码和组件库如果全用 ArkTS 重写成本相当于重新做一遍产品而且 ArkUI 的很多组件在复杂交互场景下还不够成熟遇到问题排查起来更费劲。第二条是用其他跨端方案比如混合应用或者 WebView 套壳。这类方案上手快但性能和交互体验都打了折扣尤其是我要做倒计时、连续动画、可定制日历这种偏重交互的功能WebView 的短板会被无限放大。第三条就是用 Flutter 的 OpenHarmony 适配分支来跑。这个方案的逻辑是Flutter 框架本身已经把渲染引擎、组件系统、事件分发打包成了一套独立的东西OpenHarmony 上只需要一个适配层把 Flutter 引擎对接进系统即可。开发时用熟悉的 Dart 语言和组件模型既保住了现有代码资产又拿到了接近原生的性能表现。我最后选了第三条核心原因有三个第一是代码复用率高Android 和 iOS 平台已有的逻辑可以直接迁移第二是 Flutter 自绘引擎的渲染质量在复杂界面上确实比 Web 方案稳第三是 Flutter 生态里现成的日历、图表、动画组件非常多不需要从零去写 ArkUI 版本。当然这里要泼一盆冷水——Flutter 在 OpenHarmony 上跑并不是开箱即用的适配层的成熟度决定了你会在环境配置上先耗掉不少时间这一点后面实战环节细说。1.2 逆向思维训练 App 的产品逻辑从每日一题到习惯养成先把“逆向思维训练”这个概念说清楚。日常思维里我们习惯顺着题目给的条件往下推但逆向思维是反过来先确定目标再反推需要什么条件甚至主动打破题目给的默认假设。举个例子问题是“如何提高一款 App 的日活跃用户数”顺着想可能是推送、签到、会员激励这一套逆向想就会变成“如何让用户不得不打开 App”——比如把关键功能的数据报告做成当日有效、过期作废再比如把某个隐藏功能每天换位置让用户主动去翻。这种“反着拆”的训练核心价值是打破思维惯性让大脑习惯从多个方向上寻找路径。落到产品上这个 App 的功能就非常清晰了。每天一道逆向思维题限时作答用户需要提交尽可能多的不同思路提交后展示参考答案和“思路发散指数”——指数是根据你答案之间的差异度算出来的如果五条答案本质上是同一个思路的换皮指数就低如果五条答案覆盖了不同维度指数就高。这个设计是整个 App 的灵魂它让“训练”从单纯的做题变成了可量化的思维锻炼。除了每日一题另一个核心模块就是学习日历。日历承担的是习惯养成职能——用户完成当天的训练后日历上对应日期被打上标记连续打卡天数同步更新。这个机制的心理学逻辑很简单人对自己已经投入过精力的连续记录会有很强的维护意愿连续天数本身就是一种沉没成本。产品形态上日历不光是一个打卡展示页还要承担“查看历史训练记录”的功能点击任意日期可以回看当天提交了哪些答案、思路发散指数是多少。1.3 学习日历的定位与选型第三方组件还是自研学习日历在一开始我考虑过直接用现成的第三方日历组件——就是 table_calendar 这类 Flutter 包功能确实丰富样式可定制性也强。但我在试用阶段发现了几个问题。第一它的划动手势和点击事件在 OpenHarmony 的适配层上偶发失灵滑动切换月份有时要划好几次才有反应这对用户来说是非常明显的体验缺陷。第二它的数据标记接口设计偏复杂要给某一天打上一个自定义角标需要层层配置用起来很不顺手。第三也是最重要的——我的需求其实很简单只需要月视图展示、点击切换日期、标记完成状态、统计连续天数这些功能自己写一个轻量组件足够何必为了 10% 的需求去迁就一个为 100% 场景设计的复杂库。所以最后决定自己写。自研日历组件的成本和收益我心里有一笔账开发成本大概是两到三个工作日换来的是完全可控的交互逻辑、和 App 视觉风格完全统一的样式以及未来扩展周视图、月度报告时的自由度。这个决策事后证明是对的——虽然过程中踩了几个坑但组件整体稳定性和可维护性都比用第三方库好得多。2. 核心功能拆解与数据设计2.1 逆向思维题的流转逻辑一个状态机搞定把逆向思维题的业务流程拆开看其实就是一个状态机。一个题目从用户打开 App 开始会经历这么几个状态初始状态是“今天还没作答”用户进入今日题目页面后变成“进行中”限时作答结束提交后变成“已完成”用户查看参考思路后变成“已查看”。这四种状态之间还有两个边界情况需要处理——超时未提交状态直接回退到“可补交”断网提交失败状态保持在“进行中”允许用户重试。数据模型上每个题目我定义了一个 QuestionModel包含这几个关键字段class QuestionModel { final String id; // 题目唯一标识 final String content; // 题目文本支持富文本和图片 final ListString hintDirections; // 提示方向默认给2-3个启发点 final int timeLimitSeconds; // 作答时限默认300秒 final ListString referenceAnswers; // 参考答案展示用 final int difficultyLevel; // 难度等级1到5 }题目的选取策略是“每日全局统一”——每个用户在同一天看到的是同一道题。实现方式是用日期字符串做哈希取模从题目库中确定当天索引而不是随机选择。这样做的产品原因是所有用户在同一天讨论同一道题可以形成社区话题技术原因是题目索引可重入用户在多个设备上登录时看到的题目是一致的不会因为随机数不同导致体验断裂。2.2 学习日历数据模型一张表解决全部统计需求学习日历的核心需求归纳起来就三句话某一天有没有学习记录、连续打卡了多少天、某一天具体做了哪些题。我用的本地数据库是 sqflite建了一张学习记录表字段设计是这样的字段名类型说明dateTEXT记录日期格式 yyyy-MM-dd作为主键is_completedINTEGER当天是否完成训练0或1question_countINTEGER当天完成的题目数量answers_jsonTEXT当天提交的答案列表JSON序列化存储diversity_scoreREAL当天的思路发散指数0到100streak_daysINTEGER截止当天的连续打卡天数有几个设计细节当时纠结过。第一date 字段一定要用 yyyy-MM-dd 这样的字符串做主键而不是时间戳或 DateTime 对象——字符串格式不涉及时区换算读写都稳定查询按月/按年范围时用 LIKE 或 BETWEEN 都方便。第二连续性不是预先算好存进去的而是在每次打卡时实时计算。第三答案的 JSON 存储用 TEXT 字段而不是单独建一张关联表原因是查询频率低、数据量小、单条答案不会超过几千个字符TEXT 字段完全够用还能省掉一次多表 JOIN 的开销。2.3 状态管理与组件树拆分数据源统一是铁律整套 App 的状态管理用了 Provider没有上更重的方案因为项目规模并不需要。状态树拆成了三层第一层是全局的登录状态和设置项第二层是今日训练状态第三层是日历状态。三个层级的 Provider 嵌套关系如下MultiProvider( providers: [ ChangeNotifierProvider(create: (_) SettingsProvider()), ChangeNotifierProvider(create: (_) TrainingProvider()), ChangeNotifierProvider(create: (_) CalendarProvider()), ], child: const AppRoot(), )这里有一个非常重要的设计原则TrainingProvider 和 CalendarProvider 虽然各自维护自己的界面状态但它们底层读取的是同一个 RecordRepository 数据源。用户完成一次训练后TrainingProvider 更新今日状态同时调用 CalendarProvider 的刷新方法重新读取当天的记录。一开始我没有统一数据源两个 Provider 各自从数据库读了一次数据结果出现了“训练页显示已完成、日历页还显示未打卡”的尴尬局面。这个教训后面在问题排查部分还会展开细说。3. 实操过程与关键环节实现3.1 环境准备与工程配置三步打通 Flutter 到 OpenHarmony这里我把环境搭建的过程完整写出来照着操作基本能复现。第一步是准备工具链。需要安装 OpenHarmony SDK、Flutter 的 OpenHarmony 适配分支、以及用于构建 HAP 包的 IDE 工具。SDK 版本建议用 4.0 以上的版本适配分支的 Flutter 版本建议锁定某个稳定版本不要追新新版本常有未修复的问题。第二步是创建一个标准 Flutter 项目把业务代码全部写在这个项目里。这个阶段完全不需要考虑 OpenHarmony 的差异正常写 Flutter 代码就好。第三步是关键生成 OpenHarmony 工程壳。流程是先在 Flutter 项目里用适配分支的命令行工具执行构建生成 OpenHarmony 专用的产物目录然后打开 IDE新建一个空的 OpenHarmony 应用工程把刚才生成的产物作为依赖模块导入随后在工程的模块配置里声明对 Flutter 引擎库的依赖并配置好入口 Ability。我这里贴一下我当时整理的构建配置简版# 1. 拉取适配分支依赖并构建 flutter pub get # 2. 构建 OpenHarmony 产物 flutter build hap --release # 3. 将构建产物目录导入 IDE 工程 # 在 oh-package.json5 中声明依赖构建完成后剩下的工作就是把 HAP 包安装到 OpenHarmony 设备上。这一步用 IDE 的安装工具直接部署到模拟器或真机即可。整个环境搭建大概花了我一天半时间最大的消耗在版本匹配上——Flutter 适配分支的版本和 OpenHarmony SDK 版本必须兼容这个对应关系在官方文档里写得不明显导致我第一次构建出来装到设备上后应用直接闪退。3.2 今日题目页面倒计时 限时提交的核心实现今日题目页面是整个 App 交互最重的页面包含题目展示、倒计时、答案输入、提交反馈四个区域。倒计时逻辑用 Timer.periodic 实现每一秒触发一次 setState 刷新剩余时间。这里有一个经验点Timer 必须在页面销毁时取消否则在页面退出后回调仍然执行轻则报错重则内存泄漏。我在 dispose 方法里做了严格的清理override void dispose() { _timer?.cancel(); super.dispose(); }题目切换逻辑前面提过按日期字符做哈希模取题号。答案提交前要做几道校验最少提交一条、最多五条、每条字数在 10 到 200 字之间。提交动作本身是异步的需要处理网络超时和失败重试失败时不更新本地状态保持“进行中”让用户可重试。这里还有个细节限时结束后如果还没提交我不会直接丢弃用户输入而是弹出提示让用户选择“补交”或“放弃”。补交的答案会正常入库但会标记为“超时提交”。产品逻辑是——逆向思维训练的核心是完成了思考过程而不是掐表提交的仪式感超时提交的答案同样有价值。3.3 自研日历组件GridView 布局下的核心实现自己写日历组件核心难点在于月视图的“格子”布局。我用 GridView 来实现月视图。每个格子对应一个日期日期数字显示在格子中央根据学习记录状态的不同背景色和角标会变化——已打卡的日期显示主题色背景加对勾角标未打卡的显示浅灰背景当天日期用描边强调连续打卡超过 7 天的日期右上角还会出现一个小火焰图标。布局上有两个关键计算。一是当月第一天是星期几这一天的前面需要留出对应数量的空位否则日期会从错误的列开始排。二是每个月的天数不同2 月在闰年和平年分别是 29 和 28 天格子总数要动态计算。我加了一个辅助函数ListDateTime generateMonthDays(DateTime month) { final firstDay DateTime(month.year, month.month, 1); final weekdayOfFirst firstDay.weekday; // 1周一, 7周日 final daysInMonth DateTime(month.year, month.month 1, 0).day; final leadingBlanks List.filled(weekdayOfFirst - 1, null); final days List.generate(daysInMonth, (i) DateTime(month.year, month.month, i 1)); return [...leadingBlanks, ...days]; }点击日期格时切换选中状态页面底部会弹出一个底部抽屉展示当天的训练详情——是否完成、提交了哪些答案、思路发散指数是多少。这个交互让日历不仅是一个打卡展示还承担了历史记录回看的功能这也是我做这个组件时特别想实现的效果——学习日历不是冷冰冰的标记墙而应该成为用户回顾自己思考轨迹的入口。性能方面月视图切换时只渲染当前月的格子不预加载前后月的数据当月数据在进入页面时一次性从数据库批量读出而不是每个格子单独查询避免 N1 查询问题。实测下来哪怕数据量到了两三年的量级切换月份也非常流畅。3.4 数据持久化与连续打卡统计换个方向数就对了数据持久化用的 sqflite建表和增删改查都是常规操作不需要多讲。这里重点说说连续打卡的计算逻辑因为这里藏着一个很典型的思维误区。先说我开始犯的错误。我想当然地写了这样一段逻辑取今天的日期往前逐天检查如果某一天有打卡记录连续天数就加一遇到没有记录的日期就停止。这个逻辑听起来没问题但它隐含了一个错误假设——今天一定有打卡记录。如果用户昨天打了卡、今天还没打卡按这个逻辑算出来的连续天数是 1但实际上用户保持了连续 2 天的记录只是今天还没完成而已。正确的做法是从最近一个打卡日开始往回数而不是从今天开始数。先查最近一次有记录的日期然后从这个日期往前逐天检查连续性。这样无论用户今天是否已经打卡只要存在一条连续的历史记录就能算出正确的连续天数。int calculateStreak(ListStudyRecord records, DateTime today) { final dateSet records.map((r) DateUtils.dateOnly(DateTime.parse(r.date))).toSet(); var cursor DateUtils.dateOnly(today); // 如果今天没有打卡从昨天开始回溯 if (!dateSet.contains(cursor)) { cursor cursor.subtract(const Duration(days: 1)); } var streak 0; while (dateSet.contains(cursor)) { streak; cursor cursor.subtract(const Duration(days: 1)); } return streak; }这个“换个方向数”的思路后来也应用到补签逻辑里。如果用户允许补签补签日不会往前填充连续天数的空洞而是往后延续“最近一次打卡日”相当于把连续记录整体平移。产品上这避免了用户刻意断签再补签刷数据的情况技术上也让计算逻辑保持简洁。4. 常见问题与排查技巧实录4.1 白屏、点击失灵、路由卡顿Flutter 在 OpenHarmony 上的三个大坑这一节全部是真机调试时踩出来的问题每一个都花了不少时间定位。第一个坑是应用启动后白屏要等好几秒才显示出第一个页面。一开始我以为是引擎初始化慢后来排查发现是 Flutter 在 OpenHarmony 上加载字体资源的路径和 Android 不同适配层默认去系统字体目录加载但这个目录在 OpenHarmony 上不存在或者权限受限导致渲染线程在等待字体加载时阻塞。解决办法是把默认字体加载关掉或者在工程配置里手动指定字体路径。这个问题在适配分支较新版本里已经修复但如果你用的版本比较旧还是会遇到。第二个坑是点击事件不响应。典型场景是日历格子点击没有反馈按钮点击偶尔失灵。排查了很久发现是适配层的触摸事件坐标没有做正确转换手势识别区域和视觉区域对不上所以在组件边缘位置点击时事件被分配给了相邻组件。这个问题在新版适配分支中已经解决但如果你的版本旧一个临时的规避方案是给按钮和可点击组件外加一层 padding扩大事件命中区域。第三个坑是页面跳转卡顿。Flutter 侧的页面路由和 OpenHarmony 的 Ability 切换是两个独立流程如果直接在 Flutter 里调用原生的 Ability 跳转会发生明显的卡顿甚至白屏闪烁。我的解决方案是放弃多 Ability 的架构改成单 Ability 加 Flutter 内部路由所有页面跳转都在 Flutter 侧完成只在需要调用系统能力时才走平台通道。这个方案显著提升了页面切换的流畅度。4.2 日历边界问题2 月、跨年、时区一个都别放过日历组件最容易翻车的地方全在边界情况上。第一个是 2 月的天数。我一开始用 DateTime(month.year, month.month 1, 0).day 这个表达式来获取当月天数它利用 DateTime 的溢出机制——month 1 会进位到下个月day 传 0 表示上个月的最后一天。这个写法本身没错但在处理 12 月跨年时要小心month 1 变成 13 之后DateTime 会自动进位到下一年的 1 月这是 Dart 的标准行为没问题。真正的坑在于如果你用这个表达式去算 2 月的天数平年和闰年要分别处理DateTime 本身已经处理了闰年规则你只要别自己去写一个天数表就行了。第二个是跨年显示。当用户从 12 月切换到 1 月时网格布局里可能会出现 12 月 29 日、30 日、31 日在同一个星期里然后直接跳到 1 月 1 日的情况。如果你没有把相邻月份的日子裁掉日历会显示空位或者错乱。我的做法是生成当月格子时只包含当月日期其余的格子全部留空而不是用前后月的日期顶上来。第三个是时区问题。如果设备时区不是东八区DateTime.now() 返回的日期可能是前一天或后一天。日历数据和日期字符串的生成全部统一通过一个 dateOnly 工具函数处理这个函数先把 DateTime 归一化到当天零点再转成字符串从源头上避免了时区偏移。4.3 数据同步与 Bug 实录连续天数是怎么算错的一次复盘最后记录一个真实的 Bug 和排查过程很有代表性。现象用户在训练页完成打卡后切到日历页发现今天的日期没有打上标记但连续打卡天数已经变了。再切回训练页状态又变成正常的。这两个页面的状态完全不一致。排查定位两个页面各自持有自己的 Provider 状态副本训练页在打卡完成后只更新了 TrainingProvider没有通知 CalendarProvider 刷新。而连续天数之所以变了是因为训练页更新时调用了计算连续天数的逻辑但日历页读取的还是旧的本地状态。解决方案在训练完成的事件回调里同时调用 CalendarProvider 的刷新方法重新读取数据库中的记录。为了让这个逻辑更健壮我还引入了一个全局的 ChangeNotifier——RecordChangeNotifier由它统一通知所有订阅者数据变更无论是训练页还是日历页只要收到通知就重新拉取数据。这样从架构上保证了数据一致性以后就算增加新的页面也不需要再逐对处理同步关系了。这类问题在小型 App 里容易被忽视因为页面少出问题的概率低。但一旦想增加功能、扩充页面状态不同步的隐患就会逐渐放大。所以我的一个经验是涉及同一条数据记录的多个页面宁可稍微多一点代码量也要统一走同一个数据变更通知通道这比事后排错要划算得多。写到这里这个项目的核心内容基本都讲清楚了。做这个项目我最深的体会是OpenHarmony 生态还在快速生长中很多问题没有现成答案但只要把问题拆细、一个个验证大多数坑都是可以绕过去的。学习日历这次做成了月视图后续可以继续扩展周视图、月度统计报告、打卡分享卡片这些功能我已经列了几个待办等有空把周视图和报告页做完再回来补充一篇。希望这篇实战记录能帮你少踩几个坑尤其是日历边界和数据同步这两块建议提前设计好别等测试来帮你发现。 
长河君 · 2026/10/14 3:42:51 · 阅读 1.2k Flutter跨端开发实战：OpenHarmony逆向思维App的学习日历实现
这次要聊的项目是用 Flutter 在 OpenHarmony 设备上做一款逆向思维训练 App同时完整实现了学习日历模块。项目本身不算重但横跨了跨端框架适配、业务功能设计和自定义组件开发三块内容踩坑记录一大把值得拿出来复盘。先交代背景。我做 Flutter 开发有几年了对 OpenHarmony 这边的生态一直想跟进实践恰好碰到一个合适的需求——做一个帮助用户训练逆向思维的每日打卡型 App。需求不算复杂核心就两块每天一道逆向思维题以及一个带连续打卡统计的学习日历。我之所以说它“合适”是因为这个项目规模适中既能验证 Flutter 在 OpenHarmony 上的可行性又能把一个自定义组件的完整落地过程走一遍。这篇文章会把整个项目从设计到落地完整梳理一遍包括选型时的纠结、数据模型怎么定、关键代码怎么写以及在真机上调试时踩过的各种坑。如果你也在用 Flutter 做 OpenHarmony 应用或者正打算给自己的 App 加一个日历打卡功能看完应该能少走不少弯路。1. 项目整体设计与思路拆解1.1 为什么选 Flutter 做 OpenHarmony 应用三条路我为什么选这条当时摆在我面前的开发方案其实有三条路。第一条是用 ArkTS 配合 ArkUI 原生开发。这是 OpenHarmony 应用最直接的开发方式生态和工具链都是围绕它设计的理论上兼容性最好。但问题也很现实我的团队此前积累了大量的 Flutter 业务代码和组件库如果全用 ArkTS 重写成本相当于重新做一遍产品而且 ArkUI 的很多组件在复杂交互场景下还不够成熟遇到问题排查起来更费劲。第二条是用其他跨端方案比如混合应用或者 WebView 套壳。这类方案上手快但性能和交互体验都打了折扣尤其是我要做倒计时、连续动画、可定制日历这种偏重交互的功能WebView 的短板会被无限放大。第三条就是用 Flutter 的 OpenHarmony 适配分支来跑。这个方案的逻辑是Flutter 框架本身已经把渲染引擎、组件系统、事件分发打包成了一套独立的东西OpenHarmony 上只需要一个适配层把 Flutter 引擎对接进系统即可。开发时用熟悉的 Dart 语言和组件模型既保住了现有代码资产又拿到了接近原生的性能表现。我最后选了第三条核心原因有三个第一是代码复用率高Android 和 iOS 平台已有的逻辑可以直接迁移第二是 Flutter 自绘引擎的渲染质量在复杂界面上确实比 Web 方案稳第三是 Flutter 生态里现成的日历、图表、动画组件非常多不需要从零去写 ArkUI 版本。当然这里要泼一盆冷水——Flutter 在 OpenHarmony 上跑并不是开箱即用的适配层的成熟度决定了你会在环境配置上先耗掉不少时间这一点后面实战环节细说。1.2 逆向思维训练 App 的产品逻辑从每日一题到习惯养成先把“逆向思维训练”这个概念说清楚。日常思维里我们习惯顺着题目给的条件往下推但逆向思维是反过来先确定目标再反推需要什么条件甚至主动打破题目给的默认假设。举个例子问题是“如何提高一款 App 的日活跃用户数”顺着想可能是推送、签到、会员激励这一套逆向想就会变成“如何让用户不得不打开 App”——比如把关键功能的数据报告做成当日有效、过期作废再比如把某个隐藏功能每天换位置让用户主动去翻。这种“反着拆”的训练核心价值是打破思维惯性让大脑习惯从多个方向上寻找路径。落到产品上这个 App 的功能就非常清晰了。每天一道逆向思维题限时作答用户需要提交尽可能多的不同思路提交后展示参考答案和“思路发散指数”——指数是根据你答案之间的差异度算出来的如果五条答案本质上是同一个思路的换皮指数就低如果五条答案覆盖了不同维度指数就高。这个设计是整个 App 的灵魂它让“训练”从单纯的做题变成了可量化的思维锻炼。除了每日一题另一个核心模块就是学习日历。日历承担的是习惯养成职能——用户完成当天的训练后日历上对应日期被打上标记连续打卡天数同步更新。这个机制的心理学逻辑很简单人对自己已经投入过精力的连续记录会有很强的维护意愿连续天数本身就是一种沉没成本。产品形态上日历不光是一个打卡展示页还要承担“查看历史训练记录”的功能点击任意日期可以回看当天提交了哪些答案、思路发散指数是多少。1.3 学习日历的定位与选型第三方组件还是自研学习日历在一开始我考虑过直接用现成的第三方日历组件——就是 table_calendar 这类 Flutter 包功能确实丰富样式可定制性也强。但我在试用阶段发现了几个问题。第一它的划动手势和点击事件在 OpenHarmony 的适配层上偶发失灵滑动切换月份有时要划好几次才有反应这对用户来说是非常明显的体验缺陷。第二它的数据标记接口设计偏复杂要给某一天打上一个自定义角标需要层层配置用起来很不顺手。第三也是最重要的——我的需求其实很简单只需要月视图展示、点击切换日期、标记完成状态、统计连续天数这些功能自己写一个轻量组件足够何必为了 10% 的需求去迁就一个为 100% 场景设计的复杂库。所以最后决定自己写。自研日历组件的成本和收益我心里有一笔账开发成本大概是两到三个工作日换来的是完全可控的交互逻辑、和 App 视觉风格完全统一的样式以及未来扩展周视图、月度报告时的自由度。这个决策事后证明是对的——虽然过程中踩了几个坑但组件整体稳定性和可维护性都比用第三方库好得多。2. 核心功能拆解与数据设计2.1 逆向思维题的流转逻辑一个状态机搞定把逆向思维题的业务流程拆开看其实就是一个状态机。一个题目从用户打开 App 开始会经历这么几个状态初始状态是“今天还没作答”用户进入今日题目页面后变成“进行中”限时作答结束提交后变成“已完成”用户查看参考思路后变成“已查看”。这四种状态之间还有两个边界情况需要处理——超时未提交状态直接回退到“可补交”断网提交失败状态保持在“进行中”允许用户重试。数据模型上每个题目我定义了一个 QuestionModel包含这几个关键字段class QuestionModel { final String id; // 题目唯一标识 final String content; // 题目文本支持富文本和图片 final ListString hintDirections; // 提示方向默认给2-3个启发点 final int timeLimitSeconds; // 作答时限默认300秒 final ListString referenceAnswers; // 参考答案展示用 final int difficultyLevel; // 难度等级1到5 }题目的选取策略是“每日全局统一”——每个用户在同一天看到的是同一道题。实现方式是用日期字符串做哈希取模从题目库中确定当天索引而不是随机选择。这样做的产品原因是所有用户在同一天讨论同一道题可以形成社区话题技术原因是题目索引可重入用户在多个设备上登录时看到的题目是一致的不会因为随机数不同导致体验断裂。2.2 学习日历数据模型一张表解决全部统计需求学习日历的核心需求归纳起来就三句话某一天有没有学习记录、连续打卡了多少天、某一天具体做了哪些题。我用的本地数据库是 sqflite建了一张学习记录表字段设计是这样的字段名类型说明dateTEXT记录日期格式 yyyy-MM-dd作为主键is_completedINTEGER当天是否完成训练0或1question_countINTEGER当天完成的题目数量answers_jsonTEXT当天提交的答案列表JSON序列化存储diversity_scoreREAL当天的思路发散指数0到100streak_daysINTEGER截止当天的连续打卡天数有几个设计细节当时纠结过。第一date 字段一定要用 yyyy-MM-dd 这样的字符串做主键而不是时间戳或 DateTime 对象——字符串格式不涉及时区换算读写都稳定查询按月/按年范围时用 LIKE 或 BETWEEN 都方便。第二连续性不是预先算好存进去的而是在每次打卡时实时计算。第三答案的 JSON 存储用 TEXT 字段而不是单独建一张关联表原因是查询频率低、数据量小、单条答案不会超过几千个字符TEXT 字段完全够用还能省掉一次多表 JOIN 的开销。2.3 状态管理与组件树拆分数据源统一是铁律整套 App 的状态管理用了 Provider没有上更重的方案因为项目规模并不需要。状态树拆成了三层第一层是全局的登录状态和设置项第二层是今日训练状态第三层是日历状态。三个层级的 Provider 嵌套关系如下MultiProvider( providers: [ ChangeNotifierProvider(create: (_) SettingsProvider()), ChangeNotifierProvider(create: (_) TrainingProvider()), ChangeNotifierProvider(create: (_) CalendarProvider()), ], child: const AppRoot(), )这里有一个非常重要的设计原则TrainingProvider 和 CalendarProvider 虽然各自维护自己的界面状态但它们底层读取的是同一个 RecordRepository 数据源。用户完成一次训练后TrainingProvider 更新今日状态同时调用 CalendarProvider 的刷新方法重新读取当天的记录。一开始我没有统一数据源两个 Provider 各自从数据库读了一次数据结果出现了“训练页显示已完成、日历页还显示未打卡”的尴尬局面。这个教训后面在问题排查部分还会展开细说。3. 实操过程与关键环节实现3.1 环境准备与工程配置三步打通 Flutter 到 OpenHarmony这里我把环境搭建的过程完整写出来照着操作基本能复现。第一步是准备工具链。需要安装 OpenHarmony SDK、Flutter 的 OpenHarmony 适配分支、以及用于构建 HAP 包的 IDE 工具。SDK 版本建议用 4.0 以上的版本适配分支的 Flutter 版本建议锁定某个稳定版本不要追新新版本常有未修复的问题。第二步是创建一个标准 Flutter 项目把业务代码全部写在这个项目里。这个阶段完全不需要考虑 OpenHarmony 的差异正常写 Flutter 代码就好。第三步是关键生成 OpenHarmony 工程壳。流程是先在 Flutter 项目里用适配分支的命令行工具执行构建生成 OpenHarmony 专用的产物目录然后打开 IDE新建一个空的 OpenHarmony 应用工程把刚才生成的产物作为依赖模块导入随后在工程的模块配置里声明对 Flutter 引擎库的依赖并配置好入口 Ability。我这里贴一下我当时整理的构建配置简版# 1. 拉取适配分支依赖并构建 flutter pub get # 2. 构建 OpenHarmony 产物 flutter build hap --release # 3. 将构建产物目录导入 IDE 工程 # 在 oh-package.json5 中声明依赖构建完成后剩下的工作就是把 HAP 包安装到 OpenHarmony 设备上。这一步用 IDE 的安装工具直接部署到模拟器或真机即可。整个环境搭建大概花了我一天半时间最大的消耗在版本匹配上——Flutter 适配分支的版本和 OpenHarmony SDK 版本必须兼容这个对应关系在官方文档里写得不明显导致我第一次构建出来装到设备上后应用直接闪退。3.2 今日题目页面倒计时 限时提交的核心实现今日题目页面是整个 App 交互最重的页面包含题目展示、倒计时、答案输入、提交反馈四个区域。倒计时逻辑用 Timer.periodic 实现每一秒触发一次 setState 刷新剩余时间。这里有一个经验点Timer 必须在页面销毁时取消否则在页面退出后回调仍然执行轻则报错重则内存泄漏。我在 dispose 方法里做了严格的清理override void dispose() { _timer?.cancel(); super.dispose(); }题目切换逻辑前面提过按日期字符做哈希模取题号。答案提交前要做几道校验最少提交一条、最多五条、每条字数在 10 到 200 字之间。提交动作本身是异步的需要处理网络超时和失败重试失败时不更新本地状态保持“进行中”让用户可重试。这里还有个细节限时结束后如果还没提交我不会直接丢弃用户输入而是弹出提示让用户选择“补交”或“放弃”。补交的答案会正常入库但会标记为“超时提交”。产品逻辑是——逆向思维训练的核心是完成了思考过程而不是掐表提交的仪式感超时提交的答案同样有价值。3.3 自研日历组件GridView 布局下的核心实现自己写日历组件核心难点在于月视图的“格子”布局。我用 GridView 来实现月视图。每个格子对应一个日期日期数字显示在格子中央根据学习记录状态的不同背景色和角标会变化——已打卡的日期显示主题色背景加对勾角标未打卡的显示浅灰背景当天日期用描边强调连续打卡超过 7 天的日期右上角还会出现一个小火焰图标。布局上有两个关键计算。一是当月第一天是星期几这一天的前面需要留出对应数量的空位否则日期会从错误的列开始排。二是每个月的天数不同2 月在闰年和平年分别是 29 和 28 天格子总数要动态计算。我加了一个辅助函数ListDateTime generateMonthDays(DateTime month) { final firstDay DateTime(month.year, month.month, 1); final weekdayOfFirst firstDay.weekday; // 1周一, 7周日 final daysInMonth DateTime(month.year, month.month 1, 0).day; final leadingBlanks List.filled(weekdayOfFirst - 1, null); final days List.generate(daysInMonth, (i) DateTime(month.year, month.month, i 1)); return [...leadingBlanks, ...days]; }点击日期格时切换选中状态页面底部会弹出一个底部抽屉展示当天的训练详情——是否完成、提交了哪些答案、思路发散指数是多少。这个交互让日历不仅是一个打卡展示还承担了历史记录回看的功能这也是我做这个组件时特别想实现的效果——学习日历不是冷冰冰的标记墙而应该成为用户回顾自己思考轨迹的入口。性能方面月视图切换时只渲染当前月的格子不预加载前后月的数据当月数据在进入页面时一次性从数据库批量读出而不是每个格子单独查询避免 N1 查询问题。实测下来哪怕数据量到了两三年的量级切换月份也非常流畅。3.4 数据持久化与连续打卡统计换个方向数就对了数据持久化用的 sqflite建表和增删改查都是常规操作不需要多讲。这里重点说说连续打卡的计算逻辑因为这里藏着一个很典型的思维误区。先说我开始犯的错误。我想当然地写了这样一段逻辑取今天的日期往前逐天检查如果某一天有打卡记录连续天数就加一遇到没有记录的日期就停止。这个逻辑听起来没问题但它隐含了一个错误假设——今天一定有打卡记录。如果用户昨天打了卡、今天还没打卡按这个逻辑算出来的连续天数是 1但实际上用户保持了连续 2 天的记录只是今天还没完成而已。正确的做法是从最近一个打卡日开始往回数而不是从今天开始数。先查最近一次有记录的日期然后从这个日期往前逐天检查连续性。这样无论用户今天是否已经打卡只要存在一条连续的历史记录就能算出正确的连续天数。int calculateStreak(ListStudyRecord records, DateTime today) { final dateSet records.map((r) DateUtils.dateOnly(DateTime.parse(r.date))).toSet(); var cursor DateUtils.dateOnly(today); // 如果今天没有打卡从昨天开始回溯 if (!dateSet.contains(cursor)) { cursor cursor.subtract(const Duration(days: 1)); } var streak 0; while (dateSet.contains(cursor)) { streak; cursor cursor.subtract(const Duration(days: 1)); } return streak; }这个“换个方向数”的思路后来也应用到补签逻辑里。如果用户允许补签补签日不会往前填充连续天数的空洞而是往后延续“最近一次打卡日”相当于把连续记录整体平移。产品上这避免了用户刻意断签再补签刷数据的情况技术上也让计算逻辑保持简洁。4. 常见问题与排查技巧实录4.1 白屏、点击失灵、路由卡顿Flutter 在 OpenHarmony 上的三个大坑这一节全部是真机调试时踩出来的问题每一个都花了不少时间定位。第一个坑是应用启动后白屏要等好几秒才显示出第一个页面。一开始我以为是引擎初始化慢后来排查发现是 Flutter 在 OpenHarmony 上加载字体资源的路径和 Android 不同适配层默认去系统字体目录加载但这个目录在 OpenHarmony 上不存在或者权限受限导致渲染线程在等待字体加载时阻塞。解决办法是把默认字体加载关掉或者在工程配置里手动指定字体路径。这个问题在适配分支较新版本里已经修复但如果你用的版本比较旧还是会遇到。第二个坑是点击事件不响应。典型场景是日历格子点击没有反馈按钮点击偶尔失灵。排查了很久发现是适配层的触摸事件坐标没有做正确转换手势识别区域和视觉区域对不上所以在组件边缘位置点击时事件被分配给了相邻组件。这个问题在新版适配分支中已经解决但如果你的版本旧一个临时的规避方案是给按钮和可点击组件外加一层 padding扩大事件命中区域。第三个坑是页面跳转卡顿。Flutter 侧的页面路由和 OpenHarmony 的 Ability 切换是两个独立流程如果直接在 Flutter 里调用原生的 Ability 跳转会发生明显的卡顿甚至白屏闪烁。我的解决方案是放弃多 Ability 的架构改成单 Ability 加 Flutter 内部路由所有页面跳转都在 Flutter 侧完成只在需要调用系统能力时才走平台通道。这个方案显著提升了页面切换的流畅度。4.2 日历边界问题2 月、跨年、时区一个都别放过日历组件最容易翻车的地方全在边界情况上。第一个是 2 月的天数。我一开始用 DateTime(month.year, month.month 1, 0).day 这个表达式来获取当月天数它利用 DateTime 的溢出机制——month 1 会进位到下个月day 传 0 表示上个月的最后一天。这个写法本身没错但在处理 12 月跨年时要小心month 1 变成 13 之后DateTime 会自动进位到下一年的 1 月这是 Dart 的标准行为没问题。真正的坑在于如果你用这个表达式去算 2 月的天数平年和闰年要分别处理DateTime 本身已经处理了闰年规则你只要别自己去写一个天数表就行了。第二个是跨年显示。当用户从 12 月切换到 1 月时网格布局里可能会出现 12 月 29 日、30 日、31 日在同一个星期里然后直接跳到 1 月 1 日的情况。如果你没有把相邻月份的日子裁掉日历会显示空位或者错乱。我的做法是生成当月格子时只包含当月日期其余的格子全部留空而不是用前后月的日期顶上来。第三个是时区问题。如果设备时区不是东八区DateTime.now() 返回的日期可能是前一天或后一天。日历数据和日期字符串的生成全部统一通过一个 dateOnly 工具函数处理这个函数先把 DateTime 归一化到当天零点再转成字符串从源头上避免了时区偏移。4.3 数据同步与 Bug 实录连续天数是怎么算错的一次复盘最后记录一个真实的 Bug 和排查过程很有代表性。现象用户在训练页完成打卡后切到日历页发现今天的日期没有打上标记但连续打卡天数已经变了。再切回训练页状态又变成正常的。这两个页面的状态完全不一致。排查定位两个页面各自持有自己的 Provider 状态副本训练页在打卡完成后只更新了 TrainingProvider没有通知 CalendarProvider 刷新。而连续天数之所以变了是因为训练页更新时调用了计算连续天数的逻辑但日历页读取的还是旧的本地状态。解决方案在训练完成的事件回调里同时调用 CalendarProvider 的刷新方法重新读取数据库中的记录。为了让这个逻辑更健壮我还引入了一个全局的 ChangeNotifier——RecordChangeNotifier由它统一通知所有订阅者数据变更无论是训练页还是日历页只要收到通知就重新拉取数据。这样从架构上保证了数据一致性以后就算增加新的页面也不需要再逐对处理同步关系了。这类问题在小型 App 里容易被忽视因为页面少出问题的概率低。但一旦想增加功能、扩充页面状态不同步的隐患就会逐渐放大。所以我的一个经验是涉及同一条数据记录的多个页面宁可稍微多一点代码量也要统一走同一个数据变更通知通道这比事后排错要划算得多。写到这里这个项目的核心内容基本都讲清楚了。做这个项目我最深的体会是OpenHarmony 生态还在快速生长中很多问题没有现成答案但只要把问题拆细、一个个验证大多数坑都是可以绕过去的。学习日历这次做成了月视图后续可以继续扩展周视图、月度统计报告、打卡分享卡片这些功能我已经列了几个待办等有空把周视图和报告页做完再回来补充一篇。希望这篇实战记录能帮你少踩几个坑尤其是日历边界和数据同步这两块建议提前设计好别等测试来帮你发现。