Flutter应用如何快速适配HarmonyOS

原创 于 2025-12-18 16:23:38 发布 · 457 阅读 · 9 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#flutter #harmonyos #华为

Flutter应用如何快速适配HarmonyOS

本文原创发布在华为开发者联盟社区，欢迎前往与更多开发者进行互动。
更多相关问题可点击原帖进行交流：Flutter应用如何快速适配HarmonyOS 。

概述

当前已有适配了HarmonyOS的ohos Flutter SDK，当前已有众多Flutter应用基于此版本上架鸿蒙应用市场。

目前可使用的有3.7.12、3.22及3.27三个版本，3.32也已经在Beta中。

本文旨在介绍如何将Flutter应用快速适配HarmonyOS，包含以下几个方面：

整体方案

  1. 先选择确认要使用的HarmonyOS Flutter SDK的版本，然后下载配置好开发环境，在进行HarmonyOS Flutter应用开发时记得切换SDK，可以使用flutter doctor -v进行检查
  2. 确认架构选型，是使用Flutter App还是采用Flutter module混合开发，一般延用Android/IOS上的选型 
    • flutter app方式：可以在原先项目根目录执行命令flutter create --platforms ohos --t app ./，会自动创建HarmonyOS底座工程目录ohos，与ios和android目录并列
    • flutter module方式：参考在HarmonyOS上集成Flutter module，最终会将module打包成har包，供HarmonyOS工程引用，类比于Flutter module在Android上会被构建成AAR包，供APK集成。
  3. 三方库替换成鸿蒙化的版本，需采用Git依赖的方式
  4. 未适配的三方库一般替换成同类功能的库
  5. 自研的插件需要自行适配，可以在原先插件工程的根目录下执行命令flutter create --platforms ohos --t plugin ./，也会自动创建插件鸿蒙平台代码目录ohos，与android和ios并列
  6. 平台代码重写，例如原来在Android平台上开发的Java代码，适配时需要重写成ArkTS代码
  7. 打包验证，目前也有两种方案：
    • 一套代码，一套流水线：鸿蒙版Flutter SDK也可以编译打包支持Android/IOS平台运行的包（APK或ipa），使用方便，与普通版本完全一致
    • 一套代码，两套流水线：HarmonyOS和Android/ios分别采用不同的Flutter SDK编译构建，最大程度复用代码
  8. 测试与发布

版本选择

之前在Android/IOS上使用的Flutter版本可能与适配HarmonyOS的Flutter版本不同，这需要做版本的升级，当前有三个版本适配了HarmonyOS，分别对应社区Flutter SDK的：3.7.12、3.22.0和3.27.4

切换建议：

  • 升级前做好备份
  • 选择与当前版本差异最小的版本，逐步升级
  • 做好测试用例保护

Flutter版本升级
存量项目或历史版本需先调整至上述支持版本，按 “最小适配成本” 选择，由于小版本升级不会有破坏性改动，所以仅关注版本号前两位即可：

  • 当前版本 < 3.7 → 升级至 3.7.12
  • 3.7 < 当前版本 < 3.22 → 升级至 3.22.0
  • 3.22 < 当前版本 < 3.27 → 升级至 3.27.4
  • 当前版本 > 3.27 → 降级至 3.27.4

在升级Flutter时遇到的Dart错误，可以使用dart fix命令自动修复代码，大多数破坏性改动是支持自动修复的，具体可以参考Flutter官方提供的升级指导：

注意当升级跨多个版本时，需要关注这中间多个版本的破坏性改动

技术架构选型

Flutter开发App有2种模式：纯Flutter APP和混合开发。
纯Flutter APP和混合开发对比：

维度

纯 Flutter APP

混合开发

开发范围

全栈 Flutter，HarmonyOS仅作容器

部分Flutter + 主HarmonyOS工程

原生功能适配

较难（需通过通道调用）

便捷（原生模块直接调用）

开发 / 维护成本

低（单一技术栈）

高（多技术栈协作）

