Flutter项目快速迁移为HarmonyOS应用

介绍

本文主要为现有flutter应用提供一个快速上架鸿蒙的方案，使用的仓库与本人无关，仅供技术参考，欢迎大家提出意见建议，一起完善鸿蒙生态

在展开和选择适配HarmonyOS的Flutter框架时，可以选用以下两个仓库：

1. OpenHarmony-SIG版本

   • Flutter版本：3.7.12
   • Dart版本：2.19.6
   • 仓库地址：https://gitee.com/openharmony-sig/flutter_flutter/

2. 第三方版本

   • Flutter版本：3.22.0
   • Dart版本：3.4.0
   • 仓库地址：https://gitee.com/harmonycommando_flutter/flutter

重要注意点

• 适配HarmonyOS的Flutter框架只支持构建ARM64架构的应用，即无法在x86环境的模拟器上进行调试，仅支持M系列芯片ARM架构的Mac上模拟器调试。
• 也可以使用真机调试，或打包正式包后在华为云真机上进行测试。
• 为避免与普通Flutter版本出现冲突，建议在不同系统或设备上安装和配置，或通过虚拟机部署。

环境配置方法

1. 安装DevEco Studio和Java JDK

• 建议的IDE：
  • Flutter使用VSCode编写
  • 原生使用DevEco Studio

2. 克隆Flutter仓库代码

可从两个仓库中选择一个克隆，建议根据自己项目的情况，如果本身使用Dart3.x版本构建的，建议使用第二个：

git clone https://gitee.com/openharmony-sig/flutter_flutter.git

或

git clone https://gitee.com/harmonycommando_flutter/flutter.git

3. 配置环境变量

按照下列配置环境变量：

# 设置Java路径
JAVA_HOME = <JAVA_HOME Path>
PATH=%JAVA_HOME%\bin

# 设置DevEco路径
TOOL_HOME = <DevEco Studio Path>
DEVECO_SDK_HOME=%TOOL_HOME%\sdk
PATH=%TOOL_HOME%\tools\ohpm\bin
PATH=%TOOL_HOME%\tools\hvigor\bin
PATH=%TOOL_HOME%\tools\node\bin

# 设置Flutter路径
PUB_CACHE=<指定缓存目录>
PATH=<flutter_flutter path>/bin:$PATH
PUB_HOSTED_URL=https://pub.flutter-io.cn
FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

4. 格式化配置测试

运行以下指令，确保环境变量配置正确：

flutter doctor -v

确保Flutter与OpenHarmony监查结果均为OK。

迁移现有Flutter应用至HarmonyOS

1. 创建HarmonyOS工程

通过以下指令创建工程：

flutter create --platforms ohos <projectName>

2. 拷贝原有工程文件

将原有工程中的lib和资源文件拷贝至HarmonyOS项目。

3. 配置pubspec.yaml

配置assets，例如：

flutter:
  assets:
    - assets/

4. 检查第三方库适配情况

在pubspec.yaml中配置适配的仓库：

• 纯Dart库：无需更换
• 原生库：适配计划链接，可根据自己使用的库，在适配计划中查看已适配的版本并替换
• 例：使用shared_preferences：

shared_preferences:
  git:
    url: "https://gitee.com/openharmony-sig/flutter_packages.git"
    path: "packages/shared_preferences/shared_preferences"

• 如果是没有适配的库，需要自己手动编写channel，需要有一定的ArkTS原生编码能力。后续我也会发布相关文章针对此部分进一步讲解。

5. 下载依赖和修正代码

使用以下指令：

flutter pub get

修正或删除不支持的库的代码。

6. 配置项目信息

使用DevEco打开flutter项目下的ohos子项目，在项目设置中，配置由AppGallery Connect生成的证书和Profile，并在app.json5中配置包名、应用名称和图标。

7. 构建应用包

使用以下指令：

# 构建hap包
flutter build hap –release

# 构建app包
flutter build app –release

app构建后生成所在目录为：flutter根目录/ohos/build/output/default
会生成hap以及签名和未签名的app包

8. 调试真机应用

调用真机：

# 检测设备
flutter devices

# 调试
flutter run --debug -d <deviceId>

9. 关于原生端未适配库问题

至此Flutter应用就完成了对原生鸿蒙的适配，关于未适配的原生库和自定义原生交互的方式将在后续的帖子再与大家展开讨论