架构概述：平台通道

平台通道数据类型及编解码器

示例: 通过平台通道调用平台的 iOS、Android 和 Windows 代码

第一步：创建一个新的应用项目

第二步：创建 Flutter 平台客户端

步骤 3: 添加 Android 平台的实现

步骤 4：添加 iOS 平台的实现

第五步：添加 Windows 平台特定实现

通过 Pigeon 获得类型安全的通道

Pigeon 样例

从 UI 代码中分离平台相关代码

将平台相关代码作为 Package 进行提交

自定义通道和编解码器

通道和平台线程

在后台线程中执行 channel 的 handlers

跳转到 Android 中的 UI 线程

跳转到 iOS 中的主线程

本指南介绍了如何编写自定义的平台相关代码，某些平台相关功能可通过已有的软件包获得，具体细节可查看： 在 Flutter 里使用 Packages。

提示

本页面的内容适用于大多数平台，但 Web 插件的实现一般都是通过 JS 交互 或者 dart:html 库 实现的。

Flutter 构建了一个灵活的系统，你可以调用各种相关平台的 API，具体如下所示：

Android 中的 Java 或 Kotlin API

iOS 中的 Objective-C 或 Swift API

Windows 操作系统中的 C++ API

macOS 系统中的 Objective-C

Linux 操作系统中的 C

Flutter 使用了灵活系统，无论是在 Android 上的 Kotlin 还是 Java，亦或是 iOS 上的 Swift 或 Objective-C，它都允许你调用平台特定 API。

Flutter 内置的平台特定 API 支持不依赖于任何生成代码，而是灵活的依赖于传递消息格式。或者，你也可以使用 Pigeon 这个 package，通过生成代码来 发送结构化类型安全消息。

应用中的 Flutter 部分通过平台通道向其宿主 (非 Dart 部分) 发送消息。

宿主监听平台通道并接收消息。然后，它使用原生编程语言来调用任意数量的相关平台 API，并将响应发送回客户端（即应用程序中的 Flutter 部分）。

提示

本篇教程主要介绍如何在非 Dart 语言中，利用平台通道的机制调用平台 API。但是当你在 Flutter 应用里编写 Dart 代码时，你也可以通过判断 defaultTargetPlatform，在不同的平台上执行对应的代码。 不同平台操作体验的差异和适配 文档中列举了部分 Flutter 框架自动为你处理的平台适配行为。

消息使用平台通道在客户端（UI）和宿主（平台）之间传递，如下图所示：

消息和响应以异步的形式进行传递，以确保用户界面能够保持响应。

提示

Flutter 是通过 Dart 异步发送消息的。即便如此，当你调用一个平台方法时，也需要在主线程上做调用。在 这里 查看更多。

客户端做方法调用的时候 MethodChannel 会负责响应，从平台一侧来讲，Android 系统上使用 MethodChannelAndroid、 iOS 系统使用 MethodChanneliOS 来接收和返回来自 MethodChannel 的方法调用。在开发平台插件的时候，可以减少样板代码。

提示

如果需要，方法调用也可以反向发送，由平台充当客户端来调用 Dart 实现的方法。一个具体的例子是 quick_actions 插件。

标准平台通道使用标准消息编解码器，它支持简单的类似 JSON 值的高效二进制序列化，例如布尔值、数字、字符串、字节缓冲区及这些类型的列表和映射（详情请参阅 StandardMessageCodec）。当你发送和接收值时，它会自动对这些值进行序列化和反序列化。

下表展示了如何在平台端接收 Dart 值，反之亦然：

以下代码演示了如何调用平台相关 API 来检索并显示当前的电池电量。它通过平台消息 getBatteryLevel() 来调用 Android 的 BatteryManager API、 iOS 的 device.batteryLevel API、以及 indows 上的 GetSystemPowerStatus。

该示例在主应用程序中添加平台相关代码。如果想要将该代码重用于多个应用程序，那么项目的创建步骤将略有差异（查看 Flutter Packages 的开发和提交），但平台通道代码仍以相同方式编写。

提示

可在 /examples/platform_channel/ 中获得使用 Java 实现的 Android 及使用 Objective-C 实现的 iOS 的该示例完整可运行的代码。对于用 Swift 实现的 iOS 代码，请参阅 /examples/platform_channel_swift/。

