Flutter+OpenHarmony实战：三国杀攻略App战绩记录功能实现

写这篇博文的时候，我手上的OpenHarmony开发板刚好跑完一局三国杀的胜率统计。从Flutter工程创建到鸿蒙真机跑通，中间踩了不少坑，尤其是战绩记录功能涉及本地存储、列表刷新和统计计算，跟普通App开发完全是两回事。这篇文章是我用Flutter给OpenHarmony写三国杀攻略App时，实现战绩记录功能的全过程记录，包括环境配置、数据层设计、界面实现和问题排查。准备入坑OpenHarmony Flutter开发的兄弟，或者想在鸿蒙设备上做工具类应用的朋友，可以拿来做参考。

先说背景。三国杀攻略类App最核心的留存工具不是图鉴，而是战绩记录。玩家打完一局，需要快速记录身份、武将、胜负、评分，后续能看到自己总胜率、某个武将的胜负比，甚至连胜记录。这个功能玩法简单，但对数据存储、界面刷新和统计逻辑有明确要求，加上要跑在OpenHarmony这种非Android生态上，技术选型和适配方案就得提前想清楚。

1. 项目背景与技术选型：为什么用Flutter做OpenHarmony三国杀攻略App

1.1 三国杀攻略App的定位与战绩记录的核心诉求

三国杀攻略App的常规功能包括武将图鉴、卡牌查询、身份局规则速查，但这些都是静态内容，用户看完就走。真正能让用户留下来的，是一个“记录-查看-统计”闭环。战绩记录就是这个闭环的起点。

我设计的战绩记录功能，核心诉求有这么几条：

• 快速录入：打完一局后，10秒内完成一场记录，不能有复杂表单。
• 离线可用：不依赖后端服务，所有记录保存在本机，避免隐私和网络问题。
• 历史可查：按时间倒序展示所有对局，支持下拉刷新和长按删除。
• 统计分析：总场次、胜率、连胜、常用武将胜率，这些数字要有直接的计算结果。

这些诉求决定了技术方案不能太重。不需要云数据库，不需要用户系统，本地持久化加一套简单的统计逻辑就够。这也让我在选型时可以优先考虑开发效率和跨端兼容，而不是追求后端能力。

1.2 Flutter跨端能力与OpenHarmony的适配现状

选择Flutter，核心原因是跨端一致性和开发效率。一套Dart代码可以跑在Android、iOS、Web，以及OpenHarmony上。对于三国杀攻略这种中小型App，Flutter的UI开发效率和内置组件完全够用。

但OpenHarmony不是Android，它的API、文件系统、权限模型和应用沙盒都有自己的一套逻辑。官方Flutter SDK默认支持的是Android和iOS，要跑在OpenHarmony上，必须使用OpenHarmony社区维护的Flutter适配分支。目前流行的做法是使用flutter_flutter仓库的openharmony分支，配合DevEco Studio构建hap包。

我在搭建环境时踩过不少坑，后面会详细说。这里先提醒一句：不要直接拿官方Flutter主分支编译OpenHarmony目标，否则会出现大量找不到工程文件之类的问题。选型时一定要确认适配分支的版本号，并且尽量使用OpenHarmony 3.2以上的系统版本。

1.3 技术方案选型：路由、状态管理与本地存储

战绩记录功能涉及页面跳转、数据变更后刷新UI、本地读取与写入。我在技术选型时做了以下几项决策：

• 状态管理：使用Provider。理由是这个项目体量不大，Provider足够清晰，社区文档多，遇到问题也好搜。
• 路由：使用Navigator 1.0。为了降低适配风险，没有引入flutter_boost或go_router这些额外路由库，直接使用系统自带的Navigator，减少一层依赖。
• 本地存储：用JSON文件存储。这里我犹豫过，是使用shared_preferences、sqflite，还是直接写文件。后来实际尝试发现，OpenHarmony上sqflite的适配还不成熟，编译期容易报错，shared_preferences适合存储键值对，但对几千条战绩数据的查询和筛选支持较弱。最后选择了path_provider获取应用文档目录，用dart:io手动读写JSON文件，封装一个Store类来管理所有数据操作。

这个选型的好处是可控性强、依赖少、没有数据库版本升级的烦恼；缺点是每次增删改都要整体读写文件，性能上不如数据库。但战绩数据平时就是几百条到几千条，量级不大，JSON文件完全能扛住。

2. 开发环境搭建与工程改造：把Flutter跑上OpenHarmony

2.1 环境准备：OpenHarmony SDK与Flutter适配分支

这一步是整个项目最容易劝退人的环节。环境版本不匹配，后面全白搭。我建议按以下顺序准备：

1. 安装DevEco Studio最新版，自带的OpenHarmony SDK至少是3.2版本。
2. 下载OpenHarmony Flutter适配SDK，通过git clone拿到openHarmony分支。
3. 配置环境变量，包括flutter、dart、hdc和ohos_sdk的路径。注意环境变量配置后需要新开终端才会生效，我当时就因为这个白白折腾了十几分钟。
4. 使用flutter doctor检查环境，但在OpenHarmony环境下不要期待它全部绿勾，工具链本身没有对应的检测项，重点看Dart和Flutter版本是否正常。

版本匹配是重点。Flutter官方主分支迭代很快，OpenHarmony适配分支通常滞后几个版本。我用的组合是Flutter 3.7.12 + Dart 2.19.6 + Op