鸿蒙Flutter实战：25-混合开发详解-5-跳转Flutter页面

鸿蒙 Flutter 实战：25-初始化 Flutter 引擎

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

前言

将 Flutter 模块添加至宿主鸿蒙项目中后，接下来需要实现页面跳转、消息通信等功能。本文重点介绍如何初始化 Flutter 引擎，这是鸿蒙 Flutter 混合开发的基础步骤。

Flutter 引擎初始化流程示意图

一、项目配置

1.1 添加依赖

编辑 ohos_app/oh-package.json 文件，根据集成方式不同，配置也有所不同。

1.2 Har 包方式

如果通过 Har 包方式引入 Flutter 模块，则需要添加如下内容：

{
  "dependencies": {
    "@ohos/flutter_module": "file:har/my_flutter_module.har",
    "@ohos/flutter_ohos": "file:har/my_flutter.har"
  },
  "overrides": {
    "@ohos/flutter_ohos": "file:har/flutter.har"
  }
}

1.3 源码方式

如果通过源码方式引入 Flutter 模块，则需要添加如下内容：

{
  "dependencies": {
    "@ohos/flutter_module": "./flutter_module",
    "@ohos/flutter_ohos": "./har/flutter.har"
  }
}

1.4 配置说明

二、Flutter 引擎初始化

2.1 修改 EntryAbility

编辑 ohos_app/entry/src/main/ets/entryability/EntryAbility.ets 文件。

2.2 修改前（原生鸿蒙应用）

import { AbilityConstant, ConfigurationConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';

const DOMAIN = 0x0000;

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate');
  }

  onDestroy(): void {
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onDestroy');
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageCreate');

    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        hilog.error(DOMAIN, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err));
        return;
      }
      hilog.info(DOMAIN, 'testTag', 'Succeeded in loading the content.');
    });
  }

  onWindowStageDestroy(): void {
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageDestroy');
  }

  onForeground(): void {
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onForeground');
  }

  onBackground(): void {
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onBackground');
  }
}

2.3 修改后（Flutter 混合应用）

import { FlutterAbility, FlutterEngine } from '@ohos/flutter_ohos';
import { GeneratedPluginRegistrant } from '@ohos/flutter_module';

export default class EntryAbility extends FlutterAbility {
  configureFlutterEngine(flutterEngine: FlutterEngine) {
    super.configureFlutterEngine(flutterEngine)
    GeneratedPluginRegistrant.registerWith(flutterEngine);
  }
}

2.4 核心变化

三、FlutterAbility 解析

3.1 继承关系

UIAbility (鸿蒙原生 Ability 基类)
    │
    └─► FlutterAbility (Flutter 提供的扩展类)
            │
            └─► EntryAbility (你的应用 Ability)

EntryAbility 继承自 FlutterAbility，而 FlutterAbility 继承自 UIAbility。

3.2 FlutterAbility 新增功能

FlutterAbility 在 UIAbility 基础上增加了以下功能：

1. 引擎管理

2. UI 交互

3. 生命周期协调

4. 扩展支持

3.3 生命周期对比

四、插件注册

4.1 GeneratedPluginRegistrant

GeneratedPluginRegistrant.registerWith(flutterEngine) 会自动注册所有已安装的 Flutter 插件。

4.2 生成机制

当你运行 flutter pub get 时，Flutter 工具会自动生成 GeneratedPluginRegistrant 文件。

4.3 手动添加插件

如果需要手动添加插件，可以使用 addPlugin 方法：

export default class EntryAbility extends FlutterAbility {
  configureFlutterEngine(flutterEngine: FlutterEngine) {
    super.configureFlutterEngine(flutterEngine)
    GeneratedPluginRegistrant.registerWith(flutterEngine);

    // 手动添加自定义插件
    this.addPlugin(new CustomPlugin());
  }
}

五、完整文件结构

5.1 项目结构

ohos_app/
├── ohos/
│   ├── entry/
│   │   └── src/main/ets/entryability/
│   │       └── EntryAbility.ets  ← 入口文件
│   └── oh-package.json          ← 依赖配置
├── flutter_module/
│   └── ...                       ← Flutter 模块
└── har/
    └── flutter.har              ← Flutter 引擎库

5.2 依赖关系

┌─────────────────────────────────────────────────────────────┐
│                    依赖关系图                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   EntryAbility.ets                                          │
│         │                                                   │
│         │ 继承                                                │
│         ▼                                                   │
│   FlutterAbility                                            │
│         │                                                   │
│         │ 使用                                                │
│         ▼                                                   │
│   FlutterEngine                                             │
│         │                                                   │
│         │ 注册                                                │
│         ▼                                                   │
│   GeneratedPluginRegistrant                                 │
│         │                                                   │
│         │ 包含                                                │
│         ▼                                                   │
│   所有 Flutter 插件                                           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

六、验证初始化

6.1 运行应用

# 进入项目目录
cd ohos_app

# 运行应用
flutter run -d <device_id>

6.2 查看日志

# 查看 Flutter 引擎日志
hdc hilog | grep flutter

# 查看应用日志
hdc hilog | grep "EntryAbility"

6.3 成功标志

七、常见问题

7.1 编译错误

7.2 运行错误

总结

本文介绍了在鸿蒙项目中初始化 Flutter 引擎的完整流程：

1. 配置依赖 - 在 oh-package.json 中添加 Flutter 依赖
2. 修改 EntryAbility - 继承 FlutterAbility 而非 UIAbility
3. 配置引擎 - 在 configureFlutterEngine 中注册插件
4. 验证运行 - 运行应用并查看日志

提示：FlutterAbility 已经处理了大部分生命周期管理，开发者只需要关注 configureFlutterEngine 配置即可。

下一篇预告：[调试指南](https://gitee.com/zacks/awesome-harmonyos-flutter/blob/master/鸿蒙 Flutter 实战：08-调试指南.md)

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源

• 如何使用混合开发 module
• 如何使用混合开发添加跳转 FlutterEntry
• 开源鸿蒙跨平台社区
• Flutter 引擎文档
• HarmonyOS Ability 开发