选型策略：

  • 全新项目，无存量代码：推荐选纯Flutter APP模式，从零开始用Flutter可最大化发挥 “一套代码跨多端” 的优势，避免混合开发的集成成本，迭代效率更高。
  • 已有成熟原生APP，新功能使用Flutter开发：仅需适配现有安卓ios代码为HarmonOS代码，原生开发更便捷，新业务需求集成Flutter代码，实现跨端开发。
  • 需深度利用平台特性：推荐使用混合开发，复杂原生功能通过原生代码实现更稳定，Flutter仅负责上层UI，避免通过Platform Channel频繁通信导致的性能损耗和调试复杂度。

工作量评估

适配过程中，工作量主要有以下几部分组成：

  • 三方库替换
    • Flutter Plugin中会涉及到平台代码，当适配HarmonyOS时，也需要对这些plugin也进行鸿蒙化。根据使用量排序已经适配了一批plugin，归档在GitCode上，使用方法可以参考Flutter三方库依赖引用及常见问题
    • 针对尚未适配的插件可以去官方开发者论坛提需求，会有官方技术支持响应评估，可以选择功能相同或类似的鸿蒙化插件进行替换
    • 针对自研插件，需要自行适配，文档可以参考开发plugin
  • 平台代码适配

Android或者IOS上可能开发了一些平台代码（Java、swift等），在适配时，需要将此部分代码使用ArkTS重写，经验评估： ArkTS代码行数 = 0.7 * Java代码行数

  • C++相关适配
    分为SO和源码两种：
    • SO文件需要对源码进行交叉编译成HarmonyOS上可运行的SO，再使用dart:ffi调用
    • 源码可以使用FFI插件的方式，HarmonyOS上需要使用cmake进行编译

可以结合自身对相关技术的掌握程度评估具体工作量

环境准备

  1. 先安装好最新release版本的DevEco Studio
  2. 下载鸿蒙版本的Flutter SDK
  3. 由于当前DevEco Studio不支持Dart开发，还需要额外下载VSCode或者Android Studio进行Dart开发和调试
  4. 以上完成后配置环境变量

以上完成后就可以开发HarmonyOS上的Flutter应用了

命令行工具

Flutter命令行工具也做了鸿蒙化，使用起来和在Android上十分类似，环境配置完后即可使用，可以直接通过命令创建Flutter鸿蒙模板工程，打包成har、hap或者app包，或者运行程序等等。列举了一些常用的命令如下：

指令名称

指令描述

使用说明

doctor

环境检测

flutter doctor -v

create

创建新项目

flutter create --platforms ohos,android,ios --org <org> <appName>

create

创建module模板

flutter create -t module <module_name>

create

创建plugin模板

flutter create -t plugin --platforms ohos,android,ios <plugin_name>

create

创建plugin_ffi模板

flutter create -t plugin_ffi --platforms ohos,android,ios <plugin_name>

devices

已连接设备查找

flutter devices

build

测试应用构建

flutter build hap --debug [--target-platform ohos-arm64]

build

正式应用构建

flutter build hap --release [--target-platform ohos-arm64]

run

应用运行

flutter run

attach

调试模式

flutter attach

pub

获取依赖

flutter pub get

clean

清除项目依赖

flutter clean

cache

清除全局缓存数据

flutter pub cache clean

参考完整命令列表

如何调试

由于当前DevEco Studio无法调试Dart代码，因此日常开发调试需使用2个IDE：Deveco Studio+Android Studio或VSCode。

  • Flutter App类型： 
    • 如何调试ArkTS代码 
      1. 连接真机或模拟器,真机需启用开发者选项，并打开USB调试，使用Deveco Studio打开ohos目录，并配置调试签名。
      2. 在Flutter工程根目录下执行flutter build hap构建出hap包。
      3. 在需要调试的Arkts代码行打上断点，点击第一步中DevEco Studio的右上角debug按钮运行应用程序，即可调试ArkTS代码。
    • 如何调试Dart代码 
      1. 使用Android Studio打开工程，找到main.dart文件，debug运行main方法。
      2. 使用VSCode打开工程，找到main.dart文件，debug运行main方法。
  • 混合开发类型：
    1. 参考app类型如何调试ArkTS代码, debug运行ohos工程。
    2. 调试Dart码时，使用android studio或vscode，通过flutter attach连接已经运行的应用程序，此时可以断点调试Dart，也可热重载Dart代码。