首先创建一个新的应用：

在终端中运行：flutter create batterylevel

默认情况下，我们的模板使用 Kotlin 编写 Android 或使用 Swift 编写 iOS 代码。要使用 Java 或 Objective-C，请使用 -i 和/或 -a 标志：

在终端中运行：flutter create -i objc -a java batterylevel

应用程序的 State 类保持当前应用的状态。扩展它以保持当前的电池状态。

首先，构建通道。在返回电池电量的单一平台方法中使用 MethodChannel。

通道的客户端和宿主端通过传递给通道构造函数的通道名称进行连接。一个应用中所使用的所有通道名称必须是唯一的；使用唯一的 域前缀 为通道名称添加前缀，比如：samples.flutter.dev/battery。

接下来，在方法通道上调用方法（指定通过 String 标识符 getBatteryLevel 调用的具体方法）。调用可能会失败—比如，如果平台不支持此平台 API（比如在模拟器中运行），所以将 invokeMethod 调用包裹在 try-catch 语句中。

在 setState 中使用返回结果来更新 _batteryLevel 内的用户界面状态。

最后，将模板中的 build 方法替换为包含以字符串形式显示电池状态、并包含一个用于刷新该值的按钮的小型用户界面。

首先在 Android Studio 中打开 Flutter 应用的 Android 宿主部分：

启动 Android Studio

选择菜单项 File > Open…

导航到包含 Flutter 应用的目录，然后选择其中的 android 文件夹。点击 OK。

在项目视图中打开 kotlin 文件夹下的 MainActivity.kt 文件。

在 configureFlutterEngine() 方法中创建一个 MethodChannel 并调用 setMethodCallHandler()。确保使用的通道名称与 Flutter 客户端使用的一致。

添加使用 Android battery API 来检索电池电量的 Android Kotlin 代码。该代码与你在原生 Android 应用中编写的代码完全相同。

首先在文件头部添加所需的依赖：

然后在 MainActivity 类中的 configureFlutterEngine() 方法下方添加以下新方法：

最后，完成前面添加的 onMethodCall() 方法。你需要处理单个平台方法 getBatteryLevel()，所以在参数 call 中对其进行验证。该平台方法的实现是调用上一步编写的 Android 代码，并使用 result 参数来返回成功和错误情况下的响应。如果调用了未知方法，则报告该方法。

删除以下代码：

并替换成以下内容：

首先在 Android Studio 中打开 Flutter 应用的 Android 宿主部分：

启动 Android Studio

选择菜单项 File > Open…

导航到包含 Flutter 应用的目录，然后选择其中的 android 文件夹。点击 OK。

在项目视图中打开 java 文件夹下的 MainActivity.java 文件。

接下来，在 configureFlutterEngine() 方法中创建一个 MethodChannel 并设置一个 MethodCallHandler。确保使用的通道名称与 Flutter 客户端使用的一致。

添加使用 Android battery API 来检索电池电量的 Android Java 代码。该代码与你在原生 Android 应用中编写的代码完全相同。

首先在文件头部添加所需的依赖：

然后在 Activity 类中的 onCreate() 方法下方添加以下新方法：

最后，完成前面添加的 onMethodCall() 方法，你需要处理单个平台方法 getBatteryLevel()，所以在参数 call 中对其进行验证。该平台方法的实现是调用上一步编写的 Android 代码，并使用 result 参数来返回成功和错误情况下的响应。如果调用了未知方法，则报告该方法。

移除以下代码：

并替换成以下内容：

现在你应该可以在 Android 中运行该应用。如果使用了 Android 模拟器，请在扩展控件面板中设置电池电量，可从工具栏中的 … 按钮访问。

首先在 Xcode 中打开 Flutter 应用的 iOS 宿主部分：

启动 Xcode

选择菜单项 File > Open…

导航到包含 Flutter 应用的目录，然后选择其中的 ios 文件夹。点击 OK。

在使用 Objective-C 的标准模板设置中添加对 Swift 的支持：

在项目导航中展开 Expand Runner > Runner。

打开项目导航 Runner > Runner 下的 AppDelegate.swift 文件。

