Flutter构建工具插件pigeon_build_runner的使用

pigeon_build_runner 是一个强大的Dart包，它将 pigeon 包与 build_runner 包无缝集成，提高了Flutter项目中代码生成的效率和简便性。该包作为 pigeon 和 build_runner 之间的桥梁，简化了通信过程并自动化了代码生成工作流。

开始使用

1. 安装依赖

在你的 pubspec.yaml 文件中添加以下依赖：

dependencies:
  flutter:
    sdk: flutter

dev_dependencies:
  pigeon: ^<latest_pigeon_version>
  build_runner: ^<latest_build_runner_version>
  pigeon_build_runner: ^<latest_pigeon_build_runner_version>

请确保将 <latest_pigeon_version>、<latest_build_runner_version> 和 <latest_pigeon_build_runner_version> 替换为最新的版本号。你可以在 pub.dev 上找到最新版本。

2. 包含一个pigeon文件夹

如果你的pigeon文件放置在Dart项目的 lib 文件夹之外，你需要创建一个 build.yaml 文件来正确配置构建系统。这一步骤对于从你的pigeon文件生成必要的代码是必需的。

注意： 如果你所有的pigeon文件都放在 lib 文件夹内，可以跳过此步骤直接进行步骤3。

以下是具体操作步骤：

在你的Dart项目根目录下，如果不存在 build.yaml 文件，则创建一个新的 build.yaml 文件。
使用你喜欢的文本编辑器打开 build.yaml 文件。
添加以下配置到 build.yaml 文件中：

