天马行空的味道最近不止一次被问到一个问题：我手里这套Flutter写的App，到底能不能搬到OpenHarmony上？问的人有做二手交易平台的，有做企业内部工具开发的，也有纯粹想在国产开发板上跑点东西的。我给他们的回答基本都是同一句：能跑，而且思路通了之后，工程量比你想的小得多。这篇文章就以一个二手物品置换App的“分类筛选”功能为例子，完整走一遍Flutter在OpenHarmony上的实战落地过程。从环境搭建到分类导航，从筛选面板到过滤引擎，再到移植过程中真正让我头疼过的坑，都会提到。无论是你正准备把现有Flutter项目适配到OpenHarmony，还是想从零开始做一个支持国产系统的跨端App，都可以照着这条路线走。
先交代一下背景。我做的这个二手物品置换App，核心场景是用户把闲置物品拍照发布，其他用户按分类浏览、按条件筛选，然后线下或邮寄完成置换。业务本身不复杂，但分类筛选是用户每天都要碰的高频入口，必须做得顺手。原本这套代码跑在Android和iOS上，后来因为要覆盖OpenHarmony设备，就顺手做了跨端迁移。整个过程中，分类筛选模块既是业务核心，也是踩坑最多、最能体现Flutter跨端价值的地方，拿它来拆解最合适不过。
1. 为什么把二手置换App的筛选模块迁到OpenHarmony：技术选型逻辑
先说个大前提：OpenHarmony不是“换了个名字的安卓”，它是一个独立的操作系统底座，有自己的软件包格式、自己的应用框架和编译工具链。但好在它保留了标准C/C++和现代Web技术的接入能力，这给Flutter这种自绘引擎跨端移植留了一扇门。社区里已经有人把Flutter引擎移植到了OpenHarmony上，这意味着，我可以在不改动Dart业务代码的前提下，让同一套界面和交互跑在Android、iOS、OpenHarmony三个平台上。
1.1 二手置换场景为什么适合Flutter
二手置换App和那种强依赖系统原生能力的App不太一样。它不需要特别复杂的相机滤镜、不需要激光雷达扫描、也不需要深度的系统设置交互，核心功能就三个：浏览商品列表、按条件筛选、下单沟通。这类业务对UI一致性要求高，列表要能快速滚动，筛选面板要能在各种分辨率下稳定呈现，而这些恰好是Flutter的看家本领。Flutter用Skia自绘渲染引擎直接绘制每一个像素，不依赖系统控件，所以不同平台上的视觉表现基本一致。这对二手交易这种“用户要反复刷商品图”的App来说非常重要，界面统一意味着用户换设备不需要重新适应。
另外，Flutter的Dart语言在数据处理和状态管理上非常顺手。分类筛选这种大量依赖集合操作、条件组合判断的场景，用Dart的集合Api和不可变数据模型写起来很清爽，比在ArkUI里用TypeScript再套一层状态管理要舒服一些，至少对我来说是这样。
1.2 为什么不直接用ArkUI重新写
市面上OpenHarmony原生应用的主流开发方式是用ArkUI，搭配ArkTS语言。这套东西本身也成熟，但如果我重新用ArkUI把整个项目写一遍，等于把Android和iOS的Flutter版本全部推翻重做。人员成本、维护成本、后续功能同步成本都是成倍的。更何况，ArkUI的生态起步晚，社区组件和第三方库远不如Flutter丰富，我需要用的很多筛选组件、图片懒加载库、下拉刷新组件，在ArkUI里找不到现成方案，还得自己封装。
相比之下，Flutter on OpenHarmony的移植方案直接复用现有Flutter代码，筛选模块基本上改改平台相关适配就能跑起来，这也是我选择这条技术路线最核心的原因。
1.3 分类筛选在项目里的定位
在整个App里，分类筛选模块承担了三个职责：给用户提供清晰的商品浏览入口、把海量商品数据快速收敛到用户想要的范围、为后续的服务端查询提供精确的参数。我把它拆成了三块：数据模型层（管理分类树和筛选条件）、界面展示层（分类导航和筛选面板）、状态管理层（整合用户选择并触发过滤逻辑）。后面几节就按这个拆法逐一展开。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Flutter for OpenHarmony工程搭建与分类数据模型设计
很多人以为把Flutter项目跑到OpenHarmony上，就是下载一个SDK然后编译打包那么简单。实际做下来，环境配置和工程结构比普通Flutter项目要多花两三天时间。这部分的坑主要在版本对应关系上，建议先花点时间把工具链理顺，不然后面每个编译错误都够你查半天的。
2.1 环境准备：SDK版本与工具链对齐
我使用的方案是社区维护的flutter_flutter和flutter_ohos组合。前者是适配OpenHarmony的Flutter引擎仓库，后者是用于生成OpenHarmony宿主工程的命令行工具。
- 下载适配OpenHarmony的Flutter SDK，解压后放到独立目录，不要和你平时用的Flutter SDK混在一起，两个版本分支不同，混用容易出问题。
- 配置PATH环境变量，让
flutter命令指向OpenHarmony适配版本。 - 安装DevEco Studio，这个是OpenHarmony应用的IDE，用来创建宿主工程、编译HAP包、连接开发板调试。
- 确认OpenHarmony SDK版本和Flutter适配版本保持一致，我用的组合是OpenHarmony 4.0 Release配合当时的Flutter稳定适配版。
注意：Flutter on OpenHarmony的版本迭代比较快，不同版本之间API有差异，如果照抄别人的配置发现编译不过，优先查看自己用的Flutter SDK版本和openharmony-sig仓库的适配文档。
配置国内镜像源这一步也很关键，不然依赖下载速度会让你怀疑人生。在环境变量里设置PUB_HOSTED_URL和FLUTTER_STORAGE_BASE_URL指向国内镜像，然后正常执行flutter pub get就能拉取依赖。
2.2 建立OpenHarmony宿主工程
环境配好之后，用flutter_ohos命令行工具在Flutter项目目录下生成OpenHarmony宿主工程：
bash复制flutter create --platforms=ohos my_app
然后进入工程目录，执行flutter pub get同步依赖，再用DevEco Studio打开生成的ohos目录。这里生成的工程结构里，entry模块是应用入口，Flutter引擎跑在entry/src/main/ets/pages/Index.ets的XComponent容器里。简单理解的话，XComponent是一个原生组件承载区，Flutter的UI画面渲染到这个组件里，由OpenHarmony的Ability生命周期驱动。
如果你手里的项目已经有Android/iOS代码，不需要重新创建工程，直接在新版本Flutter SDK下执行flutter-ohos的初始化命令，让它在你现有项目里补一个ohos宿主目录就行。
2.3 分类数据模型：从接口返回的JSON到内存中的树
分类筛选的第一步，是先把后端返回的分类数据变成App里能用的结构。二手置换App的分类是多级树形结构，比如“数码设备 > 手机 > iPhone”、“家用电器 > 厨房电器 > 微波炉”。接口通常返回扁平列表或嵌套JSON，我这边后端返回的是嵌套结构，每个节点包含id、名称、父级