你好！👋 欢迎来到这篇关于 pigeon 在 HarmonyOS (OpenHarmony) 上使用的实战教程。
pigeon 是 Flutter 官方推荐的类型安全的 Platform Channel 代码生成工具。本文将带你一步步在鸿蒙项目中使用它！🐦

👶 新手小课堂：Pigeon 是什么？

想象一下，Flutter 是讲英语的（Dart），而鸿蒙原生是讲方言的（ArkTS）。他们要交流（比如 Flutter 想问鸿蒙"现在几点了？"），通常需要一个翻译官。

传统的 MethodChannel 就像是 ✍️ 手写纸条传递信息，容易写错字（比如参数名拼错），而且类型不安全（把数字当成字符串传）。

Pigeon 就像是一个专业的 🎙️ “同声传译设备”。你只需要在一张纸上（.dart 定义文件）写好"我们要聊什么"，Pigeon 就会自动生成双方都能听懂的代码。这样既不会传错话，效率也更高！

---

📂 1. 引入依赖：pubspec.yaml

首先，确保你的项目中引入了适配鸿蒙的 pigeon 库。

修改文件：pubspec.yaml

dependencies:
  flutter:
    sdk: flutter

  # 👇 引入 pigeon 鸿蒙适配版本 (注意是 git 依赖)
  pigeon:
    git: 
      url: https://gitcode.com/openharmony-sig/flutter_packages.git
      path: packages/pigeon
      ref: br_pigeon-v25.3.2_ohos

💡 提示：添加后记得运行 flutter pub get！

🎯 为什么需要 Pigeon？

相比传统的 MethodChannel，Pigeon 提供了以下优势：

• ✅ 类型安全：编译时检查，避免运行时类型错误
• ✅ 自动生成代码：减少手写重复代码，降低出错概率
• ✅ 接口明确：API 定义清晰，易于维护和协作
• ✅ 跨平台一致性：统一的接口定义，支持多平台

---

🛠️ 2. 定义 API 与代码生成

2.1 📝 创建定义文件

新建文件：pigeons/messages.dart

我们定义一个简单的 Host API，包含以下功能：

• 🌍 获取宿主语言信息
• ➕ 执行加法计算
• 👋 发送问候消息
• 👤 获取用户信息（演示复杂对象传递）

import 'package:pigeon/pigeon.dart';

@ConfigurePigeon(PigeonOptions(
  dartOut: 'lib/src/messages.g.dart', // 📁 Dart 代码输出路径
))

// 📦 定义用户数据类
class User {
  String? name;
  int? age;
}

// 🎯 定义 Host API 接口
@HostApi()
abstract class ExampleHostApi {
  String getHostLanguage();  // 🌍 获取系统语言
  int add(int a, int b);      // ➕ 加法运算
  String greeting(String name); // 👋 问候方法
  User getUser(String userId);  // 👤 获取用户信息
}

2.2 ⚙️ 运行代码生成命令

在终端中运行以下命令，同时生成 Dart 代码和 ArkTS 代码：

📊 Pigeon 代码生成流程：

# 🚀 生成 Flutter 和鸿蒙端代码
dart run pigeon --input pigeons/messages.dart \
  --dart_out lib/src/messages.g.dart \
  --arkts_out ohos/entry/src/main/ets/messages.ets

✅ 成功标志：运行无报错，且在指定路径下生成了 messages.g.dart 和 messages.ets 文件。

📋 生成的文件说明：

• 📱 lib/src/messages.g.dart：Flutter 端调用接口，包含类型安全的方法定义
• 🎯 ohos/entry/src/main/ets/messages.ets：鸿蒙端接口定义，需要实现具体逻辑

---

💻 3. 鸿蒙端 (Native) 实现

3.1 🔧 实现 API 接口

新建文件：ohos/entry/src/main/ets/ExampleHostApiImpl.ets

我们需要实现生成的接口，提供具体的业务逻辑。

import { ExampleHostApi, User } from './messages';

export class ExampleHostApiImpl extends ExampleHostApi {
  // 🌍 返回系统语言信息
  getHostLanguage(): string {
    return "ArkTS (HarmonyOS)";
  }

  // ➕ 执行加法计算
  add(a: number, b: number): number {
    return a + b;
  }

  // 👋 生成问候消息
  greeting(name: string): string {
    return "Hello " + name + " from HarmonyOS!";
  }

  // 👤 创建并返回用户对象
  getUser(userId: string): User {
    let user = new User();
    user.setName("User " + userId);
    user.setAge(25);
    return user;
  }
}

