Flutter for OpenHarmony 这套组合最近咨询的人确实越来越多。前两篇我们解决了环境搭建、工程骨架和基础渲染验证有的读者已经把空白工程跑到了 OpenHarmony 真机上。这一篇进入正题实现垃圾分类指南 App 的首页。首页相当于整个 App 的门面也是用户第一次打开看到的东西它承担的不只是展示还要把搜索、分类、知识内容这些核心功能入口都串起来。这篇文章会把首页从信息架构、组件拆分到状态管理、打包验证完整过一遍代码也会给到可用的版本适合已经跑通 Flutter for OpenHarmony 基础工程、准备开始写业务页面的同学。1. 首页功能拆解与信息架构1.1 垃圾分类首页的核心任务垃圾分类指南这类工具型 App用户打开它的时机很明确手里拿着一样东西不确定扔哪个桶。所以首页的核心任务不是展示而是最短路径完成“从疑惑到答案”的闭环。这个结论听起来简单实际做信息架构时很容易被带偏。很多同类 App 会把首页做成运营位集合塞一堆轮播图、活动入口、新闻资讯结果用户打开后盯了三秒找不到搜索框直接卸载。我们在设计首页时砍掉了所有非必需模块只保留四个区域搜索区、分类速查区、热门误区文章、每日分类技巧。搜索区放在顶部保证用户第一眼就能看到分类速查区是四个常见分类可回收、有害、厨余、其他的快捷入口点进去看到的是该类下常见物品清单热门误区文章解决的是“我以为它是个可回收物其实它是有害垃圾”这类认知盲区每日分类技巧则给低频用户一点点新鲜感顺便兜底一些冷门知识。这个结构不是拍脑袋定的。我翻了不少同类 App 的首页也看过用户评论发现高频词集中在“找不到垃圾分类表”“这个东西算不算可回收”“塑料餐盒到底洗干净能不能回收”。搜索框加分类表两个入口加起来能覆盖绝大多数问题。热门文章和每日技巧属于内容型模块可以提升停留时长但优先级明显低于前两个。1.2 模块取舍为什么这里不做 AI 识别做需求评审时产品经理提过首页直接加“拍照识别垃圾”的功能听起来很酷但我拒绝了。理由有两个。一是技术链路太重拍照、上传、模型推理、结果返回任何一个环节失败都会把用户挡在门外二是垃圾识别本身是个模糊认知场景很多物品外表相似但材质不同AI 误判一次用户对 App 的信任感就崩了。第一版首页老老实实做搜索和分类速查把确定性留给用户比噱头重要得多。当时我画了一张简单的功能优先级表对着团队讲了十分钟功能用户价值技术成本首版决策关键词搜索极高低必做分类速查高低必做拍照识别中很高暂缓热门误区文章中低做放到首页下半部分每日分类技巧中低极低做轻量级这个表的意思是首版首页要的是快速、稳定、可维护不是大而全。拍照识别以后要做但应该作为独立功能页而非首页核心入口。宁可首页简单到一眼看透也不要把用户刚打开 App 的几秒黄金时间浪费在加载和跳转上。1.3 导航结构与滚动容器选择首页在 App 里不是孤立页面它和识别、指南、我的三个 Tab 一起组成底部导航。识别功能我们迟早要上所以底部 Tab 从第一版就预留了位置只是识别页先放了个占位提示。首页内部使用 CustomScrollView 来组织滚动区域顶部搜索框作为 SliverPersistentHeader 吸顶下面的宫格、文章列表、技巧区作为普通 Sliver 依次排布。一开始我纠结过要不要用 ListView 多个 section widget后来换成 CustomScrollView。原因是吸顶效果在 ListView 上实现起来很别扭要么自己监听滚动偏移要么把搜索框固定在页面顶部不动。固定搜索框是最简单但会吃掉垂直空间对于小屏设备不友好。CustomScrollView 配合 SliverPersistentHeader滚动时搜索框滑出、再滚回来时吸顶体验跟主流内容 App 一致。OpenHarmony 的 Flutter 引擎对滚动性能的处理和标准 Flutter 没有差别CustomScrollView 用起来没有额外坑。2. 工程基线确认与初始化配置2.1 工具链版本基线写任何 OpenHarmony 上的 Flutter 页面之前第一件事是确认工具链版本否则后面会遇到很多“看起来莫名其妙”的问题。我这里用的是 Flutter 3.19 对应的 OpenHarmony 分支版本DevEco Studio 用 5.0.3 及以上。之所以强调这个是因为 Flutter 官方主线的 Dart SDK 更新节奏很快但 OpenHarmony 适配版总是慢半拍尤其是一些涉及 Dart VM 内部接口的改动官方主线换了个实现适配分支没跟上就会出现编译通过但运行时崩溃的诡异现象。建议直接用 OpenAtom 基金会维护的 flutter_flutter 仓库的 OpenHarmony 分支别自己去拉主线代码手工打补丁。这个分支会跟随 OpenHarmony SDK 的版本做验证遇到问题也能找到对应的 issue。在 pubspec.yaml 里Flutter SDK 约束写成sdk: ^3.19.0同时确认environment: sdk: 3.3.0 4.0.0。简单说能用系统维护的分支就不要自己折腾版本对齐能省掉 80% 的环境类问题。2.2 初始化与运行命令速查创建一个支持 OpenHarmony 的 Flutter 工程和创建标准 Flutter 工程的命令差不多多一个 ohos 平台的配置。基本流程是这样# 拉取适配版 Flutter SDK路径按自己机器调整 git clone https://gitee.com/openharmony-sig/flutter_flutter.git -b OpenHarmony-3.19-release export PATH$PWD/flutter_flutter/bin:$PATH # 创建工程 flutter create --platforms ohos waste_guide_app cd waste_guide_app # 查看可用设备 hdc list targets # 直接运行到 OpenHarmony 设备 flutter run -d ohos有一个细节容易踩坑flutter create时如果指定了--platforms ohos但本机 Flutter SDK 不是 OpenHarmony 适配版命令会直接报错。所以先确认flutter doctor里有没有识别出 ohos 工具链。运行命令用的是hdc而不是 Android 的adb这个底层工具的本质是一样的都是设备调试桥但 OpenHarmony 设备出于安全策略默认不开放 adb 端口别混用。我最初就是因为手滑敲了adb devices半天看不到设备换成hdc list targets一下就通了。2.3 三方库选型与国产化适配状态首页需要处理网络请求、本地缓存和图片加载。标准 Flutter 生态里这三个需求分别对应 dio、shared_preferences 和 cached_network_image。但 OpenHarmony 平台要额外确认这些库有没有对应的 ohos 适配版本。我的经验是优先查 OpenHarmony 三方库中心网址是ohpm.openharmony.cn里面维护了大量常用库的鸿蒙适配版本。dio 在 ohos 平台上有官方维护的分支直接用dio: ^5.4.01这种带 ohos 标记的版本即可shared_preferences 因为是官方插件flutter_flutter 适配分支里已经带了 ohos 实现可以直接用cached_network_image 这个库依赖flutter_cache_manager后者在 ohos 上有点兼容性问题所以我干脆首页暂时没让它上场图片选择本地资源为主。上线后再根据实际需要去适配。这个阶段的取舍逻辑很简单首页每一次网络或缓存调用都可能在 OpenHarmony 设备上触发平台通道的差异能少依赖一个就有多一分稳定性。等业务验证完了再把图片缓存这类优化补上不迟。3. 首页核心组件实现3.1 搜索区样式与跳转逻辑搜索区是首页第一屏的视觉焦点。我用一个满宽圆角容器来实现里面放 TextField右侧放一个“搜索”按钮。这个设计没有任何新意但它就是最稳妥的。TextFiled 本身需要处理焦点和键盘弹出用户点击输入框后我会把焦点留在首页还是直接跳转到一个独立搜索页面最终选了后者。原因是垃圾搜索的交互比较复杂用户输入“塑料”“塑料瓶”“矿泉水瓶”这种关键词时需要实时匹配物品别名库然后展示结果列表如果所有交互都堆在首页代码会非常混乱。独立搜索页不仅逻辑清晰还给后续的搜索历史和热门搜索词预留了位置。首页的输入框更多是一个入口用户点一下页面切换时自动聚焦键盘弹出体验顺滑。实现上我用了一个自定义的SearchEntrywidget没有直接用 TextField因为既然是入口没必要让用户真的在里面输入内容。点击后用Navigator.push打开搜索页搜索页再自主管理输入和结果。这样首页不持有键盘焦点避免了滚动时自动收起键盘的各种边界问题。3.2 分类宫格图标体系与复用坑分类速查区是一个 4 列 2 行的 GridView可回收、有害、厨余、其他四个主分类再补上“医药”“电池”“织物”“电子产品”四个细分入口。宫格图标是首页最容易出视觉问题的部分因为 App 需要支持不同尺寸的 OpenHarmony 设备图标在平板上要清晰在手机上不能太大。图标方案上我踩过一个坑Material Icons 字体包虽然能直接用但字体文件体积在 OpenHarmony 上打包后偏大而且部分图标在鸿蒙字体渲染环境下细节显示有点怪。后来我改用 SVG 资源和 PNG 位图混用核心图标用 SVG需要细腻渐变的效果用 PNG。Flutter 在 ohos 上对 SVG 的支持依赖 flutter_svg 的适配版本我用了加 ohos 标记的版本实测没有遇到问题。宫格的代码结构是这样的GridView.count( crossAxisCount: 4, shrinkWrap: true, physics: const NeverScrollableScrollPhysics(), children: categories.map((cat) { return _CategoryItem( key: ValueKey(cat.id), icon: cat.iconAsset, label: cat.label, color: cat.color, onTap: () openCategory(cat.id), ); }).toList(), );有两个细节值得说。一是shrinkWrap: true否则 GridView 嵌在 CustomScrollView 里会无限高度报错二是每个 item 要加key我一开始没加页面从搜索页返回首页时宫格偶发出现图标闪烁错位。排查下来发现是元素复用导致的图标资源加载竞态加上ValueKey之后问题消失。这种问题在 Android 上不一定会暴露OpenHarmony 的资源加载时序略有差异编码时按最保守的方式来就对了。3.3 卡片式文章列表数据驱动 UI热门误区文章的展示采用简单列表卡片。每张卡片包含标题、摘要、分类标签和一张小尺寸占位图。占位图设计成主题色块加白色文字因为首版没有可靠的文章封面资源与其等后端上线图片不如设计师直接给出色块方案既保证视觉统一又避免加载失败时出现破图。文章列表的数据结构也很直接每篇文章就是一个 model 对象包含id, title, summary, tag, coverColor。UI 层根据 model 渲染不需要复杂逻辑。列表使用SliverList.builder懒加载模式文章条数少时性能完全没问题。用一个_ArticleCard组件通过构造函数传入数据方便后续从网络接口拉取真实数据时保持 UI 层不动。3.4 每日技巧低频模块的轻量实现每日分类技巧放在页面底部是一个轻量小卡片每次进入首页根据当前日期展示一条内容。它不需要网络请求也不需要状态管理直接在 build 方法里根据DateTime.now()计算索引从预置的 tips 列表取一条即可。这个模块的代码量很小但能显著提升首页的信息层次。用户如果已经搜过垃圾、看过分类首页对他来说就没有新东西了这时候一条“小龙虾壳属于厨余垃圾但大棒骨属于其他垃圾”这类冷知识能让他觉得这个 App 还有内容可看。实现时要注意 tips 列表不能让用户产生“每天都一样”的感觉所以要按日期取模而不是固定展示第一条。4. 状态管理与数据加载4.1 首页状态容器的选型首页的数据加载可以做成最原始的StatefulWidget FutureBuilder但后期一旦加入网络刷新、下拉刷新、缓存过期逻辑FutureBuilder 就会显得越来越别扭。我这边用了 flutter_bloc 的 Cubit而不是完整的 Bloc。原因是首页状态只有三种加载中、加载成功、加载失败。用完整 Bloc 的 Event 驱动模型有点重Cubit 的emit模型已经能覆盖所有需求。Cubit 的代码长这样class HomeCubit extends CubitHomeState { HomeCubit(this._repository) : super(const HomeLoading()); final HomeRepository _repository; Futurevoid loadHomeData() async { emit(const HomeLoading()); try { final data await _repository.fetchHomeData(); emit(HomeLoaded(data)); } catch (e) { emit(HomeError(首页数据加载失败请稍后重试)); } } }Cubit 持有 Repository页面只负责监听状态并渲染逻辑和 UI 分离。用 Cubit 还有一个好处后续要加测试可以直接 mock Repository 层来测状态迁移不需要启动整个 App。4.2 Repository 层与本地优先策略数据加载走了 Repository 模式。HomeRepository这个类不关心数据到底是从本地还是网络来它只暴露一个fetchHomeData()方法内部决定数据源。首版实现是典型的本地优先App 启动时从 assets 目录读取一个预置 JSON 文件里面包含分类列表、别名映射、热门文章和每日技巧。JSON 文件小解析快不存在网络依赖首页能做到秒开。为什么本地优先因为垃圾分类的基础分类表是一个相对静态的数据一个月可能才更新一次分类说明根本没必要每次都从网络拉。如果哪天需要更新知识库只需要发布新版本时替换 assets 里的 JSON 即可。等到要做运营动态时再在 Repository 里加网络刷新逻辑用本地数据兜底。4.3 网络刷新与缓存策略即使首版本地优先我还是预留了一套网络刷新机制。在 Repository 里加了一个fetchHomeDataFromRemote()方法逻辑是请求远程 JSON请求成功解析后写入 shared_preferences 缓存同时更新内存数据请求失败直接读本地 assets JSON控制缓存有效期比如 7 天刷新一次。这套机制我不在首版启用因为远程服务器还没上线。但因为接口和数据结构在设计阶段就定好了等后端就绪时只需要在 Repository 里加一个开关不需要改页面代码。5. 问题排查与优化实录5.1 热重载失效的解决路径开发 OpenHarmony 上的 Flutter 页面最影响心情的就是热重载有时不生效控制台提示 connected但是 UI 纹丝不动。我排查后发现这往往是 Flutter engine 与设备的 VM service 端口信息没有同步导致的尤其是从 DevEco Studio 启动过一次原生工程后再用flutter run概率更高。我的处理经验是先把设备上的旧应用彻底停掉再用命令行重新运行hdc shell aa force-stop com.example.waste_guide_app flutter run -d ohos如果还不行就检查flutter run弹出的 VM Service 地址是不是设备能访问的地址有时候它绑定了本机回环地址设备侧根本连不上热重载自然失效。手动指定--vm-service-port可以缓解。总之一句话开发 OpenHarmony 页面时别把热重载当成必须可用的功能跑不起来就用全量重启实际影响没有想象中大。5.2 中文粗体与字体显示不一致首页标题和关键词用了粗体在 Android 上一切正常到了 OpenHarmony 真机上某些中文字体却看不出加粗效果。这是因为 OpenHarmony 系统默认字体 HarmonyOS Sans 在粗体字重上的映射不如思源黑体完整Dart 层设置的FontWeight.w700没有对应字重文件时渲染引擎降级为常规字重。解决方案是在全局 ThemeData 里配置ThemeData( fontFamily: HarmonyOS Sans, fontFamilyFallback: [PingFang SC, Microsoft YaHei], // 其余主题参数 )并且尽量不要依赖 fontWeight 之外的字重细节。如果某些标题确实需要强调除了调 weight还改用颜色或字号来区分层级。这个原则对 OpenHarmony 平台尤其重要因为系统默认字体对字重的支持范围没法用代码补全。5.3 宫格图标错位与图片加载抖动前面提过宫格加 ValueKey 避开复用竞态这里再展开说。OpenHarmony 上的资源加载和 Android 略有不同同一个 AssetImage 在 widget 重建时偶尔会触发多次解码如果多个 item 复用了同一个 Icon 资源可能出现短暂的白块或抖一下。我的处理有几个层次给每个 GridView item 设置key图标解码前先判断ImageProvider是否已缓存未缓存时用主题色占位对于常用的 8 个图标在页面 initState 阶段就主动预加载一遍。for (final icon in categoryIcons) { precacheImage(AssetImage(icon), context); }这三招下来宫格区基本稳定了。5.4 包体与启动体积优化首页本身代码量不大但 Flutter 打包到 OpenHarmony 后hap 包体积容易被字体资源和 Skia 库抬上去。用flutter build hap --analyze-size可以查看产物构成我这边分析下来Material Icons 字体占了不小的比重。优化的第一件事是开启tree shake icons在pubspec.yaml里配置flutter: uses-material-design: true # 配合 --tree-shake-icons 编译选项同时把首页用不到的一堆 Material 图标引用清理掉改用自定义 SVG 图标。效果比较明显hap 包少了大约 8 MB。对于工具型 App安装包体积直接影响转化值得花时间在这上面。6. 把首页做成可配置化后续扩展思路首页开发到这个阶段功能层面已经完整但架构层面我留了一个口子配置化。现在首页的模块顺序是写死的分类数据和文章列表也是固定的 JSON 结构。如果后续要做运营每次调整模块顺序都需要发版这显然不合理。我的扩展思路是给首页引入一个 JSON 配置协议服务端返回一份首页配置{ modules: [ { type: search, enabled: true }, { type: category_grid, columns: 4 }, { type: article_list, limit: 5 } ] }页面渲染时遍历 modules按 type 找到对应 widget 并渲染。这样运营调整首页只需要改后台配置App 端不用发版。虽然首版不会立刻实现但数据结构上我会按这个思路预留避免以后推倒重来。这也是首页这类高频页面的通用演进方向。除了配置化还应该考虑接入系统能力。OpenHarmony 上有一些桌面小组件能力把“今日分类”或“常见垃圾速查”放到桌面上用户可以不下拉通知栏直接看到信息。这对于工具类 App 是天然的加分项等首版稳定后完全可以作为一个独立特性去迭代。收尾几个实战中的体会真做完一遍首页最大的体会是 Flutter for OpenHarmony 的坑没有想象中多但也没有想象中少。页面本身的布局、状态管理、数据加载是标准的 Flutter 知识基本不需要为鸿蒙做额外适配这部分我可以比较放心大胆地教大家用常规思路写。真正的差异集中在几个位置工具链的对齐、三方包的选择、系统字体和资源加载的细节。如果刚开始接触建议先花半天时间把官方提供的 ohos 适配样例工程跑通再开自己的业务页面否则很容易在环境上消磨掉耐心。代码和资源文件我整理在项目的chapter3分支里目录结构和本篇文章基本一致感兴趣的同学可以直接拉下来对照看。下一篇我会讲搜索页和别名库的实现那里会涉及到 OpenHarmony 平台通道和本地 SQLite 的适配问题比首页更有挑战也更有意思。