additional_public_assets:
  # 添加包含你的pigeon文件的目录，相对于根目录
  - path/to/pigeons/directory/**

将 path/to/pigeons/directory 替换为你pigeon文件所在目录的实际相对路径。确保缩进正确，如示例所示。

3. 配置项目

打开你的Flutter项目的 pubspec.yaml 文件。

在 pigeon 键下添加以下配置。以下配置中的所有输出并不是必须的，你可以根据需要配置必要的输出。

注意： 请替换为适合你项目配置的路径。

pigeon:
  # main-input 定义默认值和基本路径或包名
  main-input:
    input: pigeons/
    dart:
      out: lib/src/pigeons/ 
      test-out: test/pigeons/
    ast:
      out: lib/src/pigeons_ast/
    objc:
      header-out: ios/Runner/
      source-out: ios/Runner/
      # 设置为你的插件或应用程序的唯一前缀，遵循Objective-C命名规范
      prefix: PGN
    java:
      out: android/app/src/main/java/dev/flutter/pigeon_example_app
      package: your.package.name
    swift:
      out: ios/Runner/
    kotlin:
      out: android/app/src/main/kotlin/dev/flutter/pigeon_example_app
      package: your.package.name
    cpp:
      header-out: windows/runner
      source-out: windows/runner
      namespace: CppNamespace
  inputs:
    - input: my_pigeon.dart
      dart:
        out: my_pigeon.dart
        test-out: my_pigeon_test.dart
      ast:
        out: my_pigeon_ast.dart
      objc:
        header-out: my_pigeon.g.h
        source-out: my_pigeon.g.s
      java:
        out: MyPigeon.g.java
        # 添加 `.` 前缀会将 `main-input` 中的包名与下面的包名连接起来
        # 结果：your.package.name.additional.package.name
        package: .additional.package.name
      kotlin:
        out: MyPigeon.g.kt
        # 添加 `.` 前缀会将 `main-input` 中的包名与下面的包名连接起来
        # 结果：your.package.name.additional.package.name
        package: .additional.package.name
      swift:
        out: MyPigeon.g.swift
      cpp:
        header-out: my_pigeon.g.h
        source-out: my_pigeon.g.cpp

使用 main-input 并不是绝对必需的，但它有助于定义输入/输出文件夹的基本路径和包名，从而减少样板代码。

路径配置

如果路径以正斜杠 / 开头，则将使用主包文件夹。

pigeon:
  main-input:
    input: pigeons/
    dart:
      out: lib/src/pigeons/ 
  inputs:
    - input: first_pigeon.dart
      dart:
        out: first_pigeon.dart # lib/src/pigeons/first_pigeon.dart
    - input: second_pigeon.dart
      dart:
        out: /lib/custom_folder/second_pigeon.dart # /lib/custom_folder/second_pigeon.dart

包配置

如果包名不以点 . 开头，则不会使用 main-input 中的包名。

pigeon:
  # main-input 定义默认值和基本路径或包名
  main-input:
    input: pigeons/
    java:
      out: android/app/src/main/java/dev/flutter/pigeon_example_app
      package: your.package.name
  inputs:
    - input: first_pigeon.dart
      java:
        out: FirstPigeon.g.java
        package: .additional.package.name # your.package.name.additional.package.name
    - input: second_pigeon.dart
      java:
        out: SecondPigeon.g.java
        package: another.package.name # another.package.name

所有可用属性

以下是 pigeon_build_runner 包的所有可用属性概述。有关每个属性的详细信息，你可以参考 pigeon文档。

pigeon:
  main-input:
    copyright-header: copyright.txt
    one-language: true
    debug-generators: true

    input: pigeons/

    ast:
      out: lib/src/pigeons_ast/
    objc:
      header-out: ios/Runner/
      source-out: ios/Runner/
      prefix: PGN
    java:
      out: android/app/src/main/java/dev/flutter/pigeon_example_app
      package: your.package.name
      use-generated-annotation: true
    swift:
      out: ios/Runner/
    kotlin:
      out: android/app/src/main/kotlin/dev/flutter/pigeon_example_app
      package: your.package.name
    cpp:
      header-out: windows/runner
      source-out: windows/runner
      namespace: CppNamespace
  inputs:
    - input: my_pigeon.dart
      
      copyright-header: custom_copyright.txt
      one-language: true
      debug-generators: true

      dart:
        out: my_pigeon.dart
        test-out: my_pigeon_test.dart
      ast:
        out: my_pigeon_ast.dart
      objc:
        header-out: my_pigeon.g.h
        source-out: my_pigeon.g.s
        prefix: CustomPrefix
      java:
        out: MyPigeon.g.java
        package: .additional.package.name
        use-generated-annotation: true
      kotlin:
        out: MyPigeon.g.kt
        package: .additional.package.name
      swift:
        out: MyPigeon.g.swift
      cpp:
        header-out: my_pigeon.g.h
        source-out: my_pigeon.g.cpp

创建者

LinkedIn: Kirill Liubimov
Twitter: @kirillrg
Github: rotorgames

许可证

MIT License

特此授予，免费许可任何人获得本软件及其相关文档文件（“软件”）的副本，并处理软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件的副本，并允许软件的接收者这样做，但需遵守以下条件：

本软件按“原样”提供，不附带任何明示或暗示的保证，包括但不限于适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权持有人都不对任何索赔、损害或其他责任负责，无论是合同行为、侵权行为还是其他行为，均与软件或软件的使用或其他交易有关。

更多关于Flutter构建工具插件pigeon_build_runner的使用的实战系列教程也可以访问 https://www.itying.com/category-92-b0.html

h691938207 1楼•16 小时前

更多关于Flutter构建工具插件pigeon_build_runner的使用的实战系列教程也可以访问 https://www.itying.com/category-92-b0.html

当然，以下是如何在Flutter项目中使用pigeon_build_runner构建工具插件的一个基本示例。pigeon是Flutter官方提供的一个工具，用于生成跨平台（Dart与Objective-C/Swift、Kotlin/Java）的类型安全接口代码，以便在Flutter与原生平台代码之间进行通信。pigeon_build_runner则是这个工具的一个构建运行器（build runner），用于生成这些接口代码。

步骤 1: 添加依赖

首先，在你的pubspec.yaml文件中添加pigeon依赖：

dependencies:
  flutter:
    sdk: flutter
  pigeon: ^x.y.z  # 请替换为最新版本号

dev_dependencies:
  build_runner: ^x.y.z  # 确保build_runner是最新的，用于运行代码生成
  pigeon_build_runner: ^x.y.z  # 请替换为最新版本号

然后运行flutter pub get来安装这些依赖。

步骤 2: 定义接口

创建一个新的Dart文件（例如messaging.dart），用于定义Flutter与原生代码之间的接口。这个文件应该包含使用@HostApi或@FlutterApi注解的类，以及需要跨平台通信的方法。

// messaging.dart
import 'package:pigeon/pigeon.dart';

@HostApi()
abstract class MessagingApi {
  String sendMessage(String message);
}

@FlutterApi()
class Messaging {
  static Messaging _instance = Messaging._();

  Messaging._();

  static Messaging get instance => _instance;

  Future<String> sendMessageToHost(String message) async {
    // 这里是调用原生平台代码的地方，具体实现由pigeon生成
    final MessagingApi api = MessagingApi();
    return api.sendMessage(message);
  }
}

步骤 3: 生成代码

在项目根目录下运行以下命令来生成跨平台的接口代码：

flutter pub run build_runner build

这个命令会读取messaging.dart文件，并生成相应的Objective-C/Swift和Kotlin/Java代码。生成的代码通常位于.dart_tool/pigeon目录下。

步骤 4: 集成到原生平台

iOS（Objective-C/Swift）

将生成的Objective-C/Swift文件添加到你的Xcode项目中，并确保它们被正确编译。然后，在AppDelegate或相应的位置实现MessagingApi接口。

// AppDelegate.m
#import "GeneratedMessagingApi.h"  // 这是pigeon生成的头文件

@interface AppDelegate () <MessagingApi>
@end

@implementation AppDelegate

- (NSString *)sendMessage:(NSString *)message {
  // 实现发送消息的逻辑
  return [NSString stringWithFormat:@"Message received: %@", message];
}

@end

Android（Kotlin/Java）

将生成的Kotlin/Java文件添加到你的Android项目中，并确保它们被正确编译。然后，在相应的位置实现MessagingApi接口。

// MainActivity.kt
import com.example.yourapp.GeneratedMessagingApi  // 这是pigeon生成的类

class MainActivity : AppCompatActivity(), MessagingApi {

    override fun sendMessage(message: String): String {
        // 实现发送消息的逻辑
        return "Message received: $message"
    }
}

步骤 5: 调用跨平台方法

现在，你可以在Flutter代码中调用Messaging.instance.sendMessageToHost方法来与原生平台通信了。

void _sendMessage() async {
  String result = await Messaging.instance.sendMessageToHost("Hello from Flutter!");
  print(result);  // 输出: Message received: Hello from Flutter!
}

这个示例展示了如何使用pigeon_build_runner来定义、生成和实现跨平台的通信接口。请根据你的实际需求调整代码。