在鸿蒙系统中使用Flutter模块的实践指南
插件概述
Flutter add_to_app 是一种将 Flutter 模块整合到现有原生应用中的方法，它使开发者能够在不改变原有代码结构的前提下，利用 Flutter 的跨平台优势开发新功能。本文将详细介绍如何在鸿蒙（HarmonyOS）系统上使用 add_to_app 中的书籍示例模块。
依赖配置
由于该模块为自定义版本，需通过 Git 方式引入。请按照以下步骤在您的鸿蒙项目中配置依赖关系：
- 打开项目根目录下的
pubspec.yaml文件 - 在
dependencies部分添加如下配置：
dependencies:
flutter_module_books:
git:
url: "https://gitcode.com/openharmony-tpc/flutter_packages.git"
path: "packages/flutter_samples/add_to_app/books/flutter_module_books"- 执行
flutter pub get命令获取依赖
数据交互
数据模型
books 模块主要使用以下数据结构在 Flutter 和鸿蒙之间传输信息：
class Book {
String? title; // 书名
String? subtitle; // 副标题
String? author; // 作者
String? summary; // 简介
String? publishDate; // 出版日期
int? pageCount; // 页数
Thumbnail? thumbnail; // 封面缩略图
}
class Thumbnail {
String? url; // 缩略图 URL
}通信接口
通过 Pigeon 自动生成的接口实现 Flutter 与鸿蒙之间的双向通信：
从鸿蒙到 Flutter 的调用
// 在 Flutter 中注册接收鸿蒙端的调用
FlutterBookApi.setup(FlutterBookApiHandler((book) {
// 处理从鸿蒙端传递过来的 Book 对象
setState(() {
this.book = book;
// 更新 UI
});
}));从 Flutter 到鸿蒙的调用
// 创建 HostBookApi 实例，用于调用鸿蒙端的方法
final hostApi = HostBookApi();
// 取消编辑
hostApi.cancel();
// 完成编辑并返回更新后的 Book 对象
hostApi.finishEditingBook(updatedBook);模块集成
配置鸿蒙模块
在 flutter_module_books/.ohos/flutter_module/src/main/module.json5 文件中配置模块信息：
{
"module": {
"name": "flutter_module",
"type": "har",
"description": "flutter_module",
"mainElement": "",
"deviceTypes": ["phone", "tablet", "2in1"],
"installationFree": false,
"abilities": [],
"requestPermissions": [
{"name": "ohos.permission.INTERNET"}
]
}
}在 ArkTS 中使用 Flutter 模块
在鸿蒙应用的 EntryAbility.ets 或其他合适位置初始化 Flutter 引擎并加载 Flutter 模块：
// 导入必要的模块
import { AbilityStage } from '@kit.AbilityKit';
import { FlutterEngine } from '@ohos/flutter_engine';
export default class MyAbilityStage extends AbilityStage {
onCreate() {
// 初始化 Flutter 引擎
const flutterEngine = new FlutterEngine();
await flutterEngine.initialize();
// 预加载 Flutter 模块
await flutterEngine.runDartEntrypoint('lib/main.dart');
}
}向 Flutter 模块传递数据
// 创建 Book 对象
const book = {
title: 'Flutter 实战',
author: '张三',
publishDate: '2025-01-01',
pageCount: 300
};
// 传递给 Flutter 模块
await flutterEngine.invokeMethod('displayBookDetails', book);接收来自 Flutter 的数据
// 监听 Flutter 模块的回调
flutterEngine.setMethodCallHandler((method, args) => {
if (method === 'finishEditingBook') {
const updatedBook = args as Book;
// 处理更新后的 Book 对象
console.log('Updated book:', updatedBook);
} else if (method === 'cancel') {
// 处理取消操作
console.log('Edit canceled');
}
return Promise.resolve();
});示例应用
书籍示例应用展示了一个完整的图书详情编辑功能：
- 鸿蒙原生应用通过
displayBookDetails方法将 Book 对象传递给 Flutter 模块 - Flutter 模块显示图书详情编辑界面，允许用户修改书名、副标题和作者
- 用户可以点击保存按钮，通过
finishEditingBook方法将更新后的 Book 对象返回给鸿蒙原生应用 - 用户也可以点击取消按钮，通过
cancel方法取消编辑
总结
Flutter add_to_app 提供了一种灵活的方式将 Flutter 功能嵌入到现有的鸿蒙应用中，特别是书籍示例展示了：
- 如何使用 Pigeon 插件简化 Flutter 与鸿蒙之间的通信
- 如何在保留现有业务逻辑的同时，利用 Flutter 快速开发新功能
- 如何在 Flutter 和鸿蒙之间传递复杂的数据结构
这种混合开发模式使开发者能够充分利用 Flutter 的跨平台能力和鸿蒙的原生特性，为用户提供更优质的应用体验。
