一、背景介绍

         HarmonyOS NEXT作为鸿蒙抛弃Linux内核及安卓开放源代码项目（AOSP）等代码的首个大版本，与10月8日正式开启公测，已有15000+鸿蒙原生应用和元服务上架。而Flutter作为市场主流的跨平台应用去适配兼容鸿蒙已成为大势所趋。由于Google官方尚未将OpenHarmony（鸿蒙）纳入Flutter的原生支持平台计，目前可用的“鸿蒙版Flutter”是由OpenHarmony开源社区的特殊兴趣小组（SIG）及广大开发者基于已有flutter版本通过鸿蒙原生提供的平台能力，重新实现了一遍Flutter嵌入层，提供了一套支持openharmony平台的Flutter SDK ，目前稳定版本支持Flutter 3.7.12-ohos 1.1.5 Release、Flutter 3.22.0-ohos 1.0.5 Release、Flutter 3.27.4-ohos 1.0.0 Release、只需要下载对应版本的Flutter SDK 即可支持IDE或者终端使用Flutter Tools指令编译和构建OpenHarmony应用程序。

二、适配方案

        Flutter 从上到下可以分为三层：框架层、引擎层和嵌入层 最上层为框架层，使用 Dart 语言开发，面向 Flutter 业务的开发者 中间层为引擎层，使用 C/C++ 开发，实现了 Flutter 的渲染管线和 Dart 运行时等基础能力； Embedder(嵌入层), Flutter 最终渲染、交互是要依赖其所在平台的操作系统API，嵌入层主要是将 Flutter 引擎 “安装”到特定平台上。Flutter 代码可以通过嵌入层，以模块方式集成到现有的应用中，也可以作为应用的主体。

        为了实现Flutter在鸿蒙系统上的原生支持，需要对Flutter的嵌入层进行适配。这主要包括以下几个方面的工作：

渲染流程的适配： Flutter的图像渲染流程涉及设备发起垂直同步（VSync）信号、UI线程的渲染管线（Animate/Build/Layout/Paint）、Raster线程的组合和栅格化，以及最终通过OpenGL或Vulkan将图像上屏。 在鸿蒙系统上，需要监听设备的VSync信号并通知Flutter引擎，同时构建平台容器，为Flutter引擎的图形渲染提供用于上屏的窗口对象。

VSync信号的监听及传递： NativeVsync模块用来获取系统VSync信号，提供了OH_NativeVSync实例的创建、销毁以及设置VSync回调函数的能力，VSync信号到来时会调用已设置的VSync回调函数。

平台容器的构建： 鸿蒙系统的UI框架提供了很多常用视图组件（Component），如按钮、文字、图片、列表等。但为了实现Flutter的渲染，需要抛开这些上层组件，获得直接绘制的能力。 鸿蒙提供了SurfaceProvider类，它管理的Surface对象可以用于视频解码后的展示。这可以被用来为Flutter引擎提供用于渲染的绘图表面。

三、环境搭建与工程调试

本文以windows环境为示例，展示环境配置相关内容。

1、下载并安装OpenHarmony最新DevEco Studio开发工具，及其依赖环境
1.1 官方下载地址
OpenHarmony开发套件官方下载地址https://developer.huawei.com/consumer/cn/download/

2、下载支持鸿蒙的flutter sdk

2.1、master分支相对稳定，dev不断在更新相比master拥有更多功能，下面是两个下载路径

git clone -b dev git@gitee.com:openharmony-sig/flutter_flutter.git 

git clone https://gitcode.com/openharmony-tpc/flutter_flutter.git
git checkout -b dev origin/dev

完成后在环境变量用户变量path中添加对应下载路径D:\ohosflutter\flutter_flutter\bin 

配置flutter 国内镜像 在用户变量 新建flutter的国内镜像的变量名和变量值

2.2、下载FlutterEngine构建产物（非必选项，不指定--local engine，默认是用云端的引擎） Flutter工程构建依赖ohos_debug_unopt_arm64与ohos_release_arm64 FlutterTools指令运行参数中添加--local-engine字段来指定下载的engine：--local-engine=src/out/<engine产物目录\> ， 若不使用--local-engine来指定engine，默认使用云端最新版engine。 使用示例： flutter build hap [--local-engine=/Users/admin/Documents/flutter_engine/src/out/ohos_debug_unopt_arm64] 下载编译产物（https://docs.qq.com/sheet/DUnljRVBYUWZKZEtF?tab=BB08J2） engine本地路径必须带上src/out目录; 解压后，存放到一个目录(engine本地路径必须需带上src/out目录)： 如：/Users/admin/Documents/flutter_engine/src/out

