本指南介绍了如何编写自定义的平台相关代码，某些平台相关功能可通过已有的软件包获得，具体细节可查看： 在 Flutter 里使用 Packages。
提示
本页面的内容适用于大多数平台，但 Web 插件的实现一般都是通过 [JS 交互](https://dart.cn/web/js-interop) 或者 [`dart:html` 库](https://api.dart.cn/dart-html/dart-html-library.html) 实现的。
复制代码Flutter 使用了灵活系统，无论是在 Android 上的 Kotlin 还是 Java，亦或是 iOS 上的 Swift 或 Objective-C，它都允许你调用平台特定 API。
Flutter 内置的平台特定 API 支持不依赖于任何生成代码，而是灵活的依赖于传递消息格式。或者，你也可以使用 Pigeon 这个 package，通过生成代码来 发送结构化类型安全消息。
如果你需要在 Java/Kotlin/Objective-C 或 Swift 中使用平台的 API 或库，本指南将使用平台通道机制。但你也可以通过检查 Flutter 应用程序中的 [defaultTargetPlatform](https://api.flutter-io.cn/flutter/foundation/defaultTargetPlatform.html) 属性来编写相关平台的 Dart 代码。 [不同平台操作体验的差异和适配](https://flutter.cn/docs/resources/platform-adaptations) 文档中列出了 Flutter 框架自动为你执行的一些相关平台适配。
复制代码架构概述：平台通道
消息使用平台通道在客户端（UI）和宿主（平台）之间传递，如下图所示：
消息和响应以异步的形式进行传递，以确保用户界面能够保持响应。
Flutter 是通过 Dart 异步发送消息的。即便如此，当你调用一个平台方法时，也需要在主线程上做调用。在 [这里](https://flutter.cn/docs/development/platform-integration/platform-channels#channels-and-platform-threading) 查看更多。
复制代码客户端做方法调用的时候 MethodChannel 会负责响应，从平台一侧来讲，Android 系统上使用 MethodChannelAndroid、 iOS 系统使用 MethodChanneliOS 来接收和返回来自 MethodChannel 的方法调用。在开发平台插件的时候，可以减少样板代码。
如果需要，方法调用也可以反向发送，由平台充当客户端来调用 Dart 实现的方法。一个具体的例子是 [`quick_actions`](https://pub.flutter-io.cn/packages/quick_actions) 插件。
复制代码平台通道数据类型及编解码器
标准平台通道使用标准消息编解码器，它支持简单的类似 JSON 值的高效二进制序列化，例如布尔值、数字、字符串、字节缓冲区及这些类型的列表和映射（详情请参阅 StandardMessageCodec）。当你发送和接收值时，它会自动对这些值进行序列化和反序列化。
下表展示了如何在平台端接收 Dart 值，反之亦然：
Dart | Java | Kotlin | Obj-C | Swift |
| -------------------------- | ------------------- | ----------- | ---------------------------------------------- | --------------------------------------- |
| null | null | null | nil (NSNull when nested) | nil |
| bool | java.lang.Boolean | Boolean | NSNumber numberWithBool: | NSNumber(value: Bool) |
| int | java.lang.Integer | Int | NSNumber numberWithInt: | NSNumber(value: Int32) |
| int, if 32 bits not enough | java.lang.Long | Long | NSNumber numberWithLong: | NSNumber(value: Int) |
| double | java.lang.Double | Double | NSNumber numberWithDouble: | NSNumber(value: Double) |
| String | java.lang.String | String | NSString | String |
| Uint8List | byte[] | ByteArray | FlutterStandardTypedData typedDataWithBytes: | FlutterStandardTypedData(bytes: Data) |
| Int32List | int[] | IntArray | FlutterStandardTypedData typedDataWithInt32: | FlutterStandardTypedData(int32: Data) |
| Int64List | long[] | LongArray | FlutterStandardTypedData typedDataWithInt64: | FlutterStandardTypedData(int64: Data) |
| Float32List | float[] | FloatArray | FlutterStandardTypedData typedDataWithFloat32: | FlutterStandardTypedData(float32: Data) |
| Float64List | double[] | DoubleArray | FlutterStandardTypedData typedDataWithFloat64: | FlutterStandardTypedData(float64: Data) |
| List | java.util.ArrayList | List | NSArray | Array |
| Map | java.util.HashMap | HashMap | NSDictionary | Dictionary |
复制代码示例: 通过平台通道调用平台的 iOS 和 Android 代码
以下代码演示了如何调用平台相关 API 来检索并显示当前的电池电量。它通过平台消息 getBatteryLevel() 来调用 Android 的 BatteryManager API 及 iOS 的 device.batteryLevel API。
该示例在主应用程序中添加平台相关代码。如果想要将该代码重用于多个应用程序，那么项目的创建步骤将略有差异（查看 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
第二步：创建 Flutter 平台客户端
应用程序的 State 类保持当前应用的状态。扩展它以保持当前的电池状态。
首先，构建通道。在返回电池电量的单一平台方法中使用 MethodChannel。
通道的客户端和宿主端通过传递给通道构造函数的通道名称进行连接。一个应用中所使用的所有通道名称必须是唯一的；使用唯一的 域前缀 为通道名称添加前缀，比如：samples.flutter.dev/battery。
import 'dart:async';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
...
class _MyHomePageState extends State<MyHomePage> {
static const platform = MethodChannel('samples.flutter.dev/battery');
// Get battery level.
}
复制代码接下来，在方法通道上调用方法（指定通过 String 标识符 getBatteryLevel 调用的具体方法）。调用可能会失败—比如，如果平台不支持此平台 API（比如在模拟器中运行），所以将 invokeMethod 调用包裹在 try-catch 语句中。
在 setState 中使用返回结果来更新 _batteryLevel 内的用户界面状态。
// Get battery level.
String _batteryLevel = 'Unknown battery level.';
Future<void> _getBatteryLevel() async {
String batteryLevel;
try {
final int result = await platform.invokeMethod('getBatteryLevel');
batteryLevel = 'Battery level at $result % .';
} on PlatformException catch (e) {
batteryLevel = "Failed to get battery level: '${e.message}'.";
}
setState(() {
_batteryLevel = batteryLevel;
});
}
复制代码最后，将模板中的 build 方法替换为包含以字符串形式显示电池状态、并包含一个用于刷新该值的按钮的小型用户界面。
@override
Widget build(BuildContext context) {
return Material(
child: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.spaceEvenly,
children: [
ElevatedButton(
child: Text('Get Battery Level'),
onPressed: _getBatteryLevel,
),
Text(_batteryLevel),
],
),
),
);
}
复制代码步骤 3: 添加 Android 平台的实现
首先在 Android Studio 中打开 Flutter 应用的 Android 宿主部分：
- 启动 Android Studio
- 选择菜单项 File > Open…
- 导航到包含 Flutter 应用的目录，然后选择其中的 android 文件夹。点击 OK。
- 在项目视图中打开 java 文件夹下的
MainActivity.java文件。
接下来，在 configureFlutterEngine() 方法中创建一个 MethodChannel 并设置一个 MethodCallHandler。确保使用的通道名称与 Flutter 客户端使用的一致。
import androidx.annotation.NonNull;
import io.flutter.embedding.android.FlutterActivity;
import io.flutter.embedding.engine.FlutterEngine;
import io.flutter.plugin.common.MethodChannel;
public class MainActivity extends FlutterActivity {
private static final String CHANNEL = "samples.flutter.dev/battery";
@Override
public void configureFlutterEngine(@NonNull FlutterEngine flutterEngine) {
super.configureFlutterEngine(flutterEngine);
new MethodChannel(flutterEngine.getDartExecutor().getBinaryMessenger(), CHANNEL)
.setMethodCallHandler(
(call, result) -> {
// Note: this method is invoked on the main thread.
// TODO
}
);
}
}
复制代码添加使用 Android battery API 来检索电池电量的 Android Java 代码。该代码与你在原生 Android 应用中编写的代码完全相同。
首先在文件头部添加所需的依赖：
import android.content.ContextWrapper;
import android.content.Intent;
import android.content.IntentFilter;
import android.os.BatteryManager;
import android.os.Build.VERSION;
import android.os.Build.VERSION_CODES;
import android.os.Bundle;
复制代码然后在 Activity 类中的 onCreate() 方法下方添加以下新方法：
private int getBatteryLevel() {
int batteryLevel = -1;
if (VERSION.SDK_INT >= VERSION_CODES.LOLLIPOP) {
BatteryManager batteryManager = (BatteryManager) getSystemService(BATTERY_SERVICE);
batteryLevel = batteryManager.getIntProperty(BatteryManager.BATTERY_PROPERTY_CAPACITY);
} else {
Intent intent = new ContextWrapper(getApplicationContext()).
registerReceiver(null, new IntentFilter(Intent.ACTION_BATTERY_CHANGED));
batteryLevel = (intent.getIntExtra(BatteryManager.EXTRA_LEVEL, -1) * 100) /
intent.getIntExtra(BatteryManager.EXTRA_SCALE, -1);
}
return batteryLevel;
}
复制代码最后，完成前面添加的 onMethodCall() 方法，你需要处理单个平台方法 getBatteryLevel()，所以在参数 call 中对其进行验证。该平台方法的实现是调用上一步编写的 Android 代码，并使用 result 参数来返回成功和错误情况下的响应。如果调用了未知方法，则报告该方法。
(call, result) -> {
// Note: this method is invoked on the main thread.
// TODO
}
复制代码并替换成以下内容：
(call, result) -> {
// Note: this method is invoked on the main thread.
if (call.method.equals("getBatteryLevel")) {
int batteryLevel = getBatteryLevel();
if (batteryLevel != -1) {
result.success(batteryLevel);
} else {
result.error("UNAVAILABLE", "Battery level not available.", null);
}
} else {
result.notImplemented();
}
}
复制代码现在你应该可以在 Android 中运行该应用。如果使用了 Android 模拟器，请在扩展控件面板中设置电池电量，可从工具栏中的 … 按钮访问。
步骤 4a：添加 iOS 平台的实现
首先在 Xcode 中打开 Flutter 应用的 iOS 宿主部分：
- 启动 Xcode
- 选择菜单项 File > Open…
- 导航到包含 Flutter 应用的目录，然后选择其中的 ios 文件夹。点击 OK。
- 确保 Xcode 项目构建没有错误。
- 打开项目导航 Runner > Runner 下的
AppDelegate.m文件。
在 application didFinishLaunchingWithOptions: 方法中创建一个 FlutterMethodChannel 并添加一个处理程序。确保使用的通道名称与 Flutter 客户端使用的一致。
content_copy
#import <Flutter/Flutter.h>
#import "GeneratedPluginRegistrant.h"
@implementation AppDelegate
- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions {
FlutterViewController* controller = (FlutterViewController*)self.window.rootViewController;
FlutterMethodChannel* batteryChannel = [FlutterMethodChannel
methodChannelWithName:@"samples.flutter.dev/battery"
binaryMessenger:controller.binaryMessenger];
[batteryChannel setMethodCallHandler:^(FlutterMethodCall* call, FlutterResult result) {
// Note: this method is invoked on the UI thread.
// TODO
}];
[GeneratedPluginRegistrant registerWithRegistry:self];
return [super application:application didFinishLaunchingWithOptions:launchOptions];
}
复制代码接下来添加使用 iOS battery API 来检索电池电量的 iOS Objective-C 代码。该代码与你在原生 iOS 应用中编写的代码完全相同。
在 AppDelegate 类中的 @end 之前添加以下方法：
content_copy
- (int)getBatteryLevel {
UIDevice* device = UIDevice.currentDevice;
device.batteryMonitoringEnabled = YES;
if (device.batteryState == UIDeviceBatteryStateUnknown) {
return -1;
} else {
return (int)(device.batteryLevel * 100);
}
}
复制代码最后，完成前面添加的 setMethodCallHandler() 方法。你需要处理单个平台方法 getBatteryLevel()，所以在参数call 中对其进行验证。该平台方法的实现是调用上一步编写的 iOS 代码，并使用 result 参数来返回成功和错误情况下的响应。如果调用了未知方法，则报告该方法。
content_copy
__weak typeof(self) weakSelf = self;
[batteryChannel setMethodCallHandler:^(FlutterMethodCall* call, FlutterResult result) {
// Note: this method is invoked on the UI thread.
if ([@"getBatteryLevel" isEqualToString:call.method]) {
int batteryLevel = [weakSelf getBatteryLevel];
if (batteryLevel == -1) {
result([FlutterError errorWithCode:@"UNAVAILABLE"
message:@"Battery info unavailable"
details:nil]);
} else {
result(@(batteryLevel));
}
} else {
result(FlutterMethodNotImplemented);
}
}];
复制代码现在你应该可以在 iOS 中运行该应用。如果使用了 iOS 模拟器，注意它并不支持 battery API，并且应用会显示 ‘battery info unavailable’。
步骤 4b：使用 Swift 添加 iOS 平台的实现
注意：以下步骤与 4a 类似，唯一的区别是使用了 Swift 而非 Objective-C。
此步骤假设你在第一步中使用 -i swift 选项创建了项目。
现在你应该可以在 iOS 中运行该应用。如果使用了 iOS 模拟器，注意它并不支持 battery API，并且应用会显示 ‘battery info unavailable’。
You should now be able to run the app on iOS. If using the iOS Simulator, note that it does not support battery APIs, and the app displays ‘battery info unavailable’.
通过 Pigeon 获得类型安全的通道
在之前的样例中，我们使用 MethodChannel 在 host 和 client 之间进行通信，然而这并不是类型安全的。为了正确通信，调用/接收消息取决于 host 和 client 声明相同的参数和数据类型。 Pigeon 包可以用作 MethodChannel 的替代品，它将生成以结构化类型安全方式发送消息的代码。
在 Pigeon 中，消息接口在 Dart 中进行定义，然后它将生成对应的 Android 以及 iOS 的代码。更复杂的例子以及更多信息尽在 Pigeon pub.dev page。
使用 Pigeon 消除了在主机和客户端之间匹配字符串的需要消息的名称和数据类型。它支持：嵌套类，消息转换为 API，生成异步包装代码并发送消息。生成的代码具有相当的可读性并保证在不同版本的多个客户端之间没有冲突。支持 Objective-C，Java，Kotlin 和 Swift（通过 Objective-C 互操作）语言。
Pigeon 样例
Pigeon example
Pigeon file:
content_copy
import 'package:pigeon/pigeon.dart';
class SearchRequest {
String query;
}
class SearchReply {
String result;
}
@HostApi()
abstract class Api {
SearchReply search(SearchRequest request);
}
复制代码Dart usage:
content_copy
import 'generated_pigeon.dart'
void onClick() async {
SearchRequest request = SearchRequest()..query = 'test';
Api api = Api();
SearchReply reply = await api.search(request);
print('reply: ${reply.result}');
}
复制代码从 UI 代码中分离平台相关代码
如果你想要在多个 Flutter 应用中使用你的平台相关代码，则将代码分离为位于主应用目录之外的平台插件会很有用。相关细节查看 Flutter Packages 的开发和提交。
将平台相关代码作为 Package 进行提交
与 Flutter 生态中的其他开发者共享你的平台相关代码，可查看 提交 package。
自定义通道和编解码器
除了上面提到的 MethodChannel，你还可以使用更基础的 BasicMessageChannel，它支持使用自定义的消息编解码器进行基本的异步消息传递。你还可以使用专门的 BinaryCodec、StringCodec 和 JSONMessageCodec 类，或创建自己的编解码器。
您还可以在 cloud_firestore 插件中查看自定义编解码器的示例，该插件可以序列化和反序列化比默认类型更多的类型。
通道和平台线程
在平台端编写代码时，请调用平台主线程上的所有通道方法。在 Android上，该线程有时称为「主线程」，但从技术上讲，它被称之为 UI 线程。用 @UiThread 注释需要在UI线程上运行的方法。在iOS上，此线程称为 主线程。
跳转到 Android 中的 UI 线程
为了符合通道跳转到 Android UI 线程的要求，你可能需要从后台线程跳转到 Android 的 UI 线程以执行通道的方法。在 Android 中的实现方式是：在一个叫 Looper 的 Android UI 线程里 post() 一个 Runnable。这能使得 Runnable 在下一次机会时在主线程上执行。
Java 代码：
content_copy
new Handler(Looper.getMainLooper()).post(new Runnable() {
@Override
public void run() {
// Call the desired channel message here.
}
});
复制代码Kotlin 代码：
content_copy
Handler(Looper.getMainLooper()).post {
// Call the desired channel message here.
}
复制代码跳转到 iOS 中的主线程
为了符合通道跳转到 iOS 主线程的要求，您可能需要从后台线程跳转到 iOS 的主线程来执行通道方法。在iOS中，这是通过在主 dispatch queue上执行 block来实现的：
Objective-C 代码：
content_copy
dispatch_async(dispatch_get_main_queue(), ^{
// Call the desired channel message here.
});
复制代码Swift 代码：
content_copy
DispatchQueue.main.async {
// Call the desired channel message here.
}
复制代码