跳到正文
CH 15综合与交付Flutter9 分钟阅读

平台通道与原生互操作:MethodChannel / EventChannel

第 15 章 · 平台通道与原生互操作:MethodChannel / EventChannel

本章示例examples/ch15-platform-channels在线阅读源码下载 zip

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 侧:请求-响应与事件流

dartlib/src/platform_service.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}');
      });
}

要点:

  1. 方法名与通道名是字符串契约,Dart 拼错只有运行时才发现。把名字集中成常量(本例),并用测试兜住。
  2. invokeMethod<T> 的 T 只是类型提示,实际返回值仍是 Object?;类型不对要自己判(本例 is! Map → FormatException)。
  3. MissingPluginException 表示"当前平台没有实现这个通道"——桌面/移动共用一套 Dart 代码时,这是正常情况,要翻译成"功能不可用",而不是崩溃。
  4. PlatformException 是原生主动抛的(result.error(...)),带 code/message/details。
  5. receiveBroadcastStream() 内部会向原生发 listen,cancel 订阅时发 cancel。必须取消,否则原生的定时器/传感器永远不停(ch06 的老规矩)。

另一种写法是 setMethodCallHandler 在 Dart 侧响应原生调用(原生 → Dart)。场景是"原生事件回调进 Dart",但绝大多数情况用 EventChannel 更清晰。

15.4 macOS 实现(本章真实验证的部分)

swiftmacos/Runner/MainFlutterWindow.swift源文件
// 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 的两个回调就是事件源的生命周期:

swift
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 的日志):

text
flutter: platform info: macOS 27.2.1 (arm64)

这行来自 Dart 侧的 debugPrint,而数据来自 Swift 的 ProcessInfo——证明整条通道链路是通的。界面上还能看到:OS/版本/架构、系统深色模式、每秒 +1 的事件计数(到 5 后流结束)。

15.5 Android 实现

kotlin
// 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 侧参考实现:

swiftios/Runner/AppDelegate.swift源文件
// 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 提供了拦截平台消息的钩子,不需要真机/桌面窗口:

darttest/platform_channel_test.dart源文件
// 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 的测试要多一步——模拟"原生主动推事件":

dart
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'));   // ★ 取消必须传到原生
});

三条测试原则:

  1. 断言双向契约:不仅断言 Dart 解析正确,也断言 Dart 真的发了 listen/cancel(原生靠它管生命周期)。
  2. 错误路径也要测:PlatformException、MissingPluginException、返回类型不对。
  3. "原生未实现"是常态:同一份 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:

bash
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 运行与验证

bash
cd examples/ch15-platform-channels
flutter pub get && flutter analyze && flutter test
flutter run -d macos        # 真实调用 Swift
flutter build macos --debug

本次真实验证:

text
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
// 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)
}
dart
// 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 老兵的三句话:

  1. 通道是"进程内跨语言 RPC",有序列化和线程切换成本;能用 FFI 的热路径别用通道。
  2. 通道名 + 方法名是唯一契约,把它写成常量,并且让测试覆盖。
  3. 原生侧的资源(定时器、传感器、监听器)必须由 onCancel 释放,否则 Dart 侧 cancel 也救不了。

下一章进入综合项目(上):把前面所有零件——路由、Riverpod、JSON、网络、持久化——拼成一个有分层架构的真实应用。