这两年做跨平台开发绕不开一个词叫“生态适配”。最近我把一个公交地铁线路查询APP从纯移动端迁徙到鸿蒙生态上用的技术栈是Flutter。很多朋友一听“Flutter做鸿蒙”第一反应是会不会水土不服毕竟鸿蒙生态有自己的ArkTS和声明式UI但实际跑下来我的结论是只要你把工程结构理清楚、把平台通道的边界划明白Flutter完全能覆盖一套核心代码多端复用的诉求。这篇就完整聊聊这个APP的开发流程从环境准备、页面架构、线路查询能力到底层踩坑全部照着实操顺序来想自己复刻一条跑通的同学可以直接抄。1. 项目概述与整体设计思路1.1 为什么选Flutter而不选纯ArkTS原生先交代一下背景。这个APP的核心功能是输入起点和终点给出公交或地铁的换乘方案支持按线路编号查询也能查看站点详情和首末班时间。需求本身不算复杂但用户对响应速度和操作流畅度有要求。难点反而在开发效率上——我们团队人手有限同时要覆盖Android、iOS和鸿蒙三个平台如果每个端都写一套原生逻辑光维护成本就能压垮排期。选Flutter的最直接原因是它有一套自己的渲染引擎UI层不依赖系统原生控件。这意味着同样的Widget树在Android、iOS、OpenHarmony上都能保持一致的手感和观感。相比之下ArkTS虽然也是声明式开发但它的生态目前还是围绕鸿蒙自己转第三方库的丰富度和Flutter差了一个量级。做业务型APP很多功能要站在现成库的肩膀上比如网络请求、本地存储、地图SDK的对接Flutter这边有成熟的pub.dev生态而ArkTS还处在追赶阶段。当然这不代表Flutter没有学习成本。跨平台开发最容易翻车的就是“以为一套代码写完就万事大吉”实际你会碰到平台差异、权限差异、生命周期差异尤其是鸿蒙这种新系统很多API行为和Android不完全一致所以设计阶段就要把平台适配层抽出来。1.2 功能边界与模块划分动手写代码之前我先整理了一份功能清单避免开发到一半需求膨胀。这个APP第一版只做四块线路查询输入线路编号比如“320路”“地铁4号线”展示线路走向、站点顺序、运行时间。公交地铁换乘输入起点终点算出最优换乘方案带步行距离和预计耗时。站点详情点某个站点展示经过该站的所有线路以及站点周边的关键信息。出行收藏用户收藏常用线路或站点下次打开不用重复搜索。这四块功能覆盖了“查线路”类APP的绝大多数使用场景。再往后迭代可以加实时公交、到站预测但第一版先不做原因是这两个功能依赖第三方数据源且需要设备持续上报位置功耗和稳定性都要重新设计。我的习惯是第一版先把骨架打牢把用户高频操作做顺后续再往里面塞增量功能。模块划分上我分了四层UI层、状态管理层、数据服务层、平台能力层。UI层只管渲染和用户交互状态管理用Provider负责页面间的数据同步数据服务层统一处理API请求和本地缓存平台能力层封装定位、地图、权限请求这些系统能力每个平台单独适配。lib/ ├── models/ # 数据模型线路、站点、方案 ├── services/ # API请求、缓存、数据解析 ├── providers/ # 状态管理 ├── pages/ # 页面首页、线路详情、换乘页 ├── widgets/ # 通用组件搜索框、线路卡片等 ├── platform/ # 平台适配层 └── main.dart # 入口2. 开发环境搭建与工程初始化2.1 Flutter鸿蒙开发环境配置细节搭建环境是整个项目里最容易被低估的一步。Flutter要跑鸿蒙不是装个SDK就行你需要配置OpenHarmony SDK、DevEco Studio还要让Flutter工具链识别到鸿蒙平台。以我实际操作的顺序来说先装好Flutter稳定版建议3.13及以上再把OpenHarmony SDK下载解压配置环境变量时注意要把OHOS_SDK_HOME指到SDK的根目录。很多人卡在“Flutter doctor不识别鸿蒙”这是因为还需要在Flutter工程里额外启用鸿蒙的Platform Toolchain这通常是官方社区维护的特定分支或额外的命令行工具包。配置完成后flutter doctor会多出一个“OpenHarmony”条目状态显示正常才算环境就绪。这里有个细节容易被忽略DevEco Studio自带的Node和命令行工具和Flutter命令行工具之间有一个版本配合问题。如果你之前电脑上已经装过Node建议统一用DevEco Studio内置的版本用hvigor命令做构建时不会出现版本冲突。我一开始没注意结果命令行和IDE反复出现版本不匹配的报错排查了整整一个下午。提示鸿蒙开发的环境变量配置后一定要重启终端或者重新加载配置文件很多奇怪的问题都出在环境变量没生效上。2.2 工程初始化与依赖管理环境就绪后创建Flutter工程这一步也有讲究。标准命令是flutter create bus_route_app创建完成后再往工程里添加鸿蒙平台的适配目录。这里需要注意不能直接用flutter run跑鸿蒙设备需要借助配套的鸿蒙构建脚本常见做法是生成一个entry模块让Flutter产物以SDK的方式集成进去。依赖方面我第一版用到的核心库就四个provider状态管理没有引入更重的bloc或riverpod保持简单。dio网络请求拦截器做日志和token处理很方便。shared_preferences轻量本地存储用来存搜索历史和收藏。connectivity_plus监听网络状态变化配合缓存做离线兜底。地图SDK的选择上公共数据接口我用的是高德地图的Web服务APIFlutter端真正需要的地图SDK在鸿蒙上还不成熟所以我没有直接集成原生地图而是接了一个WebView方案让地图页面通过H5方式承载。这个取舍在后面“地图交互”部分会详细说。依赖管理有个实践心得所有依赖版本号写死到pubspec里不要用^符号放任小版本浮动。跨平台项目最怕的就是“在我电脑上能跑、到别人那崩了”版本锁死能让整个团队的构建环境强制一致。3. 页面框架与状态管理方案3.1 底部导航与页面骨架搭建APP的整体结构是经典的底部三Tab首页查询入口、收藏、我的。打开APP直接落在首页顶部是搜索框下面展示热门线路和常用站点。底部导航我用了IndexedStack而不是BottomNavigationBar配合PageView原因是IndexedStack能把三个页面的状态一次性保留切换Tab不会触发重新加载。比如用户输入了半截线路编号切到收藏再切回来输入内容还在。这个体验细节是PageView做不到的用IndexedStack代价是三个页面会同时驻留内存但这个APP页面不重内存开销可以接受。页面骨架搭好之后我统一做了无网状态、加载中状态、空数据状态三种兜底UI。很多AP
Flutter跨平台开发鸿蒙生态APP实战：公交线路查询迁移指南
这两年做跨平台开发绕不开一个词叫“生态适配”。最近我把一个公交地铁线路查询APP从纯移动端迁徙到鸿蒙生态上用的技术栈是Flutter。很多朋友一听“Flutter做鸿蒙”第一反应是会不会水土不服毕竟鸿蒙生态有自己的ArkTS和声明式UI但实际跑下来我的结论是只要你把工程结构理清楚、把平台通道的边界划明白Flutter完全能覆盖一套核心代码多端复用的诉求。这篇就完整聊聊这个APP的开发流程从环境准备、页面架构、线路查询能力到底层踩坑全部照着实操顺序来想自己复刻一条跑通的同学可以直接抄。1. 项目概述与整体设计思路1.1 为什么选Flutter而不选纯ArkTS原生先交代一下背景。这个APP的核心功能是输入起点和终点给出公交或地铁的换乘方案支持按线路编号查询也能查看站点详情和首末班时间。需求本身不算复杂但用户对响应速度和操作流畅度有要求。难点反而在开发效率上——我们团队人手有限同时要覆盖Android、iOS和鸿蒙三个平台如果每个端都写一套原生逻辑光维护成本就能压垮排期。选Flutter的最直接原因是它有一套自己的渲染引擎UI层不依赖系统原生控件。这意味着同样的Widget树在Android、iOS、OpenHarmony上都能保持一致的手感和观感。相比之下ArkTS虽然也是声明式开发但它的生态目前还是围绕鸿蒙自己转第三方库的丰富度和Flutter差了一个量级。做业务型APP很多功能要站在现成库的肩膀上比如网络请求、本地存储、地图SDK的对接Flutter这边有成熟的pub.dev生态而ArkTS还处在追赶阶段。当然这不代表Flutter没有学习成本。跨平台开发最容易翻车的就是“以为一套代码写完就万事大吉”实际你会碰到平台差异、权限差异、生命周期差异尤其是鸿蒙这种新系统很多API行为和Android不完全一致所以设计阶段就要把平台适配层抽出来。1.2 功能边界与模块划分动手写代码之前我先整理了一份功能清单避免开发到一半需求膨胀。这个APP第一版只做四块线路查询输入线路编号比如“320路”“地铁4号线”展示线路走向、站点顺序、运行时间。公交地铁换乘输入起点终点算出最优换乘方案带步行距离和预计耗时。站点详情点某个站点展示经过该站的所有线路以及站点周边的关键信息。出行收藏用户收藏常用线路或站点下次打开不用重复搜索。这四块功能覆盖了“查线路”类APP的绝大多数使用场景。再往后迭代可以加实时公交、到站预测但第一版先不做原因是这两个功能依赖第三方数据源且需要设备持续上报位置功耗和稳定性都要重新设计。我的习惯是第一版先把骨架打牢把用户高频操作做顺后续再往里面塞增量功能。模块划分上我分了四层UI层、状态管理层、数据服务层、平台能力层。UI层只管渲染和用户交互状态管理用Provider负责页面间的数据同步数据服务层统一处理API请求和本地缓存平台能力层封装定位、地图、权限请求这些系统能力每个平台单独适配。lib/ ├── models/ # 数据模型线路、站点、方案 ├── services/ # API请求、缓存、数据解析 ├── providers/ # 状态管理 ├── pages/ # 页面首页、线路详情、换乘页 ├── widgets/ # 通用组件搜索框、线路卡片等 ├── platform/ # 平台适配层 └── main.dart # 入口2. 开发环境搭建与工程初始化2.1 Flutter鸿蒙开发环境配置细节搭建环境是整个项目里最容易被低估的一步。Flutter要跑鸿蒙不是装个SDK就行你需要配置OpenHarmony SDK、DevEco Studio还要让Flutter工具链识别到鸿蒙平台。以我实际操作的顺序来说先装好Flutter稳定版建议3.13及以上再把OpenHarmony SDK下载解压配置环境变量时注意要把OHOS_SDK_HOME指到SDK的根目录。很多人卡在“Flutter doctor不识别鸿蒙”这是因为还需要在Flutter工程里额外启用鸿蒙的Platform Toolchain这通常是官方社区维护的特定分支或额外的命令行工具包。配置完成后flutter doctor会多出一个“OpenHarmony”条目状态显示正常才算环境就绪。这里有个细节容易被忽略DevEco Studio自带的Node和命令行工具和Flutter命令行工具之间有一个版本配合问题。如果你之前电脑上已经装过Node建议统一用DevEco Studio内置的版本用hvigor命令做构建时不会出现版本冲突。我一开始没注意结果命令行和IDE反复出现版本不匹配的报错排查了整整一个下午。提示鸿蒙开发的环境变量配置后一定要重启终端或者重新加载配置文件很多奇怪的问题都出在环境变量没生效上。2.2 工程初始化与依赖管理环境就绪后创建Flutter工程这一步也有讲究。标准命令是flutter create bus_route_app创建完成后再往工程里添加鸿蒙平台的适配目录。这里需要注意不能直接用flutter run跑鸿蒙设备需要借助配套的鸿蒙构建脚本常见做法是生成一个entry模块让Flutter产物以SDK的方式集成进去。依赖方面我第一版用到的核心库就四个provider状态管理没有引入更重的bloc或riverpod保持简单。dio网络请求拦截器做日志和token处理很方便。shared_preferences轻量本地存储用来存搜索历史和收藏。connectivity_plus监听网络状态变化配合缓存做离线兜底。地图SDK的选择上公共数据接口我用的是高德地图的Web服务APIFlutter端真正需要的地图SDK在鸿蒙上还不成熟所以我没有直接集成原生地图而是接了一个WebView方案让地图页面通过H5方式承载。这个取舍在后面“地图交互”部分会详细说。依赖管理有个实践心得所有依赖版本号写死到pubspec里不要用^符号放任小版本浮动。跨平台项目最怕的就是“在我电脑上能跑、到别人那崩了”版本锁死能让整个团队的构建环境强制一致。3. 页面框架与状态管理方案3.1 底部导航与页面骨架搭建APP的整体结构是经典的底部三Tab首页查询入口、收藏、我的。打开APP直接落在首页顶部是搜索框下面展示热门线路和常用站点。底部导航我用了IndexedStack而不是BottomNavigationBar配合PageView原因是IndexedStack能把三个页面的状态一次性保留切换Tab不会触发重新加载。比如用户输入了半截线路编号切到收藏再切回来输入内容还在。这个体验细节是PageView做不到的用IndexedStack代价是三个页面会同时驻留内存但这个APP页面不重内存开销可以接受。页面骨架搭好之后我统一做了无网状态、加载中状态、空数据状态三种兜底UI。很多AP