三方库替换

  • 纯Dart库
    可以直接引用pub上的版本，不涉及HarmonyOS适配工作
  • 已适配HarmonyOS三方库
    需要采用git方式进行引用，详细可以参考Flutter三方库依赖引用及常见问题
  • 插件未适配
    可以去官方开发者论坛提需求，会有官方技术支持响应评估，可以选择功能相同或类似的鸿蒙化插件进行替换
  • 自定义三方插件
    需要自行适配，文档可以参考开发plugin

申请应用权限

  • 应用使用权限配置
    应用在申请权限时，需在项目的配置文件module.json5中逐个声明权限。
    用户权限申请需使用Permission_Handler插件。
  • 受限权限申请
    受限开放的权限通常是不允许三方应用申请的：
    • 需要评估当前应用场景是否可申请受限权限,如满足申请条件，可提供相关申请材料到应用市场申请相应权限
    • 通常在三方插件中如Wechat_Asset_Picker等涉及受限权限，可考虑使用其它三方库替换，例如image_picker
    • 另外有些受限权限，文档建议使用安全控件替代，但是跨端框架无法使用安全控件，申请的时候可以注明此应用是跨端框架开发的应用，一般可以通过申请

打包和发布

  1. 测试/生产证书管理、环境隔离
    • 自动签名：开发自测阶段，IDE提供了自动签名方式快速签名，且开放了ACL权限，以及开通开放能力（推送、地图等），方便开发者快速开发调试。
    • 手动签名：发布上架应用阶段，需使用手动签名方式申请发布证书，需手动在AGC平台上申请ACL权限且审批通过，需开通开放能力。
  2. 构建release包
    • 使用Deveco Studio构建App包： 
      1. 在Flutter工程中执行命令行flutter build har --release构建har包。
      2. 参考打包APP使用Deveco Studio工具构建App包,打包产物路径ohos/build/outputs/default/***.app。
    • 使用Flutter构建App包(纯Flutter应用)：
      使用发布证书替换调试证书后，执行命令行flutter build app --release即可编译构建出app包，打包产物路径：ohos/build/outputs/default/***.app。
    • 混合开发应用：
      1. har包引入：Flutter module编译release的har包，替换Ohos工程中的har包，使用Deveco Studio构建App包。
      2. 源码引入：直接使用Deveco Studio构建App包。
  3. 发布AppGallery Connect
    • 发布HarmonyOS应用:应用正式发布到华为应用市场前,AGC审核人员会进行会审核开发者提交的所有信息。
    • 邀请测试:正式版本发布之前，您可以选择特定用户群组来测试您的应用，以收集测试用户的反馈意见，助您提前发现问题，及时修复和优化版本体验
    • 内部测试:可以将应用发布上传至您的服务器或者第三方云上，团队参与测试的人员可以将应用下载到授权的设备上测试。
    • 蒲公英测试：蒲公英平台提供了分发HarmonyOS应用的服务，IOS开发者能够快速的掌握分发测试HarmonyOS应用。
Flutter For Harmony今日时鉴应用
坚果的博客
07-23 724
Flutter For Harmony 无尽可能
HarmonyOS—设备适配与生态拓展
duolala888的博客
05-20 1349
在HarmonyOS Next的广阔生态中，设备适配犹如桥梁，连接着系统与多样化的硬件设备。随着HarmonyOS Next的不断发展，其应用场景涵盖了手机、平板、智能穿戴、智能家居等众多领域。不同类型的设备在硬件规格、屏幕尺寸、输入输出方式等方面存在显著差异。良好的设备适配能够确保应用在各种设备上稳定运行，提供一致且优质的用户体验。例如，一个在手机上运行流畅的应用，如果未经适配直接安装在智能手表上，可能会出现界面显示错乱、功能无法正常使用等问题。
Flutter 以模块化方案 适配 HarmonyOS 的实现方法
qq_32136827的博客
08-15 610
Flutter 应用可以通过与 HarmonyOS 原生代码交互来适配 HarmonyOS 平台。主要涉及 Flutter 端的插件开发和 HarmonyOS 端的原生能力实现。通过以上方法，Flutter 应用可以无缝适配 HarmonyOS，并调用原生功能。与 HarmonyOS 原生代码通信。在 HarmonyOS 中，需要实现。来处理 Flutter 的调用。在 Flutter 中，通过。
Flutter Image Editor 适配鸿蒙HarmonyOS平台实践
nanxuan521的专栏
12-05 1189
通过本次适配，我成功将库适配到了HarmonyOS平台。的核心功能都在Dart层面实现，减少了平台特定代码的工作量HarmonyOS提供了良好的Flutter插件支持，简化了适配过程与Android/iOS的适配架构保持一致，降低了学习成本。
Flutter适配HarmonyOS实践
nanxuan521的专栏
12-27 2934
flutter适配鸿蒙
HarmonyOS适配实践：Flutter 项目全流程指南-环境搭建
2501_92427005的博客
11-21 1107
随着 HarmonyOS 的全面落地，Flutter 适配鸿蒙正逐渐从探索阶段进入成熟落地期。对现有项目而言，迁移的核心不在逻辑重构，而在于环境搭建、依赖替换与平台能力适配。通过合理调整工程结构、选择兼容插件、优化平台判断逻辑，即可保证应用顺利运行并享受鸿蒙系统带来的原生性能与多设备协同能力。未来，鸿蒙生态的持续扩展将进一步放大 Flutter 的跨平台优势，提前完成适配的团队将率先占据市场机会。现在正是拥抱鸿蒙、布局未来的最佳时机。
Flutter Chewie 视频播放器 HarmonyOS 适配使用指南
最新发布
weixin_64166120的博客
12-18 341
fluttertpc_chewie 是一个专为 HarmonyOS 设备适配的 Flutter 视频播放插件，基于 chewie@1.8.5 开发。主要功能包括视频播放控制、进度调节、音量控制、全屏播放、自定义字幕等。通过 Git 引入依赖后，开发者可轻松实现视频播放功能，支持多平台控制界面适配和自定义样式。该插件提供了完整的 API 文档和示例代码，包括基础播放、字幕设置、全屏控制、视频源切换等功能，帮助开发者在 HarmonyOS 设备上构建高质量的视频播放体验。
纯Dart Flutter库适配HarmonyOS
yuanlaile的博客
12-25 495
Flutter基本组件、Flutter布局组件、Flutter图片组件、Flutter字体、Flutter图标、Fluter路由、flutter动画、 Flutter表单、flutter异步等，纯Dart库无需任何处理，可以直接编译成HarmonyOs应用。
HarmonyOS开发——鸿蒙Flutter项目适配
android__bye的博客
05-30 4486
随着鸿蒙 HarmonyOS Next的快速发展，越来越多的开发者开始尝试将 Flutter 项目迁移至鸿蒙生态。本文将基于实际开发经验，从环境搭建到应用部署，详细讲解适配 HarmonyNext 的完整流程，并记录常见问题及解决方案。
Flutter × 鸿蒙系统：一文搞懂如何将你的 App 移植到 HarmonyOS！
m0_74456227的博客
07-17 4820
摘要：本文详细介绍了如何将Flutter应用迁移至鸿蒙系统（HarmonyOS）的完整流程。通过安装Flutter SDK、DevEco Studio和社区插件flutter_harmonyos，开发者可以快速适配鸿蒙设备。文章提供了代码示例，展示如何替代原生功能（如设备路径获取、Toast提示、通知和传感器读取），并针对典型场景（如日程提醒、相册选择）给出实战解决方案。此外，还解答了常见问题，强调平台差异隔离和模块化设计的重要性，为跨平台开发提供实用指导。
Flutter跨平台开发实战：HarmonyOS应用集成与推送配置
威哥说编程
04-29 1397
Flutter作为一种跨平台开发框架，默认支持Android和iOS。但对于HarmonyOS，Flutter官方并未直接提供原生支持。因此，为了将Flutter应用集成到HarmonyOS，我们需要借助华为提供的HarmonyOS开发工具包（SDK）和一些中间层技术，如Flutter插件和自定义平台通道。本文介绍了如何将Flutter应用集成到HarmonyOS平台，并配置推送服务。通过Flutter的平台通道技术，我们能够将华为推送SDK与Flutter应用结合起来，实现跨平台的推送通知功能。
深入探索Flutter自定义绘制：从零到一实现炫酷仪表盘
2501_93809844的博客
12-16 755
本文详细介绍了Flutter中的自定义绘制技术，重点讲解了CustomPainter、Canvas和Paint三大核心工具的使用方法。通过构建一个动态仪表盘的实战案例，展示了如何绘制弧线、刻度、指针等基础图形，并实现带动画效果的渐变进度条。文章还提供了性能优化技巧，如对象复用和响应式绘制，帮助开发者创建高效的自定义UI组件。从基础图形绘制到复杂动画实现，本文为Flutter开发者提供了全面的自定义绘制指南，帮助开发者突破标准Widget的限制，实现高度定制化的UI设计。
深入实战：Flutter + OpenHarmony 分布式软总线通信完整实现指南
2502_93572233的博客
12-12 719
本文介绍了如何在OpenHarmony设备上实现Flutter应用通过分布式软总线进行跨设备通信。主要内容包括： 环境准备：需配置DevEco Studio、OpenHarmony SDK及定制版Flutter SDK，并添加必要的权限声明。 原生服务封装：使用ArkTS实现了完整的DSoftBusService，支持设备发现、会话建立和消息收发功能。 桥接层实现：通过MethodChannel和EventChannel将原生能力暴露给Flutter层，实现双向通信。 项目特点： 支持OpenHarmony
Flutter video_thumbnail 库在鸿蒙（OHOS）平台的适配实践
nanxuan521的专栏
12-15 751
通过上面这个插件的适配案例，我们其实系统性地走了一遍将 Flutter 三方库迁移到鸿蒙平台的完整流程：从环境准备技术原理分析，到鸿蒙原生代码实现，再到集成调试与最后的性能优化。整个过程也再次印证了 Flutter 插件跨平台能力的本质——它通过一套标准化的通道协议，把具体的功能实现“委托”给了各个平台最擅长的原生部分。需要对Flutter 插件架构和OHOS Napi 开发模型都有比较深入的理解。要能精准找到功能对标的原生鸿蒙 API（比如这里的媒体解码和图像处理）。妥善处理异步和内存管理。
Flutter和SAPUI5集成
duangww的博客
12-13 890
在维护遗留的 Flutter 应用时，希望借助自己熟悉的 SAPUI5 技术栈，将基于 SAPUI5 开发的 Web 应用集成到现有 Flutter 应用中。android/app/src/main/AndroidManifest.xml (line 1) 的 <application> 增加：android:usesCleartextTraffic="true"。initialUrl: 'http://你的ip:端口/zfiori_stock/index.html',尝试过解决方案，都没解决。
Flutter 状态管理进阶：从 Provider 到 Riverpod 2.0（原理 + 实战 + 性能优化）
2501_93660706的博客
12-15 887
Flutter状态管理方案Riverpod 2.0深度解析：从Provider迁移到性能优化 摘要：本文深入探讨Flutter状态管理方案Riverpod 2.0的核心优势与实战应用。相比传统Provider方案，Riverpod 2.0通过无上下文依赖设计、编译期安全校验和精准重建控制，显著提升了代码可维护性和性能表现。文章详细对比了两种方案的实现差异，展示了计数器、用户状态管理等典型场景的代码示例，并提供了select精准监听、Consumer优化等性能调优技巧。
Flutter + OpenHarmony 安全与隐私合规实践：构建可信、合规、用户放心的鸿蒙应用
2501_93573294的博客
12-16 836
Flutter + OpenHarmony 安全与隐私合规实践：构建可信、合规、用户放心的鸿蒙应用
鸿蒙跨端协同与Flutter结合的远程办公轻应用开发
2501_94138677的博客
12-13 1084
摘要：本文介绍了鸿蒙分布式能力与Flutter跨平台特性结合开发远程办公应用的方案。通过鸿蒙的分布式数据管理和设备虚拟化，配合Flutter的UI开发，实现多端协同办公功能。详细说明了开发环境配置、数据同步实现、设备虚拟化集成及性能优化策略，并提供了典型业务场景实现方案。该方案已在实际应用中验证，可显著提升协同效率，降低开发成本。欢迎开发者加入开源社区共建生态。
Flutter 的编译技术核心
2501_94417424的博客
12-18 785
Flutter编译技术采用两阶段设计，前端编译将Dart转为中间代码，本地编译生成平台特定代码。Dart语言支持JIT（开发环境）和AOT（生产环境）双模式，分别实现快速迭代与高性能运行。关键技术包括Tree Shaking代码优化、Skia/Impeller渲染引擎，未来将集成WebAssembly、AI模型和模块化交付。实际开发建议使用编译分析工具、分架构构建和FFI原生接口优化性能。Flutter通过创新的编译技术实现了跨平台高性能应用开发。
如何在 DevEco Studio 中配置 Flutter 项目以支持 HarmonyOS？
08-08
### 配置 DevEco Studio 以支持 Flutter 项目开发 HarmonyOS 应用 在 DevEco Studio 中配置 Flutter 项目以支持 HarmonyOS 平台，需要完成开发环境搭建、Flutter SDK 适配、构建流程调整等多个步骤，以确保 Flutter 应用能够顺利运行在鸿蒙设备上。 #### 安装与配置 DevEco Studio DevEco Studio 是基于 IntelliJ IDEA Community 版本打造的集成开发环境（IDE），专为 HarmonyOS 应用开发设计，支持工程模板创建、开发、编译、调试、发布等全流程服务[^1]。在安装完成后，可以通过以下步骤进行配置： - 打开 DevEco Studio，进入 **File → Settings → Plugins**。 - 在已安装插件中找到 **Chinese (Simplified) Language Pack**，点击 **Apply** 后重启 IDE，以切换至中文界面[^2]。 - 安装必要的 Flutter 和 Dart 插件，确保其版本与使用的 Flutter SDK 兼容。 #### 配置 Flutter SDK 以支持 HarmonyOS 由于官方 Flutter SDK 尚未原生支持 HarmonyOS，因此需要使用适配 HarmonyOS 的 Flutter 版本，例如通过 `fvm`（Flutter Version Management）安装特定版本： ```bash fvm install 3.7.12-ohos ``` 切换到该版本后，在 DevEco Studio 中设置 Flutter SDK 路径，确保项目使用的是支持 HarmonyOS 的 SDK 版本。 #### 创建 Flutter 项目并适配 HarmonyOS 创建 Flutter 项目后，需要修改构建配置以支持 HarmonyOS。在 `android/app/build.gradle` 文件中，确保使用支持 HarmonyOS 的插件和依赖： ```gradle plugins { id 'com.android.application' id 'org.jetbrains.kotlin.android' id 'dev.ohos' // 确保使用适配 HarmonyOS 的插件 } ``` 同时，确保 `pubspec.yaml` 中的插件兼容 HarmonyOS，或使用适配鸿蒙的替代插件版本。 #### 构建与部署到 HarmonyOS 设备 构建 Flutter 应用以支持 HarmonyOS 时，需使用 DevEco Studio 的构建工具链。构建过程中会生成 `.hap` 格式的安装包，这是 HarmonyOS 的原生应用格式。 - 在 DevEco Studio 中选择目标设备（模拟器或真机）。 - 点击 **Run** 按钮，DevEco Studio 将自动编译并部署应用到目标设备上。 - 使用内置的调试工具进行日志查看和性能分析，确保应用运行稳定。 #### UI 与交互适配 由于 HarmonyOS 的 UI 框架与 Android 存在差异，特别是在多设备协同和分布式能力方面，建议根据鸿蒙的设计规范调整应用的主题和控件样式，以提升用户体验。例如，适配响应式布局以支持不同尺寸的鸿蒙设备，如手机、平板、智能手表等。 --- ###
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
红包 添加红包
表情包 插入表情
表情包 代码片
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值