鸿蒙原生与 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

posted @ 2026-09-09 15:19  带头大哥d小弟  阅读(27)  评论(0)    收藏  举报