Flutter代码生成与通信插件 pigeon_generator 的使用

pigeon_generator 是一个 Dart 包，它将 build_runner 与 pigeon 代码生成器集成在一起，用于平台通道的代码生成。这使得运行 pigeon 自动化，从而更轻松、高效地生成平台通道代码。

安装

要安装此包，请运行以下命令：

flutter pub add build_runner pigeon pigeon_generator --dev

或者，在 pubspec.yaml 文件中添加以下依赖项，替换 [version] 为包的最新版本：

dev_dependencies:
  build_runner: [version]
  pigeon: [version]
  pigeon_generator: [version]

使用

按照以下步骤在项目中使用 pigeon_generator：

1. 创建 pigeons 文件夹

在项目的根目录下创建一个名为 pigeons 的文件夹，该文件夹将包含所有的 pigeon 文件。

还需要在 build.yaml 文件中包含此文件夹，以便 build_runner 可以识别 pigeon 文件。

additional_public_assets:
  - pigeons/**

如果使用不同的文件夹名称（例如 pigeons_other），则需要相应地更新 build.yaml 文件中的配置：

targets:
  $default:
    builders:
      pigeon_generator:
        options:
          inputs: pigeons_other

additional_public_assets:
  - pigeons_other/**

2. 配置 pigeon_generator

默认情况下，只需创建包含 pigeon 文件的 pigeons 文件夹，并在 build.yaml 文件中的 additional_public_assets 中指定该文件夹即可。

以下是完整的配置选项示例：

targets:
  $default:
    builders:
      pigeon_generator:
        options:
          inputs: pigeons # 默认值
          dart:
            out: "lib" # 如果 one_language 未设置或为 false，则默认为 lib/pigeons
            test_out: "test" # 或 true/false
            package_name: "pigeon_generator_example"
          cpp: # 或 true/false
            header_out: "windows/runner"
            source_out: "windows/runner"
            options:
              namespace: "pigeon_generator_example"
          gobject: # 或 true/false
            header_out: "linux"
            source_out: "linux"
            options:
              module: "pigeon_generator_example"
          kotlin: # 或 true/false
            out: "android/app/src/main/kotlin/com/example/pigeon_generator_example"
            package: "com.example.pigeon_generator_example"
          java: # 或 true/false
            out: "android/app/src/main/java/com/example/pigeon_generator_example"
            options:
              package: "com.example.pigeon_generator_example"
              use_generated_annotation: true
          swift: # 或 true/false
            out: "ios/Runner"
          objc: # 或 true/false
            header_out: "macos/Runner"
            source_out: "macos/Runner"
            options:
              prefix: "PGN"
          ast: # 或 true/false
            out: "output"
          copyright_header: "pigeons/copyright.txt" # 如果版权文件位于 pigeon 文件所在的同一目录，则不需要此选项
          one_language: false
          debug_generators: false
          base_path: "pigeon_generator_example"
          skip_outputs:
            defaults: [ios] # 不为 ios 生成 pigeons/defaults.dart 的输出
          out_template: "name.g.extension" # 默认值

additional_public_assets:
  - pigeons/**

3. 运行生成器

要生成代码，请运行以下命令：

dart run build_runner build

示例 Demo

以下是一个完整的示例，展示了如何使用 pigeon_generator 在 Flutter 项目中进行跨平台通信。

1. 创建 pigeons 文件夹并添加 Pigeon 文件

在项目根目录下创建 pigeons 文件夹，并在其中添加一个名为 example_pigeon.dart 的文件：

import 'package:pigeon/pigeon.dart';

@HostApi()
abstract class ExampleApi {
  String echo(String message);
}

2. 更新 pubspec.yaml

确保在 pubspec.yaml 中添加了必要的依赖项：

dev_dependencies:
  build_runner: ^2.0.0
  pigeon: ^0.2.0
  pigeon_generator: ^0.2.0

3. 配置 build.yaml

在项目根目录下创建 build.yaml 文件，并添加以下内容：

targets:
  $default:
    builders:
      pigeon_generator:
        options:
          inputs: pigeons
          dart:
            out: "lib"
            test_out: "test"
            package_name: "pigeon_generator_example"
          cpp:
            header_out: "windows/runner"
            source_out: "windows/runner"
            options:
              namespace: "pigeon_generator_example"
          gobject:
            header_out: "linux"
            source_out: "linux"
            options:
              module: "pigeon_generator_example"
          kotlin:
            out: "android/app/src/main/kotlin/com/example/pigeon_generator_example"
            options:
              package: "com.example.pigeon_generator_example"
          java:
            out: "android/app/src/main/java/com/example/pigeon_generator_example"
            options:
              package: "com.example.pigeon_generator_example"
              use_generated_annotation: true
          swift:
            out: "ios/Runner"
          objc:
            header_out: "macos/Runner"
            source_out: "macos/Runner"
            options:
              prefix: "PGN"
          ast:
            out: "output"
          copyright_header: "pigeons/copyright.txt"
          one_language: false
          debug_generators: false
          base_path: "pigeon_generator_example"
          skip_outputs:
            defaults: [ios]
          out_template: "name.g.extension"

additional_public_assets:
  - pigeons/**

4. 运行生成器

运行以下命令生成代码：

dart run build_runner build

5. 在 Flutter 应用中使用生成的代码

在 Flutter 应用中，您可以使用生成的 API 来调用原生代码。例如：

import 'package:flutter/material.dart';
import 'package:pigeon_generator_example/pigeons/example_pigeon.dart'; // 生成的 Dart 文件

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Pigeon Generator Example')),
        body: Center(
          child: ElevatedButton(
            onPressed: () async {
              final api = ExampleApi();
              final result = await api.echo('Hello from Flutter!');
              print(result); // 输出：Hello from Flutter!
            },
            child: Text('Call Native Code'),
          ),
        ),
      ),
    );
  }
}