开源鸿蒙跨平台训练营DAY14：Flutter for OpenHarmony复盘梳理第二阶段掌握的知识要点

本文记录了蘑菇图鉴APP的开发过程，主要完成了基础架构搭建和功能迭代升级。通过BottomNavigationBar实现底部导航，使用Provider+shared_preferences解决了跨页面状态同步与持久化问题。开发中克服了页面状态保留、数据序列化等难点，实现了收藏功能全链路落地。文章详细介绍了各阶段实现步骤，包括数据交互、UI适配和状态管理方案，并总结了遇到的问题及解决方法。后续计划完

tyty0214

152人浏览 · 2026-02-08 00:13:18

tyty0214 · 2026-02-08 00:13:18 发布

##欢迎加入开源鸿蒙跨平台社区

https://openharmonycrossplatform.csdn.net

#我的笔记：

【学习笔记DAY8~10】
文章链接：https://blog.csdn.net/tyty0214/article/details/157825622?fromshare=blogdetail&sharetype=blogdetail&sharerId=157825622&sharerefer=PC&sharesource=tyty0214&sharefrom=from_link

【学习笔记DAY11~12】
文章链接：https://blog.csdn.net/tyty0214/article/details/157831127?fromshare=blogdetail&sharetype=blogdetail&sharerId=157831127&sharerefer=PC&sharesource=tyty0214&sharefrom=from_link

【学习笔记DAY13】
文章链接：https://blog.csdn.net/tyty0214/article/details/157836147?fromshare=blogdetail&sharetype=blogdetail&sharerId=157836147&sharerefer=PC&sharesource=tyty0214&sharefrom=from_link

#一、核心实现功能

基础架构与导航体系：搭建首页、蘑菇列表页、我的收藏页（原我的中心页迭代）、设置页 4 大核心页面，通过BottomNavigationBar实现底部选项卡导航，结合IndexedStack和AutomaticKeepAliveClientMixin实现页面状态保留，切换选项卡时不丢失输入内容、滚动位置等状态。
数据交互与展示能力：集成Dio实现蘑菇数据的 API 请求、分页加载、下拉刷新与上拉加载更多；首页划分应用简介、分类入口（全部 / 可食用 / 有毒 / 剧毒）、热门推荐模块，列表页支持分类筛选逻辑，统一处理加载中、失败、空数据等状态，适配鸿蒙设备竖屏显示与虚拟导航栏避让。
收藏功能全链路落地：从初期全局变量collectList的简单联动，迭代为基于Provider的全局状态管理 +shared_preferences本地持久化方案，实现多页面收藏状态实时同步（点击即变色）、我的收藏页动态更新（无需刷新）、重启 APP 数据不丢失、跨页面状态一致四大核心目标。
基础优化与适配：初步实现主题切换功能框架，优化页面交互反馈；解决 API 请求、设备适配、状态管理等多类问题，完成三次 Git 代码提交与版本迭代，保障功能稳定性。

#二、核心实现步骤

##阶段 1：基础架构与导航搭建（DAY8~10）

页面规划与创建：在lib/pages目录下新建 4 个核心页面文件，均继承StatefulWidget，明确各页面职责。
底部选项卡实现：在main.dart中定义MainTabPage，通过_pages列表聚合所有页面，_selectedIndex控制选中状态，配置BottomNavigationBar的图标、标签与切换事件。
状态保留配置：每个页面的State类混入AutomaticKeepAliveClientMixin，重写wantKeepAlive返回true，并在build方法中调用super.build(context)。
初步功能联动：定义全局collectList，实现首页热门推荐收藏按钮的添加 / 移除逻辑，我的中心页渲染收藏列表并提供删除、清空功能。
数据加载与适配：集成Dio请求 API 数据，处理多状态展示；借助pull_to_refresh实现下拉刷新与上拉加载；配置鸿蒙设备竖屏锁定与安全区域适配。

##阶段 2：收藏功能升级（跨页同步 + 持久化）