重写 application:didFinishLaunchingWithOptions: 方法，然后创建一个 FlutterMethodChannel 绑定到名字为 samples.flutter.dev/battery 名称的 channel：

然后，添加 iOS Swift 代码，使用电池相关的 API 获取电量。这里的代码和你写原生 iOS 代码别无二致。

在 AppDelegate.swift 末尾添加以下新的方法：

最后，完成前面添加的 setMethodCallHandler() 方法。你需要处理单个平台方法 getBatteryLevel()，所以在参数 call 中对其进行验证。该平台方法的实现是调用上一步编写的 iOS 代码。如果调用了未知方法，则报告该方法。

首先在 Xcode 中打开 Flutter 应用的 iOS 宿主部分：

启动 Xcode

选择菜单项 File > Open…

导航到包含 Flutter 应用的目录，然后选择其中的 ios 文件夹。点击 OK。

确保 Xcode 项目构建没有错误。

打开项目导航 Runner > Runner 下的 AppDelegate.m 文件。

在 application didFinishLaunchingWithOptions: 方法中创建一个 FlutterMethodChannel 并添加一个处理程序。确保使用的通道名称与 Flutter 客户端使用的一致。

接下来添加使用 iOS battery API 来检索电池电量的 iOS Objective-C 代码。该代码与你在原生 iOS 应用中编写的代码完全相同。

在 AppDelegate 类中的 @end 之前添加以下方法：

最后，完成前面添加的 setMethodCallHandler() 方法。你需要处理单个平台方法 getBatteryLevel()，所以在参数call 中对其进行验证。该平台方法的实现是调用上一步编写的 iOS 代码，并使用 result 参数来返回成功和错误情况下的响应。如果调用了未知方法，则报告该方法。

现在你应该可以在 iOS 中运行该应用。如果使用了 iOS 模拟器（注意它并不支持 battery API），应用则会显示 ‘battery info unavailable’。

首先在 Visual Studio 中打开你 Flutter 应用 Windows 的 host 部分：

在你项目的目录夹下运行一次 flutter build windows 以生成 Visual Studio solution 文件。

启动 Visual Studio。

选择 Open a project or solution

导航至含有你 Flutter 应用的目录下，然后进入 build 文件夹，然后是 windows 文件夹，然后选择 batterylevel.sln 文件，点击 Open。

然后添加 platform channel 方法的 c++ 实现：

在 Solution 浏览器中展开 batterylevel > Source Files

打开 flutter_window.cpp。

首先，在文件的最顶部添加必要的引用，在 #include "flutter_window.h" 下面写上就行：

编辑 FlutterWindow::OnCreate 方法，然后创建一个 flutter::MethodChannel 绑定 samples.flutter.dev/battery 名字：

接下来添加使用 Windows battery API 来检索电池电量的代码。该代码与你在原生 Windows 应用中编写代码别无二致。

在 flutter_window.cpp 顶部添加下面的新方法，在 #include 下面添加：

最后，完成 setMethodCallHandler() 方法。你可以在这里处理平台方法，getBatteryLevel()，然后可以在 call 参数中进行测试。这个平台方法调用的实现，在之前的步骤中已经完成了。如果调用了一个未知的，请报告它。

移除下面的代码：

然后替换为这个：

You should now be able to run the application on Windows. If your device doesn’t have a battery, it displays ‘Battery level not available’.

For this example you need to install the upower developer headers. This is likely available from your distribution, for example with:

Start by opening the Linux host portion of your Flutter app in the editor of your choice. The instructions below are for Visual Studio Code with the “C/C++” and “CMake” extensions installed, but can be adjusted for other IDEs.

Launch Visual Studio Code.

Open the linux directory inside your project.

Choose Yes in the prompt asking: Would you like to configure project "linux"?. This enables C++ autocomplete.

Open the file my_application.cc.

First, add the necessary includes to the top of the file, just after #include dart_entrypoint_arguments, g_strfreev); g_clear_object(&self->battery_channel); G_OBJECT_CLASS(my_application_parent_class)->dispose(object); }

Edit the my_application_activate method and initialize battery_channel using the channel name samples.flutter.dev/battery, just after the call to fl_register_plugins:

Next, add the C code that uses the Linux battery APIs to retrieve the battery level. This code is exactly the same as you would write in a native Linux application.

