艺考季一到最忙的不止是考生还有各种培训机构。去年我接了一个面向艺术生文化课冲刺的真题题库需求学生要能在手机上刷题、看错题、查正确率机构老师则要看整体的学习统计。因为目标设备里有不少是OpenHarmony系统的新款平板我干脆把整套方案押在了Flutter for OpenHarmony上——一套Flutter代码同时覆盖Android和OpenHarmony两个平台把题库功能和统计概览都做成原生体验。这篇文章就把完整实战过程拆给你看尤其是统计概览模块的设计和实现适合那些想在OpenHarmony上用Flutter做生产级app、又不想走“开个WebView套壳”路线的开发者参考。1. 为什么把艺考题库押在 Flutter OpenHarmony 上1.1 这个组合不是“Android套壳”而是真原生渲染很多人第一次听到“Flutter for OpenHarmony”时第一反应是是不是把Android版Flutter跑到OpenHarmony的兼容层上不是。OpenHarmony有自己的ArkUI框架和方舟运行时Flutter的适配方案是把Flutter引擎作为独立渲染模块接入OpenHarmony窗口管理、触摸事件、生命周期这些底层机制都和OpenHarmony原生打通的。换句话说Flutter页面在OpenHarmony上不是WebView渲染也不是套一层兼容壳而是Flutter的Skia/Impeller引擎直接在OpenHarmony的Surface上绘制。那这和Android Flutter有什么区别区别主要在集成层Flutter Engine需要用OpenHarmony的NDK重新编译Platform Channel要对接的是OpenHarmony的Ability和API而不是Android的Activity和SDK。这也是为什么你不能把一个Flutter项目的Android目录直接搬到OpenHarmony上就跑必须走OpenHarmony的工程结构和打包流程。1.2 艺考题库业务对技术栈的真实要求艺考文化课题库这个场景表面看是“列表加详情加答题页”实际要求并不低题目列表滚动流畅题库动辄几千道题学生经常连续刷几十道题ListView滑动掉帧会立刻被感知到。答题状态需要持久恢复中途退出、断网、切后台再回来做题进度不能丢。统计概览要实时算每答完一道题正确率、各科分布、近七日做题趋势这些数字都要能马上反映出来。多端一致同一个学生今天用手机刷明天用平板刷界面表现和交互逻辑必须一致。Flutter的自绘UI天然适合这类“表单列表图表”密集型应用渲染链路统一不需要为不同平台维护两套控件。再加上OpenHarmony平板的屏幕比例和Android不太一样、系统控件行为也有差异如果做原生双端工作量直接翻倍用Flutter则只需要处理一个自定义UI层平台差异收敛到插件层。所以这个项目的核心价值不是“我能用Flutter跑OpenHarmony”而是“用一套Dart代码同时交付了Android和OpenHarmony两个版本的题库产品”并且统计概览这种需要频繁刷新图表、动态计算指标的功能在自绘UI下实现起来非常顺手。2. 环境搭建从 Flutter SDK 到 OpenHarmony 真机跑通的完整链路2.1 官方分支、社区分支和SDK版本的选择先说结论Flutter for OpenHarmony目前的成熟路径不是直接用flutter官方仓库代码跑OpenHarmony目标而是使用带OpenHarmony适配的Flutter SDK分支配合OpenHarmony官方SDK进行交叉编译。社区里已经有比较完整的适配方案开发流程大致是下载适配OpenHarmony的Flutter SDK分支替换默认的flutter工具链。安装OpenHarmony SDK包含API、工具链和模拟器镜像。在Flutter工程里启用OpenHarmony平台支持。用hvigor构建OpenHarmony的hap包跑在模拟器或真机上。这套流程和“用Flutter写Windows/macOS桌面应用”的体验很像本质上是同一个Flutter引擎同时支持了新的平台嵌入层只是编译目标从APK变成了HAP。我在早期搭建时最头疼的是SDK版本匹配。OpenHarmony的API版本更新很快Flutter适配分支的版本往往滞后两者不匹配时编译会报各种奇奇怪怪的符号错误和运行时崩溃。我的建议是别追求最新找一个“经过验证的组合”。具体做法是先看适配分支的发布说明确认它对应的是OpenHarmony哪个API版本然后锁死你的SDK版本不要手滑点升级。2.2 版本校验机制那个“not known to be fully supported”是哪里来的编译过程中我最常看到的一句提示是the current configured Flutter SDK is not known to be fully supported这句话的意思是当前Flutter工具链检测到你使用的SDK版本不在它的已知支持列表里。它不一定是硬错误后面可能还能编译过但说明你的组合是“未经测试”的风险自担。这句话在OpenHarmony适配场景里特别常见因为它本质上是“Flutter官方工具链默认不认识OpenHarmony目标平台”。排查链路基本是这样的先跑flutter doctor -v看Flutter工具链是否识别到OpenHarmony环境变量。再确认你选用的Flutter适配分支是不是正确拉取有没有被IDE覆盖回官方版本。然后检查OpenHarmony SDK的API版本是否在适配分支的兼容列表里。最后看项目的.metadata文件和flutter/config配置确保没有残留旧平台设置。这里有个经验如果报错信息只是warning后面编译能出包可以选择忽略但如果报错同时还伴随引擎初始化失败或真机白屏那基本可以断定是版本组合不对老老实实切换版本比打补丁快得多。2.3 第一个OpenHarmony页面启动图到首帧环境配好后我做的第一件事不是直接写业务代码而是用一个空Flutter工程跑通“OpenHarmony模拟器显示Flutter首帧”的全流程。这一步非常关键因为Flutter在OpenHarmony上的启动链路和Android不一样涉及原生启动图、Flutter引擎初始化和首帧渲染三个阶段的衔接。启动图的配置值得单独说。Flutter应用在OpenHarmony上启动时先显示原生Ability配置的启动窗口然后才是Flutter引擎创建、加载Dart代码、渲染首帧。如果原生启动窗口直接关掉而Flutter首帧还没准备好就会出现一段明显的白屏。我实测下来正确做法是把原生启动图的展示时间拉长一点做成品牌色启动页然后在Flutter端初始化完成后调用一个Platform Channel通知原生关闭启动窗口实现“原生页无缝过渡到Flutter页”的效果。3. 题库工程结构part、Bloc、Cubit 的使用边界3.1 用 part 组织领域模型的实测体验题库项目里领域对象不少题目、答题记录、科目、统计聚合结果每个对象还有一堆扩展方法和序列化逻辑。如果全部塞在一个文件里几千行代码根本没法维护。Dart提供了part和part of机制可以把一个库拆成多个文件这些文件共享同一个库作用域可以直接访问私有成员。很多人问part和普通import有什么区别简单说import是隔离的只能访问公开接口part是“一伙的”文件之间可以互访私有内容。我在题库项目里用part组织了一套题目解析相关代码// question.dart library question; part question_parser.dart; part question_serializer.dart; class Question { final String id; final String subject; final String content; final ListString options; final int correctIndex; const Question({...}); }// question_parser.dart part of question.dart; Question parseQuestionFromJson(MapString, dynamic json) { return Question( id: json[id] as String, subject: json[subject] as String, content: json[content] as String, options: ListString.from(json[options]), correctIndex: json[correctIndex] as int, ); }老实说part用在“同一主题的多个辅助文件”上很舒服解析逻辑、序列化逻辑和模型定义分离又不需要像import那样反复暴露接口。但要注意part文件里的代码和主文件在同一个命名空间变量名冲突会直接编译报错所以只在确实需要共享私有成员时才用。如果只是普通工具函数用import就够了滥用part反而会制造隐式耦合。3.2 状态管理题库流程用 Bloc统计页用 Cubit题库App里有两类状态它们对状态管理的要求完全不同答题流程状态之间有严格的流转关系比如“待作答 - 已作答 - 已提交 - 下一题”还要处理答案记录、计时、错题标记这种适合用Bloc的Event - State模型因为事件驱动的写法能把流程控制得清楚。统计概览本质上是“加载数据 - 展示结果”没有复杂流程只有三种状态加载中、加载成功、加载失败。这种场景用Cubit就够了省掉了Bloc的事件类样板代码。统计页的Cubit我写得很轻class StatisticsCubit extends CubitStatisticsState { StatisticsCubit(this._repository) : super(StatisticsLoading()); final StatisticsRepository _repository; Futurevoid loadStatistics() async { emit(StatisticsLoading()); try { final data await _repository.fetchStatistics(); emit(StatisticsLoaded(data)); } on Exception { emit(StatisticsError(统计加载失败请稍后重试)); } } }为什么这里不用Bloc因为统计页没有用户点击“统计”按钮之外的复杂交互引入Bloc等于写了三四个Event类收益很小。真正复杂的流程在答题页我在那里用了Bloc把答案提交、错题判定这些动作都转成事件由Bloc统一维护状态机。这套“核心流程用Bloc、轻量页面用Cubit”的搭配帮我控制住了代码量也让统计页的代码一眼能看懂。4. 统计概览的核心答题记录表与聚合算法4.1 答题记录怎么落库统计概览依赖的基础数据是每一道题的答题记录。我的设计是每答一题落一条记录包含下面这些字段字段类型说明recordIdString记录唯一IDquestionIdString题目IDsubjectIdString科目ID用于按科目录统计selectedIndexint学生选的选项下标correctIndexint正确答案下标isCorrectbool是否正确durationSecondsint本题耗时answeredAtDateTime作答时间存储层我用的是轻量级本地数据库按answeredAt建立索引因为统计概览页最常查的就是“最近7天的做题情况”。这里有一个小坑如果记录表里只有题目ID和科目ID后续题目内容有修改统计页想要展示“某道题的正确率”时还要反查题目表联表查询在移动端数据库上虽然也能做但性能会差。折中方案是在记录表里冗余一个questionBrief字段存题目的一小段摘要统计页列表直接显示不用再查第二张表。4.2 三个统计指标的计算链路题库的统计概览页我最终保留了三个核心指标总正确率正确题目数 / 已答题数。这里我刻意把“已答对题数”和“已答题数”分开算因为学生可能只做了50题正确率90%但这并不代表他掌握了整本书。各科正确率分布按科目分组计算展示为横向柱状图或环形图让老师一眼看到薄弱学科。近七日做题趋势按天统计每日做题数和正确数展示为柱状图辅助判断学习节奏。计算逻辑的核心是分组聚合。Dart里用groupBy思路做就可以MapString, SubjectStat aggregateBySubject(ListAnswerRecord records) { final result String, SubjectStat{}; for (final record in records) { final stat result.putIfAbsent( record.subjectId, () SubjectStat(subjectId: record.subjectId), ); stat.total; if (record.isCorrect) stat.correct; } return result; }这段代码的复杂度是O(n)一次遍历完成所有科目的计数。对于几千条记录来说完全够用不需要上MapReduce式的复杂框架。4.3 实时聚合还是预聚合一个折中方案刚开始我图省事每次进统计页都直接查全表聚合但数据量上来后几千条记录以上统计页的加载开始出现可感知的卡顿尤其是在旧设备上。后来我做了个折中方案维护一张daily_statistics预聚合表每天结束后按天、按科目累计数据。每次查询时先取预聚合表的绝大部分数据再额外实时统计“当天新增的记录”。这个方案既避免了全表扫描又保证了当天数据是最新的因为统计页里“今天”的数据量通常很小实时计算很便宜。预聚合任务放在每日凌晨用后台任务触发一次如果某天没触发也没关系用户打开统计页时发现预聚合不是最新会自动补算一次。5. 统计概览UI自绘CustomPaint、TabBar动画和重绘隔离5.1 不用图表库用CustomPaint画柱状图和环形图统计页如果直接引一个Flutter图表库在OpenHarmony上要额外验证兼容性而且图表库体积大、自定义受限。我选择用CustomPaint自绘核心原因是统计概览的图表就那么几种柱状图和环形图完全可以用几十行代码画出来不需要为一个柱状图引入几百KB的依赖。柱状图的核心是用CustomPainter绘制圆角矩形class BarChartPainter extends CustomPainter { final Listdouble values; final double maxValue; BarChartPainter({required this.values, required this.maxValue}); override void paint(Canvas canvas, Size size) { final barWidth size.width / (values.length * 1.5); final spacing size.width / (values.length * 1.5) / 2; final maxHeight size.height; final paint Paint()..color const Color(0xFF4C8DFF); for (var i 0; i values.length; i) { final barHeight maxHeight * (values[i] / maxValue); final left spacing i * (barWidth spacing) barWidth * 0.1; final rrect RRect.fromRectAndRadius( Rect.fromLTWH(left, maxHeight - barHeight, barWidth, barHeight), const Radius.circular(4), ); canvas.drawRRect(rrect, paint); } } override bool shouldRepaint(covariant BarChartPainter oldDelegate) { return oldDelegate.values ! values || oldDelegate.maxValue ! maxValue; } }环形图就更简单了用canvas.drawArc画出扇形缺口中间再叠一个Text组件显示百分比即可。自绘的好处是我能精确控制动画统计数字从0变到目标值柱子从底部生长到目标高度这些都是原生控件很难做到的交互动效。5.2 TabBar 点击取消动画为什么默认动画不理想题库App底部有“题库”、“统计”、“我的”三个Tab我用的是自定义TabBar。Flutter自带的TabBar默认会附带一个滑动的指示器动画视觉上是“指示器从当前Tab滑动到目标Tab”。这个动画在大多数场景下很流畅但在艺考题库这种高频切换场景里如果同时还要刷新统计图表滑动动画会和页面切换动画形成“双重位移”视觉上有点过。后来我查了Flutter TabBar的实现发现可以通过TabController的animationDuration控制动画时长把它设成Duration.zero再配自定义的indicator就能实现“点击即切换、没有滑动指示器”的效果。实际代码是这样TabBar( controller: _tabController, indicatorColor: Colors.transparent, labelColor: Colors.black, unselectedLabelColor: Colors.grey, // 关键是这一行把动画时长置零 // 但注意这里置零的是TabBar内部切换动画 )不过直接改源码不是最优解。更可控的做法是自己监听TabController.index用一个AnimatedContainer或AnimatedSwitcher管理页面切换动画把“Tab点击”和“内容动画”彻底解耦。这样点击Tab的瞬间内容区立即切换不再受默认滑动动画的影响。5.3 RepaintBoundary 与最小重绘统计页最容易出现的性能问题是图表区域因为外层状态变化被反复重绘比如加载成功后整个页面setState图表也跟着重画一遍但其实数据根本没变。解决这个问题的办法是给图表区域包一层RepaintBoundaryRepaintBoundary( child: CustomPaint( painter: BarChartPainter(values: snapshot.chartValues, ...), size: Size(320, 160), ), )RepaintBoundary会把子组件隔离到独立的绘制层父级发生重绘时只要子组件自身的shouldRepaint返回false它就不会被重新绘制。我在统计页的所有图表组件上都加了这一层配合Cubit对StatisticsState做精确的相等判断实测数据刷新时图表不会出现无意义的闪烁和重建。这里还有一个更实用的细节统计页的数字动画。数字从旧值跳到新值如果用AnimationController从头播放每次进页面都要重跑体验反而拖沓。我的方案是只在数据变化超过阈值时才播放动画否则直接显示静态数字。这就避免了“每次打开统计页都要看一遍数字涨落”的尴尬。6. 上线前绕不开的问题网络异常、崩溃边界和数据缓存6.1 SocketException 处理逻辑题库App的题目内容虽然本地也有缓存但最新的真题和统计数据还是要从服务端拉取。OpenHarmony设备网络环境并不总是稳定尤其是校园Wi-Fi切网频繁很容易触发SocketException。如果这个异常不捕获Flutter层面会直接抛错用户看到的就是一个红屏或难看的错误提示。我的统一处理策略是三层底层Repository捕获所有网络异常转换成业务异常类型比如NetworkTimeoutException、NetworkUnavailableException。Bloc或Cubit捕获这些业务异常更新到State里UI层根据异常类型展示不同的提示。提供一个“重试”按钮点击后重新触发数据加载逻辑而不是让整个页面重启。有一个容易被忽略的点SocketException在真实设备上比模拟器上频繁得多模拟器网络正常不代表真机没问题。所以一定要在真机上测试弱网场景我常用的方式是走到信号差的角落、或者用系统级的飞行模式开关来模拟断线。6.2 原生启动图与Flutter首帧的衔接前面提到过启动图这里展开讲讲我的完整方案。OpenHarmony原生端Ability创建时会显示一个启动窗口这个是原生配置的Flutter引擎初始化完成并渲染出第一帧后原生窗口如果还在两者就会重叠视觉上表现为“原生启动图停留过久”或“白屏闪一下”。我在项目里的做法是原生启动窗口的背景色设成与Flutter首屏背景色一致。在Flutter端Dart代码里通过Platform Channel向原生发一个firstFrameReady消息原生收到后主动关闭启动窗口。这样一来用户看到的是一张静态的品牌色页面然后页面内容自然出现没有任何白屏或跳变。这里的坑在于firstFrameReady信号一定要在WidgetsFlutterBinding.instance.addPostFrameCallback里发送不能放在main()里因为main()执行不等于首帧已经渲染出来。6.3 回到 60fps几项收益明显的性能优化统计概览页最怕的就是数字滚动、柱状动画、列表刷新一拥而上导致帧率掉到30fps以下。我总结了几项在OpenHarmony上实测收益明显的优化大量使用const构造函数这是成本最低、收益最稳定的优化。Flutter的const对象会被复用不会在build时反复创建统计页的文字、图标、装饰器能加const的都加了。ListView.builder而不是ListView题库列表项有题目和选项如果直接用ListView(children: ...)所有项都会一次性构建改用ListView.builder后只有可视区域内的项才会被构建。图片预解码科目图标和题目配图如果在列表里直接Image.asset图片解码会占用UI线程。先在最前面的页面里做一次预解码再传递ImageProvider给列表滚动时就不会因为解码而掉帧。避免在build里做聚合计算统计页的所有聚合结果都提前在Cubit里算好存到State里UI只做展示。永远不要在build方法里调聚合函数因为build可能一帧执行多次聚合计算会白耗性能。这些优化做下来统计页在OpenHarmony平板上的滚动和动画基本稳定在60fps和Android端的表现持平。最后聊聊我的一点体会。很多人看到“Flutter for OpenHarmony”第一反应是观望担心版本不稳定、社区不成熟。我的实践结论是在题库这类中轻交互业务里已经可以投入产出比很好地用起来。关键是把“业务逻辑”和“平台差异”隔离干净让Flutter层只依赖抽象的接口OpenHarmony和Android的差异留在插件层。这样就算明天OpenHarmony适配又升级了一版你改的也只是接入代码而不是整个业务。艺考真题题库只是个开始统计概览这种高频动态计算的模块跑顺了后面再做错题导出、学习报告、教师端数据看板都是同一套底子。
