引言
本文结合实际代码讲述如何改造现有 Flutter 项目,适配鸿蒙平台。
通过模块化,鸿蒙壳工程,结合 FVM 管理多版本 Flutter SDK,保持原 Flutter 代码纯净,最小化修改,完成鸿蒙化的适配示例。
准备工作
1. 安装 FVM
安装 FVM,更多安装方式参考 fvm 官方文档
curl -fsSL https://fvm.app/install.sh | bash
2.使用 FVM 安装 Flutter SDK
分别安装官方的Flutter版本(我这里用的比较旧,版本为 3.3.10),以及鸿蒙社区的 3.22.0 版本
提示:安装鸿蒙定制版本的 Flutter SDK,建议使用 git clone
命令行(我一开始直接 download zip,出现下载不全的现象)
现有 Flutter 工程架构
完成准备工作后,调整现有 Flutter 的工程结构,简化后大致如下:
.
├── apps #该目录用于存放各端应用壳工程 (示例如下)
│ ├── app #对应Android、IOS、Windows等原Flutter框架支持的平台
│ └── app_ohos #对应HarmonyOS平台
│
├── modules #该目录用于存放各业务模块 (示例如下)
│ ├── home_module #首页
│ ├── trade_module #交易结算
│ └── memeber_module #会员管理
│
├── common # 该目录用于存放公共库 (示例如下)
│ ├── network
│ ├── tools
│ └── widgets
│
└── README.md
如上所示, /apps/app
为我们现有的 Flutter 壳工程目录,modules
及common
目录是我们项目开发中封装的业务模块库及公共组件库。(当然,不一定要放在同一目录下,这里也为方便大家观察学习)
壳工程解耦,将统一布局
及三方库依赖
放在下层模块中
例如,在home_module
模块中添加外部三方库,封装后再提供给壳工程使用。
在 /modules/home_module/pubspec.yaml
中添加几个典型的三方库作为示例
name: home_module
description: home_module
version: 0.0.1
homepage:
environment:
sdk: '>=2.18.6 <3.0.0'
flutter: ">=1.17.0"
dependencies:
flutter:
sdk: flutter
flutter_bloc: ^7.3.0 // 演示纯 Dart 实现的三方状态管理库
dio: ^4.0.6 // 演示纯 Dart 实现的三方网络库
fluttertoast: 8.1.2 // 演示依赖系统底层实现的三方库(需要鸿蒙化适配)
封装组件 HomePage
提供给壳工程,用于显示主页
App 壳工程
在 /apps/app/pubspec.yaml
中对各个业务模块及公共组件库进行依赖项添加
dependencies:
flutter:
sdk: flutter
cupertino_icons: ^1.0.6
home_module:
path: '../../module/home_module'
... 省略其他
通过依赖 home_module
显示封装的首页组件
点击运行,效果如下:
鸿蒙壳工程
首先,我们需要在 /apps
目录下创建一个鸿蒙壳工程
+ 第一步,使用 FVM 将 Flutter 版本切换到鸿蒙化的版本
fvm use custom_3.22.0
+ 第二步,进入 /apps
目录,使用命令行创建 app_ohos
项目
fvm flutter create --template app --platforms ohos --org com.rex.flutter app_ohos
+ 添加依赖项
dependencies:
flutter:
sdk: flutter
cupertino_icons: ^1.0.6
home_module:
path: '../../module/home_module'
... 省略其他
+ 三方库鸿蒙化适配
通过 dependency_overrides 来替换鸿蒙化的三方库,以组件内用到的 fluttertoast
为例
dependency_overrides:
fluttertoast:
git:
url: "https://gitee.com/openharmony-sig/flutter_fluttertoast.git"
ref: "master"
app_ohos/pubsec.yaml 中的 dependency_overrides, 仅添加需要鸿蒙化的三方库
如何判断三方库是否需要鸿蒙化,简而言之,如果三方库由纯 Dart 实现,则不需要单独适配,直接使用;如果三方库依赖系统底层实现,则需要鸿蒙化适配。
三方库的适配情况,可以查询 Gitee/Github,或者查阅表格 Flutter三方库适配计划
+ 运行调试
用 Deveco 打开apps/app_ohos/ohos 目录。
在 Deveco 左上角 打开 File -> Project Structure..., 点击 Siging Configs, 勾选 Automatically generate signature, 对鸿蒙项目签名。
在 ohos_app 目录下,使用 fvm flutter run,或者点击运行按钮,运行flutter项目。
PS1:注意添加应用权限
PS2:没有真机的同学可以使用模拟器运行
运行效果如下:
总结:
- 通过 FVM 管理多个 Flutter SDK 版本,仅在鸿蒙调测打包时,切换到 ohos-flutter SDK
- 通过 apps 壳工程,将鸿蒙化适配的代码,尽量在 app_ohos 项目中完成。通过 pub 包管理的
dependency_overrides
配置,逐个替换鸿蒙化的三方库 - Flutter 项目进行模块化、组件化、插件化拆分,职责分离,平台抽象,不同平台组合打包,有效解决平台不一致问题
DEMO 示例已上传: https://github.com/liyufengrex/flutter_ohos