Flutter add_to_app 在鸿蒙上的使用指南

NetPilot2025

关注

原创最新推荐文章于 2026-09-10 22:46:16 发布 735 阅读 AI 写同款· GEO 优化 ›

【鸿蒙开发实战教程】在MacOS上如何使用 Flutter 构建鸿蒙APP 有很多小伙伴不知道该从哪里开始学习鸿蒙开发技术？也不知道鸿蒙开发的知识点重点掌握的又有哪些？自学时频繁踩坑，导致浪费大量时间。结果还是一知半解。所以有一份实用的鸿蒙（HarmonyOS NEXT）全栈开发资料用来跟着学习是非常有必要的。阅读详情

插件介绍

Flutter add_to_app 是一个用于将 Flutter 模块嵌入到现有原生应用中的解决方案，它允许开发者在保留现有原生应用代码和业务逻辑的同时，利用 Flutter 的跨平台能力快速开发新功能。本指南将重点介绍如何在鸿蒙（HarmonyOS）上使用 add_to_app 示例中的 books Flutter 模块。

books 示例是 add_to_app 中一个具有代表性的案例，它模拟了一个真实的图书应用场景，展示了：

如何将 Flutter 模块集成到已有业务逻辑和中间件的鸿蒙应用中
如何使用 Pigeon 插件自动生成平台通道代码，简化 Dart 与 ArkTS 之间的通信
如何在 Flutter 和鸿蒙原生应用之间传递复杂数据结构（如 Book 对象）

包的引入

由于这是一个自定义修改版本的 Flutter 模块，需要以 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 命令获取依赖

API 的调用

数据结构

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();
});