Flutter在OpenHarmony上开发任务列表App的实践与踩坑

社团换届后接到的第一个技术活就是把散落在群聊里的任务安排收拢成一个真正能用的App。手里的测试设备是一台搭载开源鸿蒙OpenHarmony的开发板讨论方案时有人建议用原生ArkTS写但我想下半年还有安卓和桌面端的发布计划代码重复写一遍实在太亏。最终定下来用Flutter——一套UI代码先跑通OpenHarmony后续平移到其他平台能省一大半力气。这篇文章就把“任务列表”这个核心模块从技术选型到落地的完整过程拆开讲包括数据模型设计、列表页实现、本地存储和真机调试里踩过的坑适合已经会一点Flutter、准备往开源鸿蒙生态里试水的开发者参考。先说结论任务列表看上去简单但真正在一个非官方支持的全新平台上跑起来很多细节是文档里根本不会写的。下文我会尽量把每一步为什么这么做讲清楚关键代码也给出来可以直接抄作业。1. 项目定位与整体设计思路1.1 为什么社团任务管理先拿“任务列表”开刀社团管理App看起来很丰富但拆开看最核心的流量入口其实是任务列表。日常的例会安排、活动分工、物资筹备、宣传物料的进度跟踪本质都是一个个有状态、有责任人、有截止时间的任务项。把这些任务以列表形态展示出来用户一眼就能看到自己该干什么、哪个任务快到期了、哪些已经做完。从开发角度讲任务列表是一个“麻雀虽小五脏俱全”的模块。它涉及数据模型定义、状态管理、列表渲染、交互反馈、本地持久化还要处理刷新、滑动删除、筛选这些常见操作。把这一个模块做扎实后面再加任务详情页、数据统计、消息通知都是在这个骨架上添砖加瓦。我当时的规划是先做任务列表作为技术验证因为它是整个App所有功能的载体。任务列表跑通了意味着Flutter在OpenHarmony上的UI渲染、事件响应、存储读写这一整条链路都通了后面再做别的页面心里就有底。反过来如果一上来就做复杂的多角色权限体系一旦底层适配出问题排查范围会大得吓人。1.2 Flutter跑在OpenHarmony上到底靠不靠谱Flutter官方支持的平台是Android、iOS、Web、Windows、macOS、LinuxOpenHarmony不在官方列表里。但这并不代表跑不了。开源鸿蒙体系有对应的Flutter适配版本本质是把Flutter的渲染引擎迁移到了OpenHarmony的图形栈上Dart层和Widget层的代码完全复用不需要因为平台切换重写UI。说一下我的实际感受纯Dart代码包括数据模型、状态管理、业务逻辑在OpenHarmony上和在其他平台上几乎没有区别。UI层也基本能跑因为Flutter是自己绘制UI的不依赖系统组件。真正变化大的是底层插件——凡是涉及原生能力的比如文件路径、数据库、网络请求都要找适配了OpenHarmony的版本或者自己补一层平台通道。团队里有同事建议直接用ArkTS写理由是OpenHarmony原生生态肯定适配得最好。这个我承认单纯为了OpenHarmony一个平台写ArkTS没问题。但我们的情况是后续还要出安卓版和桌面端如果每个平台写一套UI后续维护成本直接翻三倍。用一个团队已经熟悉的Flutter栈是当时性价比最高的选择。到了开发中后期ArkTS和Flutter在功能上都能完成需求差别主要在多端复用和生态成熟度上。1.3 状态管理选型从setState到Provider任务列表的状态管理方案我纠结了一阵子。最基础的做法是StatefulWidget加setState简单直接但那仅限于单个页面内部改改数值。社团管理App有多个页面会读写任务数据比如列表页要改完成状态详情页要编辑任务字段统计页要读取任务数量如果各自维护一份数据同步就成了灾难。所以需要一个共享的状态容器。我选的方案是Provider加ChangeNotifier没有上Riverpod也没用Bloc。原因是任务模块的状态结构足够简单就是一组任务对象的增删改查加上一个筛选维度。ChangeNotifier配合notifyListeners足够覆盖这个场景学习成本还低社团里的新成员接手代码也快。Provider的优势在于它把“数据和界面分离”这件事做得非常干净。界面层只负责调用状态对象的方法和监听变化不关心数据是怎么存储、怎么同步的。后面如果要引入网络后端只需要在Model内部把本地数组换成远程接口的映射UI层可以完全不动。工程目录也按这个思路分了三层Models放任务实体States放状态管理Pages放UI页面。这个结构对一个小型项目管理App来说刚刚好不会过度设计。2. 核心细节解析任务列表的数据模型与UI方案2.1 任务数据模型的字段设计任务模型是整个App的基石字段设计得不好后面加功能时会各种别扭。我最终敲定的结构是这样import package:flutter/foundation.dart; enum TaskPriority { low, medium, high } class Task { Task({ required this.id, required this.title, this.detail , this.priority TaskPriority.medium, this.deadline, this.assignee , this.isDone false, }); final String id; final String title; final String detail; final TaskPriority priority; final DateTime? deadline; final String assignee; bool isDone; Task copyWith({ String? title, String? detail, TaskPriority? priority, DateTime? deadline, String? assignee, bool? isDone, }) { return Task( id: id, title: title ?? this.title, detail: detail ?? this.detail, priority: priority ?? this.priority, deadline: deadline ?? this.deadline, assignee: assignee ?? this.assignee, isDone: isDone ?? this.isDone, ); } MapString, dynamic toJson() { return { id: id, title: title, detail: detail, priority: priority.index, deadline: deadline?.millisecondsSinceEpoch, assignee: assignee, isDone: isDone, }; } factory Task.fromJson(MapString, dynamic json) { return Task( id: json[id] as String, title: json[title] as String, detail: json[detail] as String? ?? , priority: TaskPriority.values[json[priority] as int? ?? 1], deadline: json[deadline] null ? null : DateTime.fromMillisecondsSinceEpoch(json[deadline] as int), assignee: json[assignee] as String? ?? , isDone: json[isDone] as bool? ?? false, ); } }字段看起来不少但每个都有明确用途。id用时间戳加随机数生成保证唯一后面做数据库主键要用。title是必填的扼要说明任务内容。detail存补充描述比如活动物资清单、宣传推文链接。priority三档就够了低中高对应普通、紧急、非常紧急再多用户根本懒得选。deadline用DateTime本地存储时转成毫秒时间戳避免时区问题。assignee存责任人姓名以后做消息通知时就靠它定位人。isDone是完成标记列表筛选的核心依据。设计模型时我克制了一点没有一上来就加tag标签、附件列表、重复规则这些字段。原因很简单这些功能当前都用不上加了只会让addTask和editTask的接口越来越臃肿。Flutter的数据模型最佳实践是“按需迭代”先把确定性需要的字段做扎实后续通过copyWith方法平滑扩展。2.2 列表项的视觉层级与布局拆解任务列表的用户体验基本取决于列表项的排版这一块值得花心思。我用的是CheckboxListTile作为基础组件原因很实际它自带多选框、标题、副标题三个位置的完整布局点击整行都能切换状态无障碍语义也是现成的比自己拼Row和GestureDetector省不少代码。视觉上我做了一个显眼但不过头的优先级提示用列表项左侧的色条区分紧急程度红色高优先级、黄色中优先级、绿色低优先级或已完成。色条用Container的decoration画一个窄条放在卡片的最左边。这样做的好处是不需要额外文字说明用户扫一眼色块就知道优先级。Container( width: 4, decoration: BoxDecoration( color: task.priority TaskPriority.high ? Colors.redAccent : task.priority TaskPriority.medium ? Colors.orangeAccent : Colors.greenAccent, borderRadius: BorderRadius.circular(2), ), )标题行放任务名称和优先级图标副标题显示截止时间和责任人。截止时间的格式我封装了一个方法把DateTime格式化成“MM-dd HH:mm”避免直接打印出一长串难看的时间戳。已完成的任务标题加删除线文字颜色调成灰色这是移动应用里最常见的“完成反馈”用户理解成本最低。空状态一开始没做后来在真机上发现任务列表清空时整个页面白茫茫一片用户会以为App坏了。于是加了一个简单的空状态视图中间放一个icon和一行提示文字“暂无待办任务点击右下角新建”。这件事看着小对体验的提升却非常明显。2.3 交互细节优先级、筛选、滑动操作交互方面我做了三个核心功能每个都在真实使用中被反复验证过。筛选功能用的是Material 3的SegmentedButton分“全部”“待办”“已完成”三档。切换筛选时不需要重新请求数据只是在状态模型里维护一个TaskFilter枚举然后在getter里做一次where过滤。这里有一个小坑如果直接在build方法里做过滤每次通知都会触发全量遍历数据量少没事任务多了就会卡顿。正确做法是把过滤后的列表缓存到State里只在筛选条件或数据源变化时重新计算。滑动删除用的是Dismissible这个组件很强大但有个副作用列表刷新时如果不加保护正在滑动中的item会被意外判定为删除。我的处理是在Dismissible的confirmDismiss回调里做二次确认弹一个SnackBar用户点“删除”才真正移除数据。这样可以防止误删尤其社团里多人共用一台演示设备时特别有用。排序功能我做了“按截止时间升序”和“按优先级降序”两个选项放在AppBar的PopupMenuButton里。默认按截止时间排序让用户第一时间看到最紧迫的任务。实现上就是在状态模型里保存一个SortMode枚举getter里对列表做sort操作。注意sort会改变原列表顺序所以排序前必须copy一份否则会导致状态数据被意外重排。这些交互拆开看都不复杂但组合在一起任务列表就从一个干巴巴的列表变成了一个能真正被日常使用的工具。3. 实操过程从环境搭建到任务列表落地3.1 构建环境适配版Flutter SDK与IDE开发前要把环境准备好这一块是最容易劝退新手的因为网上能找到的教程不是过时就是针对性不够。我用的是DevEco Studio作为主要IDE它自带OpenHarmony开发插件可以直接创建和构建HAP包。Flutter侧需要安装适配OpenHarmony的Flutter SDK版本这个跟官方标准版是两个不同的分支千万不能搞混。安装完成后把适配版Flutter的bin目录加到PATH环境变量里保证命令行里执行flutter命令用的是适配版。这里有个容易踩的坑适配版Flutter通常对应固定的OpenHarmony API版本比如某套SDK只支持OpenHarmony 4.x。如果你的开发板系统版本太旧或太新构建时会出现各种奇怪的编译错误。建议先查清测试设备的系统版本再回推该装哪个Flutter分支。我当时一开始装了不匹配的版本编译报错了一个下午最后才发现是API level对不上。真机调试方面我用的是开发板加屏幕的方案虽然不如手机方便胜在OpenHarmony系统版本可控。连接后通过IDE的部署功能直接把HAP包安装到设备上整个过程和普通Flutter开发的流程非常接近只是构建目标从APK变成了HAP。3.2 创建工程并引入OpenHarmony适配依赖环境就绪后用flutter create命令创建工程flutter create --org com.example club_task_app创建完成后核心要处理的是pubspec.yaml里的依赖。我用到的依赖没有很多但全部要对齐OpenHarmony的适配生态dependencies: flutter: sdk: flutter provider: ^6.1.1 shared_preferences: ^2.2.2 intl: ^0.18.1provider和intl本身是纯Dart实现跨平台没问题。shared_preferences是个典型的原生插件在OpenHarmony上需要使用已经有适配声明的版本如果拉取不到匹配的二进制就需要从源码编译。OpenHarmony的Flutter适配层对插件的管理方式和Android不完全一样有些插件包在pub.dev上看着是最新版但没做过OpenHarmony的移植强行引入会出现原生工程配置错误。我的建议是创建工程后先跑一个空壳App验证环境再逐步加依赖。一旦加了某个依赖后编译不过立刻回退不要拖着排查。3.3 任务模型与状态管理代码实现任务模型在上文已经给出了完整代码这里重点说状态管理这块的书写心得。我定义了一个TaskListModel继承ChangeNotifier内部维护一个私有的List 对外提供增删改查方法和各种过滤列表。核心代码如下import package:flutter/foundation.dart; class TaskListModel extends ChangeNotifier { final ListTask _allTasks []; ListTask get allTasks List.unmodifiable(_allTasks); ListTask get pendingTasks _allTasks.where((t) !t.isDone).toList(); ListTask get doneTasks _allTasks.where((t) t.isDone).toList(); void addTask(Task task) { _allTasks.add(task); notifyListeners(); } void toggleTask(String id) { final index _allTasks.indexWhere((t) t.id id); if (index 0) { _allTasks[index].isDone !_allTasks[index].isDone; notifyListeners(); } } void deleteTask(String id) { _allTasks.removeWhere((t) t.id id); notifyListeners(); } void loadTasks(ListTask tasks) { _allTasks ..clear() ..addAll(tasks); notifyListeners(); } }注意到getter里我用了List.unmodifiable和toList这是为了防止外界直接修改列表内容所有修改都必须经过Model的方法。这是个好习惯因为状态管理的核心就是保证数据变更可控、可追踪。在页面中使用时我通过Provider把这个Model放到顶层列表页用ListenableBuilder监听变化。ListenableBuilder是Flutter 3.10以后推荐的新组件比之前的AnimatedBuilder语义更清晰专门用来监听Listenable重建子组件。ListenableBuilder( listenable: context.watchTaskListModel(), builder: (context, _) { final tasks taskModel.pendingTasks; if (tasks.isEmpty) { return const Center(child: Text(暂无待办任务)); } return ListView.builder( itemCount: tasks.length, itemBuilder: (context, index) { final task tasks[index]; return Dismissible( key: ValueKey(task.id), direction: DismissDirection.endToStart, onDismissed: (_) taskModel.deleteTask(task.id), child: CheckboxListTile( value: task.isDone, onChanged: (_) taskModel.toggleTask(task.id), title: Text( task.title, style: TextStyle( decoration: task.isDone ? TextDecoration.lineThrough : null, color: task.isDone ? Colors.grey : Colors.black87, ), ), subtitle: Text( 截止 ${formatDeadline(task.deadline)} · ${task.assignee}, ), secondary: buildPriorityIcon(task.priority), ), ); }, ); }, )状态管理写到这里基本够用。后面如果需要接后端可以在TaskListModel里添加Future方法通过dio请求远程数据然后调用loadTasks回填列表。UI层的逻辑完全不需要改动。3.4 列表页UI与本地持久化实现本地存储我用了shared_preferences它以键值对的形式存储小型数据适合保存任务列表这种JSON序列化后的数据。保存和读取的代码如下import dart:convert; import package:shared_preferences/shared_preferences.dart; class TaskLocalStore { static const _key task_list; static Futurebool save(ListTask tasks) async { final prefs await SharedPreferences.getInstance(); final data tasks.map((t) jsonEncode(t.toJson())).toList(); return prefs.setStringList(_key, data); } static FutureListTask load() async { final prefs await SharedPreferences.getInstance(); final data prefs.getStringList(_key); if (data null) return []; return data .map((e) Task.fromJson(jsonDecode(e) as MapString, dynamic)) .toList(); } }为什么用shared_preferences而不是数据库因为这个阶段的任务量撑死几百条而且没有复杂的查询需求。直接用键值对存JSON代码量最小也最容易理解。等以后任务量上来要做按人筛选、按时间范围统计再替换成数据库也不迟存储层已经做了隔离替换成本很低。App启动时我在main函数里先异步加载本地数据然后把TaskListModel注入到Provider中void main() async { WidgetsFlutterBinding.ensureInitialized(); final tasks await TaskLocalStore.load(); final taskModel TaskListModel()..loadTasks(tasks); runApp( ChangeNotifierProvider( create: (_) taskModel, child: const ClubApp(), ), ); }每次任务数据变化后在Model内部统一调用TaskLocalStore.save这样能保证内存和本地存储始终一致。我当时没有做防抖处理任务量少时无所谓以后如果高频修改可以加一个简单的debounce。UI方面列表页的骨架是Scaffold加AppBarAppBar标题显示当前筛选状态右上角是排序菜单右下角是一个FloatingActionButton点击跳转到新增任务页面。新增页用一个简单的Form表单收集标题、描述、优先级、截止时间和责任人提交时回调Model的addTask。底部还做了一个统计条显示“待办x项 · 已完成y项”用Row加两个Text实现。这个统计条放在列表下方通过BottomAppBar承载既能给用户整体感知又不干扰列表滚动。这个设计是后期加上的第一次使用后就被社团反馈很有用算是意外收获。4. 踩坑实录与问题排查4.1 插件适配导致的编译失败整个开发过程中最折磨人的就是插件适配问题。任务的本地存储这块我一开始天真地以为shared_preferences在所有平台都一个样直接pub get就完事。结果构建HAP时原生工程报错提示找不到某个原生符号。排查了半天确认是OpenHarmony适配版本没有正确引入。这种情况的解决思路是不要死磕官方最新版插件先查适配版本的分支确认它能支持OpenHarmony的API版本。有些插件在pub.dev上的版本号没变但内部实现已经支持了多平台关键要看有没有OpenHarmony的package/paths配置。遇到编译错误时先读完整日志定位到是哪个原生模块出的问题。不要试图绕过它因为绕过的方案往往会让App运行崩溃。最稳妥的做法是把依赖回退到适配分支验证过的版本然后重新构建跑通后再考虑升级。常见的插件是这样分布的插件在OpenHarmony上表现建议provider纯Dart直接可用不需要额外处理intl纯Dart直接可用不需要额外处理shared_preferences需要适配版本引入前确认适配分支dio纯Dart底层用dart:io可以直接用path_provider需要适配版本获取目录前先测试读写权限sqflite需要适配版本数据量大时再考虑引入表格里这些结论是我在实际工程里验证过的不代表所有场景都会遇到但能帮你快速定位问题方向。4.2 中文字体与SafeArea渲染差异Flutter在OpenHarmony上的字体渲染跟Android相比有一些细微差别。最明显的是中文字重在部分开发板上默认字体显示得偏细小号文字会有些发虚。这个问题比较难完美解决我当时做的是在MaterialApp的主题里统一指定fontFamily为一个开源的思源黑体适配方案整体观感好了不少。字体文件会增大包体但任务列表这个App对包体没那么敏感所以能接受。另一个坑是SafeArea。OpenHarmony上不同设备的系统栏高度不一致尤其开发板接的屏幕和带触摸屏的设备差异很大。如果列表底部没有正确避开系统NavigationBar会出现最后一条任务被遮挡的情况。我的处理方式是把列表页的Scaffold包在SafeArea里同时给ListView的padding加一个底部安全边距。padding: EdgeInsets.only( bottom: MediaQuery.of(context).padding.bottom 8, ),这个细节看起来微不足道但真机上如果没有处理用户划不到最后一条数据会直接认为App有bug。还有键盘顶起问题。在新增任务页面输入描述时键盘会把提交按钮挡住。我在Scaffold上设置了resizeToAvoidBottomInset为true默认就是自适应但列表页的滚动位置和键盘弹出时的视觉跳动OpenHarmony上跟Android比有一点差别偶尔会出现滚动位置突然回弹。这个后来在build方法里对ListView的controller做了一次显式size检查才稳定下来。4.3 真机性能瓶颈与包体优化性能问题在任务列表数据量小时完全看不出来但我故意塞了300条样例任务做压力测试发现滚动列表的帧率还是能稳在60帧Flutter的渲染层在OpenHarmony上的表现比我预想的要好很多。真正需要优化的点是状态通知的频率。我刚开始写的时候每次点击Checkbox都会触发notifyListeners这会重建整个ListView。300条任务时能感觉到明显的卡顿。后来优化方案很简单把每个列表项用独立的ListenableBuilder包裹让重建范围缩小到当前项。实践下来滚动流畅度基本恢复到满帧。包体优化上最大的体积来源是字体文件和未使用的图标。Material图标库默认打包全量字体我在pubspec里启用了icons的shrink配置包体直接下降了十几兆。另外构建正式HAP包时gradle和Hvigor的压缩配置都开起来资源文件压缩率还不错。优化前包体大约是三十多兆优化后降到二十兆以内对一个内部管理工具来说完全可以接受。如果你的App对包体有严格要求还可以考虑移除自带字体改用系统字体渲染代价是中文字体观感下降这个取舍看场景。还有一点要提醒在OpenHarmony上调试时热重载有时候会不太稳定尤其是改动原生插件配置或pubspec依赖后热重载经常不生效甚至导致页面白屏。遇到这种情况不要反复点热重载直接冷重启App反而更快。这个习惯帮我省了不少时间。回看整个项目任务列表这个模块虽然不复杂但因为在OpenHarmony这个新平台上跑每一层都有值得记录的经验。我个人最深的体会是选Flutter不是因为它比ArkTS更“正确”而是因为它解决了我们的多端复用问题但任何跨平台方案都绕不开平台差异插件适配和渲染细节就是那个必须交的学费。如果你也正在表OpenHarmony上加Flutter建议先从小模块开始验证把链路跑通后再扩展。任务列表就是一个特别理想的第一块试金石。