鸿蒙原生与 Flutter 混合开发:三种通讯方式快速上手
鸿蒙原生与 Flutter 混合开发:三种通讯方式快速上手
这篇文档对应华为开发者官网的混合开发说明,重点讲鸿蒙原生(ArkTS)和 Flutter 之间怎么互相传数据、互相调用。我们把它拆成最常用的三种通道,每种都配一段能直接照着写的代码。
文中的代码不是演示用的假代码,而是已经在下面的项目里编译通过的写法:
- Flutter 侧:
flutter_module/lib/main.dart - 鸿蒙原生侧:
entry/src/main/ets/flutter/MyFlutterEntry.ets
一、先搞清楚一件事:谁找谁
混合开发里,Flutter 页面和鸿蒙原生页面放在同一个 App 里。它们互相不认识,所以需要一条"通道"来传话。
华为文档里说的三种通道,本质区别就一句话:数据是谁发起、流向哪边、能不能收到回复。
| 通道 | 谁发起 | 数据方向 | 有没有回复 | 典型场景 |
|---|---|---|---|---|
| MethodChannel | Flutter 主动调用原生 | Flutter → 原生 → Flutter | 有,一次一答 | 获取设备号、调相机、算一个结果 |
| BasicMessageChannel | 双方都可以主动发 | 双向 | 可以回复,也可以不回复 | 传简单字符串、JSON、自定义协议 |
| EventChannel | 原生主动推给 Flutter | 原生 → Flutter | 没有,持续发事件流 | 传感器数据、电量变化、进度更新 |
一句话记忆:
- 想"问一句、答一句",用 MethodChannel。
- 想"来回聊天",用 BasicMessageChannel。
- 想"原生不停往 Flutter 推送",用 EventChannel。
注意:三种通道的名字就是它们的"身份证",Flutter 侧和原生侧必须写成一模一样,否则对不上。
二、数据到底怎么传:能传什么、不能传什么
这一章是三种通道通用的规则,建议先看完再往后看代码。
很多人第一次接通道,代码照抄能跑,但一传自己的数据结构就失败,问题都出在这一章。
2.1 能传的就这几种类型
通道不是万能的,它只认下面这些类型:
| 类型 | Flutter(Dart)侧 | 鸿蒙原生(ArkTS)侧 | 说明 |
|---|---|---|---|
| 空值 / 布尔 / 数字 / 字符串 | null、bool、int、double、String |
null、boolean、number、string |
最常用 |
| 列表 | List |
数组 [] |
原样传 |
| 键值对 | Map |
普通对象 {...} |
键必须是字符串 |
| 二进制 | Uint8List |
ArrayBuffer / Uint8Array |
传图片字节等 |
自定义 class 实例 |
❌ 不支持 | ❌ 不支持 | 必须先转成上面的类型 |
函数、Date、Set、Stream |
❌ 不支持 | ❌ 不支持 | 通道不认识 |
一句话:通道只认"键值对 + 数组",传过去的是值,不是对象。
2.2 最容易搞混的一点:interface 能传,class 不能传
这一条建议重点看,因为它看起来"自相矛盾"。
我们的原生代码里有这样的写法:
// ✅ 这样是可以的
export interface CalculatorResultDto {
value: number;
label: string;
}
const dto: CalculatorResultDto = { value: first - second, label: '差' };
result.success(dto);
CalculatorResultDto 看着像"自定义对象",为什么能直接回传?
因为 ArkTS / TypeScript 的 interface 只存在于编译期,运行时会被完全擦除。
运行时它就是普通的对象字面量 { value, label },等价于一张 Map,通道能正常编码。
真正不能传的是带原型的 class 实例(有方法、getter、原型链):
// ❌ 这样不行
class CalculatorResult {
value: number = 0;
format(): string { return `${this.value}`; } // ← class 才有方法
}
result.success(new CalculatorResult()); // 通道编解码会失败
需要回传 class 实例时,先"拍平"成普通对象:
// ✅ 先转成普通对象再回传
const result = new CalculatorResult(first - second);
const dto: CalculatorResultDto = {
value: result.value,
label: result.format()
};
result.success(dto);
一句话判据:不是"是不是自定义类型",而是"运行时是不是普通对象"。
iOS / Android 接入时同理:直接用
[String: Any]/HashMap就行,不用为这些结构建实体类再序列化。
2.3 数字类型有坑:两边的"数字"不是一回事
三个平台的数字类型对不上,这是跨端最常见的隐性 bug:
| 场景 | 问题 |
|---|---|
| 原生 → Flutter | 原生回传一个整数,Dart 侧如果写 invokeMethod<int> 而实际值是小数,会直接抛 TypeError |
| Flutter → 原生 | Dart 的 int 和 double 到了 ArkTS 都是 number,看不出区别;到了 iOS 常常变成 NSNumber(double) |
| 参数没传 | call.argument('second') 会拿到 undefined,参与运算就是 NaN,界面上显示 NaN |
所以两端都要"容错取值",不要直接强转。 原生侧:
/** 读数字参数:是数字就用,是字符串就转,取不到就用默认值 */
function argInt(call: MethodCall, key: string, fallback: number = 0): number {
const value = call.argument(key);
if (typeof value === 'number') {
return value;
}
if (typeof value === 'string') {
const parsed = Number.parseInt(value, 10);
return Number.isNaN(parsed) ? fallback : parsed;
}
return fallback;
}
// 用法:second 没传也不会变成 NaN,而是拿到默认值 0
const first = argInt(call, 'first');
const second = argInt(call, 'second');
Flutter 侧同理,写一套 _asInt / _asDouble:
int _asInt(Object? value) {
if (value is int) return value;
if (value is num) return value.toInt(); // 原生传 double 也能接
if (value is String) return int.tryParse(value) ?? 0;
return 0;
}
2.4 参数名和 key:大小写敏感,而且必须是字符串
- 原生侧
call.argument('first')和 Flutter 侧传的{'first': 12}必须逐字一致,大小写也算;
写成'First'取到的就是undefined,而且不会报错,只会算出个NaN。 - Map 的键必须是字符串。Flutter 侧
MethodChannel的形参写的是Map<Object?, Object?>,
但实际能安全往返的只有字符串键,别用枚举或数字当键。
小建议:参数名不要取
type、data这种太通用的词,两端各自维护一份"方法名 + 参数名"的约定表,改的时候一起改。
2.5 枚举值必须三端完全一致
通道传不了枚举类型,传的是数字,所以数字的含义必须三端自己约定好:
| 枚举 | 取值 | 含义 |
|---|---|---|
MediaType |
0 / 1 |
视频 / 照片 |
DownloadStatus |
0 / 1 / 2 / 3 / 4 |
等待 / 暂停 / 下载中 / 完成 / 失败 |
AlbumTab |
0 / 1 / 2 |
相机文件 / 已下载 / 云相册 |
⚠️ 新端接入时请直接照抄这张表,不要按直觉编号。
比如MediaType是"视频 = 0",很多平台会习惯性把照片当 0,接上以后两边显示正好相反。
2.6 返回值可能是 null
原生侧如果没有处理这个方法,会回 notImplemented,Flutter 侧 await 拿到的是 null,不是异常:
// 原生侧:每一条调用都必须回一次,三选一
result.success(data); // 成功
result.error('code', 'msg'); // 失败
result.notImplemented(); // 没实现 → Flutter 侧拿到 null
// Flutter 侧:一定要判空 + 容错解析,别直接强转
final Map<Object?, Object?>? result =
await _channel.invokeMethod<Map<Object?, Object?>>('subtract', args);
if (result == null) {
return 0; // 原生没实现 / 返回空,走兜底
}
三选一没做到(比如原生什么都不调),Flutter 侧的 await 会永远不返回,表现为界面一直转圈。
2.7 传过去的是"值",跨通道匹配要用稳定的键
通道不传引用,传的是那一刻的值。所以同一个东西在两边是两个副本,要匹配就得靠某个"两边都一样"的键。
这个键必须生命周期内不会变。我们踩过这个坑:
| 用法 | 结果 |
|---|---|
用 fileId 做下载任务的匹配键 |
❌ 下载开始时 fileId 会被重新生成,Flutter 侧一条都匹配不上(现象是"日志在变、界面不动") |
改用 remoteUrl 做匹配键 |
✅ 从入队到完成全程不变,问题消失 |
规则:需要跨通道匹配的字段,必须挑生命周期内不变的那个,而不是"看起来唯一"的那个。
2.8 大数据不要走通道
通道的编解码都在主线程上做,数据大了就是卡顿:
| 场景 | 建议 |
|---|---|
| 传图片/文件内容 | 用 Uint8List / ArrayBuffer;再大就传文件路径,让另一边自己读 |
| 列表全量刷新 | 只在首屏拉一次全量,之后推增量 |
| 高频变化(进度、传感器) | 限流推送(我们项目里是 300ms 一次),而且只推正在变化的那几条 |
我们实测过:队列上千条时每 500ms 推一次全量快照,"构造对象 + 通道编解码"直接把主线程压死,报 THREAD_BLOCK_6S。
三、MethodChannel:一问一答
3.1 什么时候用
Flutter 想调用原生能力,并且要拿到一个返回值。比如:
- 获取设备的某个信息;
- 调用原生已经写好的功能;
- 让原生帮忙算个数再还回来。
华为官网的用例是"获取设备号",我们项目里对应的是"减法由原生计算后返回"。
3.2 数据怎么走
Flutter 调 invokeMethod('subtract')
↓
鸿蒙原生收到方法名和参数
↓
原生计算(执行的函数),result.success(结果)
↓
Flutter 拿到结果并显示
3.3 Flutter 侧代码
import 'package:flutter/services.dart';
// 通道名,两边必须一致
const MethodChannel _nativeChannel =
MethodChannel('com.example.hybrid/native_calculator');
Future<void> subtract() async {
// 把两个数传给原生,原生算完把差返回来
final result = await _nativeChannel.invokeMethod<dynamic>(
'subtract',
{'first': 12, 'second': 5},
);
print(result); // 7
}
3.4 鸿蒙原生侧代码
import { MethodChannel } from '@ohos/flutter_ohos';
const channel = new MethodChannel(
binaryMessenger,
'com.example.hybrid/native_calculator'
);
channel.setMethodCallHandler({
onMethodCall: (call, result) => {
if (call.method === 'subtract') {
// 用容错取值,别直接 as number(见 2.3)
const first = argInt(call, 'first');
const second = argInt(call, 'second');
// 计算在原生侧完成
result.success(first - second);
return;
}
result.notImplemented();
}
});
四、MethodChannel 反着用:原生调 Flutter
MethodChannel 不是只能 Flutter 先开口。原生也可以反过来调用 Flutter 里已经写好的方法。
4.1 Flutter 侧:先注册好一个方法等着被调
const MethodChannel _flutterChannel =
MethodChannel('com.example.hybrid/flutter_calculator');
// 在 initState 里注册。注意:这个方法是被原生调用的,
// 参数要从 call.arguments 里取,不能直接用变量名
_flutterChannel.setMethodCallHandler((call) async {
if (call.method == 'divide') {
final Map<Object?, Object?> args =
(call.arguments as Map<Object?, Object?>?) ?? const <Object?, Object?>{};
final double first = _asDouble(args['first']);
final double second = _asDouble(args['second']);
if (second == 0) {
// 这里 throw 出去,原生侧的 error 回调会拿到 code / message
throw PlatformException(code: 'DIVIDE_BY_ZERO', message: '除数不能为 0');
}
return first / second; // 这个返回值会交给原生侧的 success 回调
}
throw PlatformException(code: 'NOT_IMPLEMENTED', message: '未实现:${call.method}');
});
// 容错取值:原生传过来的可能是 int、double,也可能是字符串
double _asDouble(Object? value) {
if (value is num) return value.toDouble();
if (value is String) return double.tryParse(value) ?? 0;
return 0;
}
4.2 原生侧:主动调一下
const flutterChannel = new MethodChannel(
binaryMessenger,
'com.example.hybrid/flutter_calculator'
);
// 原生主动让 Flutter 执行除法。
// ⚠️ 注意:ArkTS 的 invokeMethod 返回 void,结果要用第三个参数(回调)拿,
// 写 flutterChannel.invokeMethod('divide', null) 是拿不到返回值的
flutterChannel.invokeMethod('divide', { 'first': 12, 'second': 4 }, {
// Flutter 侧 return 的值走这里
success: (value: Object) => {
hilog.info(0x0000, 'HybridDemo', 'Flutter 返回:%{public}s', JSON.stringify(value));
},
// Flutter 侧 throw PlatformException 时走这里
error: (code: string, message: string) => {
hilog.error(0x0000, 'HybridDemo', `调用 Flutter 失败:${code} ${message}`);
},
// Flutter 侧根本没有注册这个方法时走这里
notImplemented: () => {
hilog.warn(0x0000, 'HybridDemo', 'Flutter 侧没有注册 divide');
}
});
对应项目里的按钮:除法:原生调 Flutter。
五、BasicMessageChannel:双向聊天
5.1 什么时候用
两边都要能主动发消息,数据是字符串、简单对象或 JSON。它比 MethodChannel 更"轻",没有方法名,直接发一条消息,对方可以回复。
我们项目里对应"乘法":Flutter 发 3,4 给原生,原生算完把 3 × 4 = 12 回给 Flutter。
5.2 数据怎么走
Flutter 发消息 "3,4"
↓
鸿蒙原生收到后处理
↓
原生 reply.reply("3 × 4 = 12")
↓
Flutter 收到回复
5.3 Flutter 侧代码
import 'package:flutter/services.dart';
// StringCodec 表示这条通道传的是字符串
const BasicMessageChannel<String> _msgChannel =
BasicMessageChannel<String>(
'com.example.hybrid/basic_message',
StringCodec(),
);
final reply = await _msgChannel.send('3,4');
print(reply); // 3 × 4 = 12
5.4 鸿蒙原生侧代码
import {
BasicMessageChannel,
StringCodec,
} from '@ohos/flutter_ohos';
const msgChannel = new BasicMessageChannel<string>(
binaryMessenger,
'com.example.hybrid/basic_message',
StringCodec.INSTANCE
);
msgChannel.setMessageHandler({
onMessage: (message, reply) => {
const parts = message.split(',');
const first = Number(parts[0]);
const second = Number(parts[1]);
// 原生把结果回给 Flutter
reply.reply(`${first} × ${second} = ${first * second}`);
}
});
5.5 原生也可以先开口
反过来,原生想主动发消息给 Flutter 时,Flutter 也要提前注册一个接收器:
const BasicMessageChannel<String> _nativeMsgChannel =
BasicMessageChannel<String>(
'com.example.hybrid/native_message',
StringCodec(),
);
_nativeMsgChannel.setMessageHandler((message) async {
print('收到原生消息:$message');
return '已收到';
});
原生侧直接发:
const nativeMsgChannel = new BasicMessageChannel<string>(
binaryMessenger,
'com.example.hybrid/native_message',
StringCodec.INSTANCE
);
nativeMsgChannel.send('这是鸿蒙原生发来的消息');
六、EventChannel:原生持续推事件
6.1 什么时候用
数据主要从原生往 Flutter 流,而且可能不止一次。比如传感器读数、网络状态变化、进度更新。
我们项目里对应"原生推事件":鸿蒙原生通过 EventChannel 推一条设备信息给 Flutter。
6.2 数据怎么走
Flutter 先订阅事件流
↓
鸿蒙原生保存 EventSink(一个"发送口")
↓
原生随时 sink.success(事件)
↓
Flutter 的监听回调收到事件
6.3 Flutter 侧代码
import 'dart:async';
import 'package:flutter/services.dart';
const EventChannel _eventChannel =
EventChannel('com.example.hybrid/native_event');
StreamSubscription? _subscription;
_subscription = _eventChannel
.receiveBroadcastStream()
.listen((event) {
print('收到原生事件:$event');
});
// 页面销毁时记得取消订阅
_subscription?.cancel();
6.4 鸿蒙原生侧代码
import { EventChannel, EventSink } from '@ohos/flutter_ohos';
private nativeEventSink: EventSink | null = null; // 定义在类内部
const eventChannel = new EventChannel(
binaryMessenger,
'com.example.hybrid/native_event'
);
eventChannel.setStreamHandler({
onListen: (args, events) => {
// Flutter 开始监听时,把发送口保存下来
this.nativeEventSink = events;
},
onCancel: () => {
// Flutter 取消监听时清掉
this.nativeEventSink = null;
}
});
// 以后任何地方、任何时候都能推一条事件
this.nativeEventSink?.success('设备号 3AQ0224B14026838');
七、华为官网用例和我们项目的对照
华为文档用"获取设备号"贯穿三种通道,我们的项目用"计算器"贯穿,逻辑是对应的:
| 华为文档 | 我们项目 | 通道 |
|---|---|---|
| Flutter 调原生拿设备号 | 减法:Flutter 调原生算差 | MethodChannel |
| 原生方法由 Flutter 实现 | 除法:原生反过来调 Flutter | MethodChannel 反向 |
| 双向发消息 | 乘法:Flutter 发两个数、原生回乘积 | BasicMessageChannel |
| 设备号变化持续推送 | 原生主动推事件给 Flutter | EventChannel |
八、最容易踩的几个坑
通道本身
- 通道名对不上:Flutter 和原生必须用完全相同的字符串,少一个字符都会报
MissingPluginException。 - 编解码器不匹配:
BasicMessageChannel传字符串就用StringCodec,两边要一致。 - 忘了取消订阅:
EventChannel的StreamSubscription在页面销毁时要cancel(),否则会泄漏。 - 结果回调要各走各的路:原生处理完必须调用
result.success、result.error或result.notImplemented其中一个,不能什么都不做。 - 先注册再调用:如果原生要调 Flutter 的方法,Flutter 侧必须先把
setMethodCallHandler注册好,否则原生调不到。 - 原生调 Flutter 拿返回值要用回调:ArkTS 的
invokeMethod(method, args, callback)返回的是void,第三个参数才是结果回调,别写成.then()(拿不到东西)。Flutter 侧return的值走success,throw PlatformException走error。
数据传递(详见第二章)
- 参数名大小写错了、或者漏传:不报错,只会拿到
undefined/NaN。 - 直接回传
class实例:接口报错或者数据丢失,先转成普通对象。 - 枚举数字含义两端反了:界面显示正好相反,先对齐第二章那张枚举表。
- 跨通道匹配用了会变的字段:现象是"日志在变、界面不动",换成生命周期内不变的键。
- 高频/大量数据走通道:主线程被编解码压死,表现为卡顿甚至 ANR。
调试
- 在 Flutter 里用
print/debugPrint打日志:在鸿蒙真机上看不到,需要走通道转发到原生日志(见另一篇《Flutter 端日志打印实现》)。
项目地址:https://gitee.com/wking123321/arkts-flutter
官网介绍:https://developer.huawei.com/consumer/cn/blog/topic/03223830707488374
浙公网安备 33010602011771号