3.2 📌 注册 API 到 Flutter 引擎

修改文件：ohos/entry/src/main/ets/entryability/EntryAbility.ets

在应用启动时注册 API 实现。

// ... 导入部分
import { ExampleHostApi } from '../messages';
import { ExampleHostApiImpl } from '../ExampleHostApiImpl';

export default class EntryAbility extends FlutterAbility {
  configureFlutterEngine(flutterEngine: FlutterEngine) {
    super.configureFlutterEngine(flutterEngine)
    GeneratedPluginRegistrant.registerWith(flutterEngine)
    
    // 👇 注册 Pigeon API 实现
    ExampleHostApi.setup(flutterEngine.dartExecutor.getBinaryMessenger(), new ExampleHostApiImpl());
  }
}

👶 新手小课堂：为什么要注册 API？

代码生成好只是第一步，ExampleHostApiImpl 就像是你请来的 👨‍💼 “翻译官”（实现了具体的业务逻辑）。

但在应用启动时，系统并不知道有这个翻译官的存在。

ExampleHostApi.setup(...) 这行代码的作用就是：把这个翻译官正式介绍给 Flutter 引擎 📢。告诉引擎：“嘿，如果 Flutter 那边有人问 ExampleHostApi 相关的问题，就找这位 ExampleHostApiImpl 来回答！”

---

📱 4. Flutter 端调用

新建文件：lib/pigeon_demo.dart

现在可以在 Flutter 页面中直接调用生成的 API 了，就像调用本地方法一样简单！✨

4.1 📥 导入生成的接口

import 'src/messages.g.dart'; // 导入生成的文件

// 🎯 创建 API 实例
final ExampleHostApi _api = ExampleHostApi();

4.2 🌍 调用获取语言信息

Future<void> _getHostLanguage() async {
  final String language = await _api.getHostLanguage();
  print("Host Language: $language"); // 输出: ArkTS (HarmonyOS)
}

4.3 ➕ 调用加法计算

Future<void> _addNumbers() async {
  final int result = await _api.add(10, 20);
  print("Result: $result"); // 输出: 30
}

4.4 👋 调用问候方法

Future<void> _getGreeting() async {
  final String greeting = await _api.greeting('Flutter Developer');
  print(greeting); // 输出: Hello Flutter Developer from HarmonyOS!
}

4.5 👤 获取用户对象

Future<void> _getUserInfo() async {
  final User user = await _api.getUser('12345');
  print('Name: ${user.name}, Age: ${user.age}'); // 输出: Name: User 12345, Age: 25
}

---

❓ 5. 常见问题解决方案

😱 问题 1：找不到 arkts_out 选项？

原因分析：

• ❌ 使用了官方版本的 Pigeon（尚未支持鸿蒙）

解决方案：

• ✅ 确保 pubspec.yaml 中使用的是 openharmony-sig 仓库的 br_pigeon-v25.3.2_ohos 分支（或更新版本）
• ✅ 官方版本尚未包含 arkts_out 选项，必须使用鸿蒙适配版本

🐛 问题 2：setup 方法报错？

原因分析：

• ❌ messages.ets 文件未生成或路径错误
• ❌ 实现类导入路径不正确

解决方案：

• ✅ 检查 messages.ets 是否生成成功
• ✅ 确保在 EntryAbility 中正确导入了生成的 messages.ets 和你的实现类
• ✅ 注意文件路径引用是否正确（例如 ../messages）

🔄 问题 3：修改 API 定义后没有生效？

解决方案：

• ✅ 重新运行 dart run pigeon 命令生成代码
• ✅ 清理项目缓存：flutter clean
• ✅ 重新获取依赖：flutter pub get
• ✅ 重新构建鸿蒙端项目

---

🎉 结语

通过 pigeon，我们可以轻松实现 Flutter 与 HarmonyOS 的类型安全通信，告别繁琐的 MethodChannel 字符串硬编码！🚀

📝 本教程实现的功能：

• ✅ 基本数据类型传递（String、int）
• ✅ 复杂对象传递（User 类）
• ✅ 类型安全的 API 调用
• ✅ 自动生成的通信代码

🎯 核心优势：

• 🔒 类型安全：编译时发现错误，避免运行时崩溃
• 🤖 自动生成：减少手写代码，提高开发效率
• 📖 易于维护：统一的 API 定义，便于团队协作
• 🌐 跨平台：一套定义，多端复用

🎉 祝你开发顺利！ 🚀
欢迎加入开源鸿蒙跨平台社区