【拥抱鸿蒙】Flutter+Cursor轻松打造HarmonyOS应用（一）

前言

在移动应用开发领域，Flutter以其出色的跨平台能力和高效的开发体验赢得了众多开发者的青睐，是许多移动开发者混合开发的首选。

随着HarmonyOS的崛起，许多开发者开始探索如何将Flutter应用迁移到鸿蒙生态。本文将带你从零开始，使用Flutter开发HarmonyOS应用，并借助强大的AI编程助手Cursor来加速UI开发过程。

这是“【拥抱鸿蒙】Flutter+Cursor轻松打造HarmonyOS应用”系列的第一篇。

一、环境准备：搭建Flutter for HarmonyOS开发环境

1.1 基础工具安装

首先确保你的开发机器已安装以下基础工具：

• Flutter SDK（推荐3.13.0或更高版本）

  # 下载Flutter SDK
  git clone https://github.com/flutter/flutter.git -b stable
  
  # 添加环境变量
  export PATH="$PATH:`pwd`/flutter/bin"
  
  # 运行flutter doctor检查依赖
  flutter doctor
  

• HarmonyOS开发工具：
  
  API12, deveco-studio-5.0 或 command-line-tools-5.0 (推荐使用5.0.0 Release或更新版本)

• JDK17

• 配置环境变量

 export TOOL_HOME=/Applications/DevEco-Studio.app/Contents # mac环境
 export DEVECO_SDK_HOME=$TOOL_HOME/sdk # command-line-tools/sdk
 export PATH=$TOOL_HOME/tools/ohpm/bin:$PATH # command-line-tools/ohpm/bin
 export PATH=$TOOL_HOME/tools/hvigor/bin:$PATH # command-line-tools/hvigor/bin
 export PATH=$TOOL_HOME/tools/node/bin:$PATH # command-line-tools/tool/node/bin

注意

这里有一个问题需要注意，支持鸿蒙的Flutter SDK版本目前是3.22.0版本。在开发适配iOS和Android时，我们使用的Flutter版本可能高于3.22.0。这时，因此需要使用fvm对Flutter版本进行管理，可以同时维护和切换多个Flutter版本。同时也建议，Flutter的鸿蒙应用仓库最好和其他端仓库分开，因为目前支持鸿蒙的Flutter版本是滞后于Flutter官方版本的。

使用fvm维护多个版本示例：

1.2 配置Flutter鸿蒙支持

目前Flutter对HarmonyOS的支持主要通过开源项目OpenHarmony-TPC/flutter_flutter实现。

该仓库是基于Flutter官方仓库的3.22.0版本，对于OpenHarmony平台的兼容拓展。可支持IDE或者终端使用Flutter Tools指令编译和构建OpenHarmony应用程序。

Build前需使用fvm切换Flutter版本：

fvm use custom_3.22.0

1.3 环境验证

创建新项目并检查鸿蒙支持：

flutter create my_harmony_app
cd my_harmony_app
flutter run -d harmony

如果看到鸿蒙模拟器或真机上运行着Flutter的默认启动页面，说明环境配置成功！

二、Flutter鸿蒙开发框架解析

2.1 架构概览

Flutter在HarmonyOS上的运行架构分为三层：

1. 框架层：Dart实现的Flutter框架
2. 引擎层：Skia渲染引擎+鸿蒙适配层
3. 系统层：HarmonyOS的ACE（Ability Cross-platform Environment）

2.2 关键差异点

与Android/iOS平台相比，Flutter在鸿蒙上需要注意：

• 页面导航：使用HarmonyOS的Page Ability而非Activity/ViewController
• 权限系统：鸿蒙特有的权限声明方式
• 原生交互：通过ffi与鸿蒙的Native API通信

2.3 常用适配组件

import 'package:flutter_harmony/harmony.dart';

// 鸿蒙特色的组件
HarmonyApp(
  config: HarmonyConfig(
    abilityName: 'MainAbility', // 对应的鸿蒙Ability名称
  ),
  home: MyHomePage(),
);

三、Flutter与鸿蒙原生交互

3.1 导入原生插件

与其他端类似，ohos工程中需要GeneratedPluginRegistrant.ets文件导入Flutter生成的原生插件。

3.2 实现FlutterPlugin

定义一个类作为FlutterPlugin的实现，并在onAttachedToEngine(binding: FlutterPluginBinding): void 方法中使用MethodChannel监听Flutter调用的方法。

export default class HMFlutterPlugin implements FlutterPlugin {
  private channel?: MethodChannel;
  private basicChannel?: BasicMessageChannel<Any>;
  private context?: common.UIAbilityContext;

  setContext(context: common.UIAbilityContext) {
    this.context = context;
  }

  onAttachedToEngine(binding: FlutterPluginBinding): void {
    this.channel = new MethodChannel(binding.getBinaryMessenger(), "com.xxx.app/message");
    this.channel.setMethodCallHandler({
      onMethodCall: (call: MethodCall, result: MethodResult) => {
        if (!this.context) {
          result.error("CONTEXT_NOT_INITIALIZED", "Context is not initialized", null);
        }

        const argsRec = call.args as Map<string, Object>;
        LogUtil.info(`[flutter-call-ohos]\nmethod: ${call.method}\nargs: ${JSONUtil.toJSONString(argsRec)}`);
        switch (call.method) {
          case "xxx": {
            break;
          }
          default: break;
        }
}

3.3 配置FlutterEngine

在EntryAbility.ets中实现configureFlutterEngine(flutterEngine: FlutterEngine) 方法。

configureFlutterEngine(flutterEngine: FlutterEngine) {
    super.configureFlutterEngine(flutterEngine)
    GeneratedPluginRegistrant.registerWith(flutterEngine)
    const plugin = new HMFlutterPlugin();
    plugin.setContext(this.context);
    this.addPlugin(plugin);
  }

3.4 回调返回给Flutter端

使用result.success(res);回调执行成功的数据；使用result.error(errorCode, error.message, null);回调执行失败的错误信息。

try {
    // xxx接口功能实现
    result.success(res);
} catch (err) {
    let error = err as BusinessError;
    result.error(errorCode, error.message, null);
}

3.5 Flutter调用鸿蒙原生方法并接收回调数据

try {
    final res = await _channel.invokeMethod('method_ohos');
    return res.toString().toLowerCase() == 'true' || res.toString() == '1';
} catch (e) {
    printError('get network status error: $e');
}

总结

本篇主要介绍了Flutter开发鸿蒙应用的环境搭建和交互，我们将在下篇介绍如何借助Cursor提高开发效率让我们的开发之旅轻松而有趣。

我是郑知鱼，欢迎大家讨论与指教。

如果你觉得有所收获，也请点赞收藏️关注我吧~~