依赖配置：在pubspec.yaml中添加provider（状态管理）、shared_preferences（本地存储）等依赖，执行flutter pub get安装。
数据模型标准化：完善MushroomModel，补充id等核心字段，重写==和hashCode按id判断唯一性，新增toJson()、fromJson()、fromLocalJson()实现 JSON 序列化 / 反序列化。
全局状态封装：创建CollectProvider，实现init()（启动加载本地数据）、toggleCollect()（收藏切换 + 存储 + 状态通知）、refreshCollect()（手动刷新）三大核心方法。
全局状态注入：改造main.dart，初始化CollectProvider并await init()，通过MultiProvider全局注册状态，确保所有页面处于状态作用域内。
多页面集成：各页面用Consumer<CollectProvider>包裹组件，绑定收藏按钮点击事件，动态切换图标颜色；我的收藏页复用toggleCollect()实现删除，支持下拉刷新。
代码版本管理：执行git pull origin main拉取最新代码，git add .添加修改文件，git commit -m "feat: 实现收藏跨页同步+持久化"提交，git push origin main推送到远程仓库，处理可能的代码冲突。

#三、重难点与问题解决

##（一）核心重难点突破

页面状态保留失效：
- 问题本质：未正确配置AutomaticKeepAliveClientMixin，导致切换选项卡后页面重建。
- 解决方案：确保每个页面都混入该类、重写wantKeepAlive返回true，且build方法中调用super.build(context)。
跨页面状态同步不及时：
- 问题本质：初期全局变量缺乏状态通知机制，修改后页面无法感知。
- 解决方案：采用Provider实现全局单一数据源，通过notifyListeners()触发实时刷新，所有页面通过Consumer监听状态变化。
本地存储序列化失败：
- 问题本质：模型字段空值未处理、JSON 格式不规范，导致重启 APP 后数据丢失。
- 解决方案：模型解析时设置空值默认值，使用标准jsonEncode/jsonDecode，添加异常捕获机制，避免解析失败。
Provider 作用域失效：
- 问题本质：状态未全局注册，或页面嵌套导致状态隔离。
- 解决方案：用MultiProvider包裹根MaterialApp，仅保留一个MaterialApp，所有页面通过MainTabBar聚合。

##（二）典型问题与解决方法

问题	表现形式	解决方法
组件参数错误	Icon 误用 fontSize，Text 误用 fontSize	Icon 改用 size 参数，Text 通过 TextStyle 设置字体大小
虚拟机无法访问本地 API	接口请求失败	将localhost改为电脑局域网 IP，确保设备与电脑网络互通
收藏按钮不变色	点击无反馈，无日志	检查`Consumer`包裹、`notifyListeners()`调用、`id`判断逻辑
我的收藏页空白	收藏后无数据显示	验证`init()`异步执行、存储键名一致、字段映射无拼写错误
重启 APP 收藏状态丢失	重启后收藏列表为空	确认`prefs.setString()`调用、JSON 格式正确、清除旧缓存测试
主题切换报错	提示`darkMode isn't defined`	统一字段名为`themeMode`、传入`ThemeMode`参数、删除无用导入
列表滑动状态错乱	滑动后图标显示错误	基于全局状态判断、验证模型重写、不缓存状态

#DAY14总结：

本次蘑菇图鉴 APP 开发历经基础架构搭建、功能迭代升级两个核心阶段，从初期的页面导航与简单数据联动，逐步完善为具备跨页同步、本地持久化的完整收藏功能，实现了 “导航稳定、数据互通、状态一致、体验流畅” 的核心目标。

开发过程中，核心突破点在于通过Provider+shared_preferences解决了跨页面状态同步与持久化的核心痛点，同时通过规范的模型设计、状态管理与设备适配，保障了功能的稳定性与兼容性。遇到的问题多集中在组件使用规范、状态作用域、数据序列化等基础层面，通过查阅文档、调试日志与逻辑优化逐一解决。

后续需重点推进主题切换、分类筛选等未完成功能的落地，同时从性能、兼容性、代码维护性三个维度进行优化，进一步提升 APP 的用户体验与可扩展性。整体开发过程遵循 “从基础到复杂、从功能到体验” 的迭代思路，为后续跨平台应用开发积累了宝贵的实践经验。