平台通道与原生互操作:MethodChannel / EventChannel
第 15 章 · 平台通道与原生互操作:MethodChannel / EventChannel
run
$cd examples/ch15-platform-channels && flutter run -d macos已验证
- flutter analyze 0 告警、flutter test 10 个用例全绿、flutter build macos --debug 真实构建
- 完整工程已打包:打包下载
本章目录 · 13 节
15.1 本章目标
- 分清三种通道:
MethodChannel(请求-响应)、EventChannel(原生推流)、BasicMessageChannel(原始消息); - 会写 Dart 侧与 macOS(Swift) / Android(Kotlin) / iOS(Swift) 侧的实现,并知道通道名是唯一契约;
- 掌握错误语义:
PlatformException、MissingPluginException、notImplemented; - 会用 mock 把通道测试变成纯 Dart 测试;
- 知道平台通道和 FFI(ch10)各自适合什么场景;
- 知道线程规则:通道调用在哪个线程执行、UI 线程上不能做什么。
15.2 三种通道
| 通道 | 方向 | 语义 | 典型用途 |
|---|---|---|---|
MethodChannel |
Dart → 原生 → Dart | 一问一答 | 调系统 API:读取设备信息、打开相机、申请权限 |
EventChannel |
原生 → Dart(流) | 原生主动推事件 | 传感器、定位、蓝牙、电池状态 |
BasicMessageChannel |
双向 | 原始消息(自定义编解码) | 高频/自定义协议、插件间通信 |
三者都建立在**二进制消息(binary messenger)**之上,默认用 StandardMessageCodec,支持的类型是固定的一组:
| 支持 | 不支持 |
|---|---|
null、bool、int(≤64 位)、double、String |
自定义类(要自己转 Map) |
Uint8List(推荐用于二进制) |
List<int> 会作为 List<Object?> 传(不是 Uint8List) |
List<Object?>、Map<Object?, Object?> |
DateTime、枚举、record |
所以通道参数/返回值里的"业务对象"必须手动转成 Map。这也是平台通道比 FFI 慢的原因之一(序列化 + 拷贝)。
15.3 Dart 侧:请求-响应与事件流
// examples/ch15-platform-channels/lib/src/platform_service.dart
const String kDeviceChannel = 'ch15.platform/device';
const String kTicksChannel = 'ch15.platform/ticks';
class PlatformService {
PlatformService({MethodChannel? methodChannel, EventChannel? eventChannel})
: _method = methodChannel ?? const MethodChannel(kDeviceChannel),
_events = eventChannel ?? const EventChannel(kTicksChannel);
Future<PlatformInfo> getPlatformInfo() async {
try {
final Object? result = await _method.invokeMethod<Object?>('getPlatformInfo');
if (result is! Map<Object?, Object?>) throw const FormatException('原生返回的不是 Map');
return PlatformInfo.fromMap(result);
} on MissingPluginException {
throw const PlatformUnsupportedException(kDeviceChannel, 'getPlatformInfo');
} on PlatformException catch (e) {
throw PlatformUnsupportedException(kDeviceChannel, '${e.code}: ${e.message}');
}
}
Stream<int> ticks() => _events.receiveBroadcastStream().map((Object? event) {
if (event is int) return event;
throw FormatException('ticks 事件应为 int,实际是 ${event.runtimeType}');
});
}
要点:
- 方法名与通道名是字符串契约,Dart 拼错只有运行时才发现。把名字集中成常量(本例),并用测试兜住。
invokeMethod<T>的T只是类型提示,实际返回值仍是Object?;类型不对要自己判(本例is! Map→FormatException)。MissingPluginException表示"当前平台没有实现这个通道"——桌面/移动共用一套 Dart 代码时,这是正常情况,要翻译成"功能不可用",而不是崩溃。PlatformException是原生主动抛的(result.error(...)),带code/message/details。receiveBroadcastStream()内部会向原生发listen,cancel订阅时发cancel。必须取消,否则原生的定时器/传感器永远不停(ch06 的老规矩)。
另一种写法是
setMethodCallHandler在 Dart 侧响应原生调用(原生 → Dart)。场景是"原生事件回调进 Dart",但绝大多数情况用EventChannel更清晰。
15.4 macOS 实现(本章真实验证的部分)
// examples/ch15-platform-channels/macos/Runner/MainFlutterWindow.swift
let messenger = flutterViewController.engine.binaryMessenger
let deviceChannel = FlutterMethodChannel(name: "ch15.platform/device", binaryMessenger: messenger)
deviceChannel.setMethodCallHandler { [weak self] call, result in
switch call.method {
case "getPlatformInfo":
let v = ProcessInfo.processInfo.operatingSystemVersion
result([
"os": "macOS",
"version": "\(v.majorVersion).\(v.minorVersion).\(v.patchVersion)",
"arch": MainFlutterWindow.archName(),
"isDarkMode": self?.isDarkMode() ?? false,
])
case "vibrate":
NSSound.beep() // 桌面没有振动马达,用提示音代替
result(nil)
default:
result(FlutterMethodNotImplemented) // → Dart 收到 MissingPluginException
}
}
let ticksChannel = FlutterEventChannel(name: "ch15.platform/ticks", binaryMessenger: messenger)
ticksChannel.setStreamHandler(TickStreamHandler())
FlutterStreamHandler 的两个回调就是事件源的生命周期:
final class TickStreamHandler: NSObject, FlutterStreamHandler {
private var timer: Timer?
private var count = 0
func onListen(withArguments arguments: Any?, eventSink events: @escaping FlutterEventSink) -> FlutterError? {
count = 0
timer?.invalidate()
timer = Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { [weak self] _ in
guard let self else { return }
self.count += 1
events(self.count)
if self.count >= 5 {
self.stop()
events(FlutterEndOfEventStream) // 主动结束
}
}
return nil
}
func onCancel(withArguments arguments: Any?) -> FlutterError? {
stop() // 不 stop → 定时器永远跑
return nil
}
...
}
真实验证(flutter run -d macos 的日志):
flutter: platform info: macOS 27.2.1 (arm64)
这行来自 Dart 侧的 debugPrint,而数据来自 Swift 的 ProcessInfo——证明整条通道链路是通的。界面上还能看到:OS/版本/架构、系统深色模式、每秒 +1 的事件计数(到 5 后流结束)。
15.5 Android 实现
// examples/ch15-platform-channels/android/app/src/main/kotlin/.../MainActivity.kt
override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
super.configureFlutterEngine(flutterEngine)
val messenger = flutterEngine.dartExecutor.binaryMessenger
MethodChannel(messenger, "ch15.platform/device").setMethodCallHandler { call, result ->
when (call.method) {
"getPlatformInfo" -> result.success(mapOf(
"os" to "Android",
"version" to Build.VERSION.RELEASE,
"arch" to (Build.SUPPORTED_ABIS.firstOrNull() ?: "unknown"),
"isDarkMode" to isNightMode(),
))
"vibrate" -> result.success(null)
else -> result.notImplemented()
}
}
EventChannel(messenger, "ch15.platform/ticks").setStreamHandler(
object : EventChannel.StreamHandler {
private var handler: Handler? = null
private var count = 0
override fun onListen(arguments: Any?, events: EventChannel.EventSink?) { /* 起定时器 */ }
override fun onCancel(arguments: Any?) { handler?.removeCallbacksAndMessages(null) }
}
)
}
| 概念 | macOS(Swift) | Android(Kotlin) | iOS(Swift) |
|---|---|---|---|
| Messenger | engine.binaryMessenger |
dartExecutor.binaryMessenger |
registrar.messenger() |
| 返回成功 | result(value) |
result.success(value) |
result(value) |
| 返回错误 | FlutterError |
result.error(code, msg, details) |
FlutterError |
| 未实现 | FlutterMethodNotImplemented |
result.notImplemented() |
FlutterMethodNotImplemented |
| 事件回调 | FlutterEventSink 闭包 |
EventChannel.EventSink |
FlutterEventSink |
| 结束流 | FlutterEndOfEventStream |
events.endOfStream() |
FlutterEndOfEventStream |
| 主线程 | 方法回调在 main | 方法回调在 main(UI)线程 | 在 main |
本机限制:本章只在 macOS 上构建/运行验证过。Android 与 iOS 代码是同构写法,但没有真机验证(AGENTS.md §7.5 的要求是给出实现并标注适用平台)。iOS 侧参考实现:
// ios/Runner/AppDelegate.swift(scene-based 模板,仅供参考,本机未编译验证)
func didInitializeImplicitFlutterEngine(_ engineBridge: FlutterImplicitEngineBridge) {
GeneratedPluginRegistrant.register(with: engineBridge.pluginRegistry)
guard let registrar = engineBridge.pluginRegistry.registrar(forPlugin: "Ch15Channels") else { return }
let channel = FlutterMethodChannel(name: "ch15.platform/device", binaryMessenger: registrar.messenger())
channel.setMethodCallHandler { call, result in
switch call.method {
case "getPlatformInfo":
result(["os": "iOS", "version": UIDevice.current.systemVersion,
"arch": "arm64", "isDarkMode": false])
default:
result(FlutterMethodNotImplemented)
}
}
}
15.6 测试:把通道 mock 掉
flutter_test 提供了拦截平台消息的钩子,不需要真机/桌面窗口:
// test/platform_channel_test.dart
void mockChannel(String name, Future<Object?> Function(MethodCall call) handler) {
TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
.setMockMethodCallHandler(MethodChannel(name), handler);
}
test('解析原生返回的 Map', () async {
mockChannel(kDeviceChannel, (MethodCall call) async {
expect(call.method, 'getPlatformInfo');
return <String, Object?>{'os': 'macOS', 'version': '27.2.1', 'arch': 'arm64'};
});
final PlatformInfo info = await PlatformService().getPlatformInfo();
expect(info.os, 'macOS');
});
EventChannel 的测试要多一步——模拟"原生主动推事件":
Future<void> emitEvent(int value) async {
await TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger.handlePlatformMessage(
kTicksChannel,
const StandardMethodCodec().encodeSuccessEnvelope(value),
(ByteData? _) {},
);
}
test('接收原生推送的多条事件', () async {
final calls = <String>[];
mockChannel(kTicksChannel, (MethodCall call) async { calls.add(call.method); return null; });
final received = <int>[];
final sub = PlatformService().ticks().listen(received.add);
await Future<void>.delayed(const Duration(milliseconds: 20));
expect(calls, contains('listen'));
await emitEvent(1); await emitEvent(2); await emitEvent(3);
expect(received, <int>[1, 2, 3]);
await sub.cancel();
await Future<void>.delayed(const Duration(milliseconds: 20));
expect(calls, contains('cancel')); // ★ 取消必须传到原生
});
三条测试原则:
- 断言双向契约:不仅断言 Dart 解析正确,也断言 Dart 真的发了
listen/cancel(原生靠它管生命周期)。 - 错误路径也要测:
PlatformException、MissingPluginException、返回类型不对。 - "原生未实现"是常态:同一份 Dart 跑在桌面和手机上,某个能力在平台上不存在时必须优雅降级(示例里显示"未实现"而不是红屏)。
实测坑:在测试里不注册任何 handler 时,
invokeMethod返回null而不是抛MissingPluginException(测试用 messenger 的默认行为)。因此 UI 必须有兜底的on Object catch,否则会以未捕获异常的形式炸掉。示例对_loadInfo做了两层 catch。
15.7 线程与生命周期
| 事项 | 规则 |
|---|---|
| 方法回调在哪个线程 | 平台主线程(Android/iOS/macOS 都是 UI 线程) |
| 能否在回调里做耗时操作 | 不能。5 秒的磁盘读会让界面卡住;用后台队列/isolate,完成后回主线程 result(...) |
Dart 侧 await invokeMethod |
不阻塞 Dart 事件循环(ch05),但原生侧是同步在处理 |
| 页面销毁时 | 取消 EventChannel 订阅;别在 await 之后碰已销毁的 State(mounted) |
| 通道对象 | MethodChannel 可以复用;EventChannel 每次 receiveBroadcastStream 是新的订阅 |
Dart 与原生不共享内存:参数会被编码成字节再解码,所以传 10MB 的 Uint8List 就是两次拷贝。大块数据要么传文件路径,要么走 FFI(零拷贝)。
15.8 平台通道 vs FFI:怎么选
| 需求 | 平台通道 | FFI |
|---|---|---|
| 调 Android SDK / iOS SDK(Java/Swift 对象) | ✅ 唯一选择 | ❌ 不行 |
| 复用 C/C++/Rust/Go 库 | ❌ 要包一层原生代码 | ✅ 直接调 |
| 每次调用开销 | 微秒~毫秒(序列化 + 线程切换) | 纳秒~微秒 |
| 大块二进制 | 拷贝代价高 | 可零拷贝(Pointer + asTypedList) |
| 崩溃隔离 | 原生崩溃带走整个 App | 同样带走 |
| 测试 | mock 通道(纯 Dart) | 必须构建原生库 |
经验:系统能力用通道,算法/性能用 FFI。两者可以在同一个插件里共存(插件 API 是 Dart,内部一部分走通道、一部分走 FFI)。
15.9 什么时候该抽成插件包
如果通道只服务这个 App,写在 MainActivity / MainFlutterWindow 里就行(本章做法)。要复用到多个 App 或开源,就抽成 Flutter plugin:
flutter create --template=plugin --platforms=android,ios,macos,linux,windows ch15_plugin
插件模板会生成各平台的 register 入口和 pubspec 的 plugin: 段,Dart 侧自动绑定各平台实现。代价是构建/发布流程更复杂(pigeon 可以帮忙生成类型安全的通道代码)。
15.10 调试技巧
| 现象 | 排查 |
|---|---|
MissingPluginException |
通道名拼错 / 原生没注册 / 热重载后原生代码未重建(要 R 或重启) |
| 原生代码不生效 | 改 Kotlin/Swift 后必须完全重启(热重载只重载 Dart) |
PlatformException |
看 code/message/details,原生侧 print/Log.d/NSLog |
| 事件流不动 | 原生 onListen 没被调用(通道名不一致)或没在主线程起定时器 |
| 界面卡顿 | 原生回调里做了耗时操作,挪到后台队列 |
15.11 运行与验证
cd examples/ch15-platform-channels
flutter pub get && flutter analyze && flutter test
flutter run -d macos # 真实调用 Swift
flutter build macos --debug
本次真实验证:
No issues found!
00:00 +10: All tests passed!
✓ Built build/macos/Build/Products/Debug/ch15_platform_channels.app
flutter: platform info: macOS 27.2.1 (arm64)
附:C/Go 代码对照:cgo 导出 vs 消息通道
// Go + cgo:同样跨语言,但走的是 C ABI 直调(ch10 的做法)
/*
#include <stdlib.h>
*/
import "C"
import "runtime"
//export GetPlatformInfo
func GetPlatformInfo() *C.char {
return C.CString(runtime.GOOS + " " + runtime.GOARCH)
}
// Flutter 平台通道:Dart 声明方法名,原生侧按名字分发并回消息
final info = await const MethodChannel('ch15.platform/device')
.invokeMethod<Map<Object?, Object?>>('getPlatformInfo');
| cgo / FFI | MethodChannel | |
|---|---|---|
| 对方是谁 | C ABI 动态库 | Kotlin / Swift 代码 |
| 参数 | C 类型(指针、整型) | 可序列化的消息(Map/List/String…) |
| 线程 | 调用方线程 | 平台主线程 |
| 适合 | 算法库、已有原生代码 | 系统 API、平台对象 |
Go 侧如果要暴露给 Flutter,本质上有两条路:编译成 c-shared 走 FFI,或者写 Android/iOS 插件走通道——通道不能直接调 Go。
15.12 本章小结 + C/Go 对照清单
| 主题 | C/Go 里的做法 | Flutter | 陷阱 |
|---|---|---|---|
| 调系统 API | 直接链接系统库 | MethodChannel.invokeMethod |
通道名/方法名拼错 |
| 接收原生事件 | 回调/epoll | EventChannel.receiveBroadcastStream |
忘记 cancel → 定时器不停 |
| 错误传递 | 返回码/errno | PlatformException |
把 code/message 当英文文案直接给用户 |
| 未实现 | 链接期报错 | MissingPluginException |
没降级处理 → 页面崩 |
| 参数序列化 | 结构体直接传 | StandardMessageCodec 类型集合 |
传自定义对象/DateTime |
| 线程 | 自己管 | 方法回调在平台主线程 | 在回调里做耗时操作 |
| 测试 | 需真机/模拟器 | setMockMethodCallHandler |
忘了断言 listen/cancel |
给 C/Go 老兵的三句话:
- 通道是"进程内跨语言 RPC",有序列化和线程切换成本;能用 FFI 的热路径别用通道。
- 通道名 + 方法名是唯一契约,把它写成常量,并且让测试覆盖。
- 原生侧的资源(定时器、传感器、监听器)必须由
onCancel释放,否则 Dart 侧cancel也救不了。
下一章进入综合项目(上):把前面所有零件——路由、Riverpod、JSON、网络、持久化——拼成一个有分层架构的真实应用。