3、下载jdk17并配置环境变量

JAVA_HOME = <JAVA_HOME path>  PATH=%JAVA_HOME%\bin

4、配置HarmonyOS SDK和环境变量

4.1、我的电脑-属性-高级系统设置-环境变量-用户变量  点击新建 -输入对应的变量名和变量值-注意路径不要用空格

4.2、在对应的Deveco_Stdio安装路径下，环境变量中的用户变量path变量中追加 Node，ophm ，hvigor，hdc指令(可选)的路径

5、验证是否正确配置 打开cmd命令行窗口，输入flutter doctor –v 运行后，正确配置效果如图。确保flutter和HarmonyOS配置成功

6、创建工程

方式一 该方式只创建了ohos平台

        flutter create --platforms ohos <projectName> 创建工程

方式二 该方式创建了移动端和桌面端的平台

        flutter create  <projectName>

7、编译hap包

进入工程根目录编译hap包（可选release,debug,profile三个版本）

flutter build hap –release

编译产物路径 ${projectName}/ohos/entry/build/default/outputs/default/entry-default-signed.hap

8、鸿蒙真机运行Flutter项目

方式一 ：安装应用 hdc install [-r|-s] src （ src为应用安装包的文件名，具体到全路径） hdc install D:\ohtest\flutter_ohos_demo\ohos\entry\build\default\outputs\default\entry-default-signed.hap

方式二： 使用DevEcoStudio 选择设备为真机，在此之前需要在手机打开开发者选项，连接到手机后，点击启动

四、鸿蒙原生工程集成flutter_module

1、如何在鸿蒙工程中引用flutter_module

1. 创建鸿蒙原生工程MyApplication
2. 创建 flutter子模块工程 flutter create -t module my_flutter_module
3.  编译生成 flutter_module.har cd my_flutter_module flutter build har --debug
4. 复制 EntryAbility.ets 和 Index.ets 到 MyApplication 中替换之前的文件

2、鸿蒙原生工程引用flutter_module 的两种方式

2.1、ohos工程引用 har 文件

1. 复制.ohos/har文件夹内容到鸿蒙项目根目录

2. 修改工程级别的oh-package.json5

3. 执行 ohpm install

4. 使用 Deveco Studio 配置 MyApplication 的签名，运行程序

2.2、ohos工程直接引用 flutter_module 源码

 1. 复制 flutter_module 源码 和 flutter相关文件

2. 修改 MyApplication/build-profile.json5

3. 修改 MyApplication/oh-package.json5

五、Flutter与鸿蒙数据交互的三种方式

1、MethodChannel 特性：支持数据双向传递，有返回值。 通信机制：通过MethodChannel，Flutter可以发送方法调用请求到Native端，Native端处理完请求后，可以返回结果给Flutter

1.1、在flutter端定义MethodChannel 通道 final _platform = const MethodChannel('samples.flutter.dev/battery')

1.2、Harmonyos 端定义同一名称的MethodChannel，并通过onMethodCall 去监听flutter端传来的方法名和数据，处理后result.success(level)回调数据给flutter端

2、EventChannel 特性：单向通信方式，从Native向Flutter发送数据，Flutter无法返回数据给Native 通信机制：Native端通过EventChannel向Flutter发送数据流，Flutter端接收并处理这些数据。 

2.1、在flutter端定义EventChannel 通道 final _eventChannel = const EventChannel(‘samples.flutter.dev/event_channel’); 创建流数据监听

2.2、在Harmonyos 端定义同一名称的EventChannel，调用setStreamHandler方法，在调用onListen 通过EventSink 的success 方法，传递数据流给flutter端

3、BasicMessageChannel 特性：用于传递字符串和半结构化的信息（如JSON），支持数据双向传递，有返回值。 通信机制：通过BasicMessageChannel，Native和Flutter可以相互发送和接收消息，并可以回复消息。

3.1、在flutter端定义BasicMessageChannel 通道 final _basicChannel = const BasicMessageChannel("samples.flutter.dev/basic_channel",StandardMessageCodec());

3.2、Harmonyos 端定义同一名称的BasicMessageChannel，调用setMessageHandler方法，在onMessage方法回调中接收flutter端传来的message数据，通过relpy 回调数据给flutter端