Add the following as a new function at the top of my_application.cc just after the G_DEFINE_TYPE line:

Finally, add the battery_method_call_handler function referenced in the earlier call to fl_method_channel_set_method_call_handler. You need to handle a single platform method, getBatteryLevel, so test for that in the method_call argument. The implementation of this function calls the Linux code written in the previous step. If an unknown method is called, report that instead.

Add the following code after the get_battery_level function:

你现在应该可以在 Windows 上运行应用了。如果你的设备没有电池的话，它会提示 ‘Battery level not available’。

在之前的样例中，我们使用 MethodChannel 在 host 和 client 之间进行通信，然而这并不是类型安全的。为了正确通信，调用/接收消息取决于 host 和 client 声明相同的参数和数据类型。 Pigeon 包可以用作 MethodChannel 的替代品，它将生成以结构化类型安全方式发送消息的代码。

在 Pigeon 中，消息接口在 Dart 中进行定义，然后它将生成对应的 Android 以及 iOS 的代码。更复杂的例子以及更多信息尽在 pigeon。

使用 Pigeon 消除了在主机和客户端之间匹配字符串的需要消息的名称和数据类型。它支持：嵌套类，消息转换为 API，生成异步包装代码并发送消息。生成的代码具有相当的可读性并保证在不同版本的多个客户端之间没有冲突。支持 Objective-C，Java，Kotlin 和 Swift（通过 Objective-C 互操作）语言。

Pigeon 文件:

Dart 用法:

如果你想要在多个 Flutter 应用中使用你的平台相关代码，则将代码分离为位于主应用目录之外的平台插件会很有用。相关细节查看 Flutter Packages 的开发和提交。

与 Flutter 生态中的其他开发者共享你的平台相关代码，可查看 提交 package。

除了上面提到的 MethodChannel，你还可以使用更基础的 BasicMessageChannel，它支持使用自定义的消息编解码器进行基本的异步消息传递。你还可以使用专门的 BinaryCodec、StringCodec 和 JSONMessageCodec 类，或创建自己的编解码器。

您还可以在 cloud_firestore 插件中查看自定义编解码器的示例，该插件可以序列化和反序列化比默认类型更多的类型。

目标平台向 Flutter 发起 channel 调用的时候，需要在对应平台的主线程执行。同样的，在 Flutter 向目标平台发起 channel 调用的时候，需要在根 Isolate 中执行。对应平台侧的 handler 既可以在平台的主线程执行，也可以通过事件循环在后台执行。对应平台侧 handler 的返回值可以在任意线程异步执行。

提示

在 2.10 正式版中，Task Queue API 在 Android 上已经可以使用，若要在 iOS 上使用，需要切换到 master 渠道。

提示

在 Android 平台上时，平台的 main 线程有时候被叫做主线程，但是它在技术上被看作 UI 线程。被 @UiThread 注解标记的方法需要在 UI 线程上执行。在 iOS 上，这个线程被官方标记为主线程。

Plugins and channels can be used by any Isolate, but that Isolate has to be a root Isolate (the one created by Flutter) or registered as a background Isolate for a root Isolate.

The following example shows how to register a background Isolate in order to use a plugin from a background Isolate.

要在 channel 对应的平台侧的后台中执行 handler，需要使用 Task Queue API。当前该功能仅支持在 iOS 和 Android。

对应的 Java 代码：

Kotlin 版本：

Swift 版本：

提示

在 2.10 的发布中，若要在 iOS 上使用 Task Queue API，只能切换到 master 渠道。

Objective-C 版本：

提示

在 2.10 的发布中，若要在 iOS 上使用 Task Queue API，只能切换到 master 渠道。

为了符合通道跳转到 Android UI 线程的要求，你可能需要从后台线程跳转到 Android 的 UI 线程以执行通道的方法。在 Android 中的实现方式是：在一个叫 Looper 的 Android UI 线程里 post() 一个 Runnable。这能使得 Runnable 在下一次机会时在主线程上执行。

Java 代码：

Kotlin 代码：

为了符合通道跳转到 iOS 主线程的要求，您可能需要从后台线程跳转到 iOS 的主线程来执行通道方法。在iOS中，这是通过在主 dispatch queue上执行 block来实现的：

Objective-C 代码：

Swift 代码：