Flutter三方库鸿蒙适配实战：让flutter_sms在HarmonyOS上跑起来

Flutter三方库鸿蒙适配实战：让flutter_sms在HarmonyOS上跑起来

引言

最近华为鸿蒙系统（HarmonyOS）的生态越来越热，不少Flutter开发者都在琢磨：怎么把手头的应用顺滑地迁移到鸿蒙平台？Flutter本身凭借出色的跨平台渲染能力和丰富的三方库，确实是多端开发的一把利器。但问题来了------一旦涉及调用系统原生功能（比如发短信、调用传感器），那些依赖平台通道（Platform Channel）的Flutter插件，在鸿蒙上往往找不到官方支持，这时候就得我们自己动手适配了。

本文就以一个实际常用的、依赖系统短信服务的插件------flutter_sms为例，带你走一遍完整的鸿蒙端适配流程。我们会拆解它的实现原理，给出可操作的适配代码，顺便分享一些调试和优化的经验，希望能为你后续的跨平台适配工作打个样。

一、准备工作

1.1 开发环境配置

首先，确保你的开发环境满足以下基本条件，这是适配工作的基础。

# 1. 确认Flutter SDK版本（建议使用稳定的3.0以上版本）
flutter --version
# 输出示例：Flutter 3.19.5 • channel stable ...

# 2. 启用Flutter对HarmonyOS（OpenHarmony）的平台支持
# 这个命令允许Flutter工具链创建和构建鸿蒙项目。
flutter config --enable-ohos-desktop  # 针对鸿蒙桌面设备
flutter config --enable-ohos-mobile   # 针对鸿蒙手机等移动设备

# 3. 安装并配置鸿蒙原生开发工具
# 下载并安装DevEco Studio，用于编写HarmonyOS侧的Native代码。
# 下载地址：https://developer.huawei.com/consumer/cn/develop/deveco-studio/

1.2 获取目标插件源码

我们选用flutter_sms插件作为案例。它功能清晰，结构也很有代表性。

# 克隆原插件仓库到本地
git clone https://github.com/fluttercommunity/flutter_sms.git
cd flutter_sms

# 看一眼插件的目录结构，了解多平台是怎么组织的
tree -L 2

典型的flutter_sms插件目录结构如下。可以看到已经有android/和ios/的实现，而鸿蒙（ohos/）目录需要我们自己创建。

.
├── CHANGELOG.md
├── LICENSE
├── README.md
├── android/          # Android平台原生实现
├── ios/              # iOS平台原生实现
├── lib/              # Flutter Dart层代码
│   └── flutter_sms.dart
├── pubspec.yaml      # 插件依赖和元数据定义
└── ... (其他平台如windows, macos)

1.3 插件功能与适配目标分析

flutter_sms插件主要提供两个功能：

1. 打开短信应用：跳转到系统短信编辑界面，并预填好收件人和内容。
2. 直接发送短信：在后台静默发送短信，无需用户二次确认（当然，需要相应系统权限）。

适配的核心任务 很简单：在鸿蒙平台上，我们需要在ohos/目录下，用HarmonyOS的原生代码实现上述功能，并通过Flutter平台通道与Dart层通信。

二、技术核心：Flutter插件如何与鸿蒙通信

2.1 Platform Channel 原理

Flutter通过**平台通道（Platform Channel）**和原生平台进行双向异步通信。最常用的有三种：

• MethodChannel ：用于调用特定的原生方法并获取返回结果。flutter_sms主要就用它。
• EventChannel：用于向Dart层持续推送事件流（比如传感器数据）。
• BasicMessageChannel：用于使用自定义编解码器传递简单消息。

一次典型的通信流程是这样的：

1. Flutter端（Dart）通过MethodChannel发起调用（比如调用sendSMS）。
2. 消息被序列化后，通过引擎传递到原生端（Android是Java/Kotlin，iOS是Swift/ObjC，鸿蒙是Java）。
3. 原生端在对应的MethodChannel处理器里接收到调用，执行真正的原生代码（比如调用鸿蒙的短信API）。
4. 执行结果被序列化后，再通过同一个通道传回Flutter端。

2.2 鸿蒙侧的实现载体：Ability与Library

在鸿蒙生态里，Flutter引擎是作为一个"库工程（Library）"被集成到主Ability的HAP包中的。我们为插件写的原生代码，本质上是一个或多个HarmonyOS的Ability或Service ，它们通过MethodChannel和上层的Flutter UI交互。对于flutter_sms这种系统功能调用，通常使用Feature Ability (FA)或Particle Ability (PA, 即Service Ability)来实现。

三、动手适配：创建HarmonyOS端实现

3.1 创建鸿蒙模块目录结构

在flutter_sms插件根目录下，创建标准的鸿蒙模块结构。

mkdir -p ohos/src/main
cd ohos
# 创建鸿蒙模块必需的配置文件
touch build.gradle settings.gradle
mkdir -p src/main/java/com/example/flutter_sms
mkdir -p src/main/resources

3.2 配置HarmonyOS模块依赖

编辑ohos/build.gradle，配置好插件对Flutter引擎和HarmonyOS SDK的依赖。

apply plugin: 'com.huawei.ohos.library' // 声明为鸿蒙库模块

ohos {
    compileSdkVersion 8 // 根据你的DevEco Studio版本调整
    defaultConfig {
        compatibleSdkVersion 8
    }
}

dependencies {
    // 关键依赖：Flutter引擎嵌入层，提供了FlutterEngine和MethodChannel等类。
    implementation 'io.openharmony.tpc.thirdlib:flutter_embedding_release:1.0.1'
    // HarmonyOS核心库
    implementation 'com.huawei.ohos:hap:3.1.1.0'
}

四、代码实战：鸿蒙原生功能开发

4.1 实现核心工具类：SmsHelper

这个类封装了调用鸿蒙短信服务的基本API。

// ohos/src/main/java/com/example/flutter_sms/SmsHelper.java
package com.example.flutter_sms;

import ohos.app.Context;
import ohos.telephony.SmsManager;
import ohos.utils.zson.ZSONObject;
import ohos.utils.PacMap;
import java.util.List;
import java.util.ArrayList;

public class SmsHelper {

    private final Context context;
    private final SmsManager smsManager;

    public SmsHelper(Context context) {
        this.context = context;
        this.smsManager = SmsManager.getInstance(context);
    }

    /**
     * 直接发送短信。
     * @param recipients 收件人号码列表
     * @param body 短信正文
     * @return 包含发送结果的PacMap，可序列化回传给Flutter。
     */
    public PacMap sendDirectMessage(List<String> recipients, String body) {
        PacMap result = new PacMap();
        List<String> sentResults = new ArrayList<>();
        boolean allSuccess = true;
        String errorMessage = null;

        // 检查权限（需在Flutter侧或Ability入口提前申请）
        // if (!hasSmsPermission()) { ... }

        for (String recipient : recipients) {
            try {
                // 调用鸿蒙SmsManager API发送短信
                // 注意：此API可能需要特定权限，且为异步操作，这里简化为同步示例。
                smsManager.sendTextMessage(recipient, null, body, null, null);
                sentResults.add("Message to $recipient: Pending");
            } catch (Exception e) {
                allSuccess = false;
                sentResults.add("Message to $recipient: Failed - " + e.getMessage());
                errorMessage = e.getMessage();
            }
        }

        result.putBoolean("success", allSuccess);
        result.putString("resultList", ZSONObject.toZSONString(sentResults));
        if (errorMessage != null) {
            result.putString("error", errorMessage);
        }
        return result;
    }

    /**
     * 跳转到系统短信应用。
     * @param recipients 收件人号码列表
     * @param body 短信正文
     * @return 操作结果
     */
    public PacMap launchSmsApp(List<String> recipients, String body) {
        PacMap result = new PacMap();
        try {
            // 构造一个隐式Intent，跳转到系统短信编辑界面。
            Intent intent = new Intent();
            Operation operation = new Intent.OperationBuilder()
                    .withAction(Intent.ACTION_SENDTO) // 发送给某人的动作
                    .withUri(Uri.parse("sms:" + TextUtils.join(",", recipients))) // 收件人
                    .build();
            intent.setOperation(operation);
            intent.setParam("sms_body", body); // 预填充内容
            context.startAbility(intent, 0);
            result.putBoolean("success", true);
            result.putString("message", "SMS app launched.");
        } catch (Exception e) {
            result.putBoolean("success", false);
            result.putString("error", "Could not launch SMS app: " + e.getMessage());
        }
        return result;
    }
}

4.2 实现平台通道入口：FlutterSmsPlugin

这是Flutter引擎加载插件时调用的入口类，负责初始化MethodChannel并处理来自Dart层的调用。

// ohos/src/main/java/com/example/flutter_sms/FlutterSmsPlugin.java
package com.example.flutter_sms;

import io.flutter.embedding.engine.plugins.FlutterPlugin;
import io.flutter.plugin.common.MethodCall;
import io.flutter.plugin.common.MethodChannel;
import io.flutter.plugin.common.MethodChannel.MethodCallHandler;
import io.flutter.plugin.common.MethodChannel.Result;
import ohos.app.Context;
import ohos.utils.PacMap;
import java.util.List;

/** FlutterSmsPlugin */
public class FlutterSmsPlugin implements FlutterPlugin, MethodCallHandler {
  private MethodChannel channel;
  private Context ohosContext;
  private SmsHelper smsHelper;

  @Override
  public void onAttachedToEngine(FlutterPluginBinding binding) {
    // 1. 创建MethodChannel，通道名称必须与Dart端完全一致。
    channel = new MethodChannel(binding.getBinaryMessenger(), "flutter_sms");
    channel.setMethodCallHandler(this);

    // 2. 获取鸿蒙应用的Context，并初始化工具类。
    ohosContext = binding.getApplicationContext();
    smsHelper = new SmsHelper(ohosContext);
  }

  @Override
  public void onMethodCall(MethodCall call, Result result) {
    // 3. 根据Dart端调用的方法名，分派到不同的原生功能。
    switch (call.method) {
      case "sendSMS":
        handleSendSMS(call, result);
        break;
      case "sendDirectSMS":
        handleSendDirectSMS(call, result);
        break;
      default:
        result.notImplemented();
    }
  }

  private void handleSendSMS(MethodCall call, Result result) {
    // 对应"打开短信应用"功能
    try {
      List<String> recipients = call.argument("recipients");
      String body = call.argument("body");
      PacMap pacMapResult = smsHelper.launchSmsApp(recipients, body);
      // 将PacMap转换为Flutter可识别的Map
      result.success(convertPacMapToMap(pacMapResult));
    } catch (Exception e) {
      result.error("LAUNCH_ERROR", e.getMessage(), null);
    }
  }

  private void handleSendDirectSMS(MethodCall call, Result result) {
    // 对应"直接发送短信"功能
    try {
      List<String> recipients = call.argument("recipients");
      String body = call.argument("body");
      // 注意：在实际应用中，此处应检查并请求SEND_SMS权限。
      PacMap pacMapResult = smsHelper.sendDirectMessage(recipients, body);
      result.success(convertPacMapToMap(pacMapResult));
    } catch (SecurityException e) {
      result.error("PERMISSION_DENIED", "SEND_SMS permission not granted", null);
    } catch (Exception e) {
      result.error("SEND_ERROR", e.getMessage(), null);
    }
  }

  private Map<String, Object> convertPacMapToMap(PacMap pacMap) {
    // 简化的转换逻辑，实际应根据PacMap内容精细处理。
    Map<String, Object> map = new HashMap<>();
    for (String key : pacMap.keySet()) {
        map.put(key, pacMap.getObject(key));
    }
    return map;
  }

  @Override
  public void onDetachedFromEngine(FlutterPluginBinding binding) {
    channel.setMethodCallHandler(null);
    channel = null;
    smsHelper = null;
  }
}

4.3 注册插件

最后，别忘了在鸿蒙模块的资源文件里注册插件，这样Flutter引擎才能自动发现并初始化它。

<!-- ohos/src/main/resources/config.json (部分) -->
{
  "module": {
    "package": "com.example.flutter_sms",
    "name": ".MyApplication",
    "deviceTypes": ["phone", "tablet"],
    "distro": {
      "deliveryWithInstall": true,
      "moduleName": "flutter_sms_ohos"
    },
    "abilities": [
      // ... 其他Ability
    ],
    "plugins": [
      {
        "name": "flutter_sms",
        "class": "com.example.flutter_sms.FlutterSmsPlugin" // 指定入口类
      }
    ]
  }
}

五、集成、调试与性能优化

5.1 在Flutter应用中集成适配后的插件

修改你的Flutter应用的pubspec.yaml，通过path依赖本地刚刚适配好的插件。

dependencies:
  flutter:
    sdk: flutter
  flutter_sms:
    path: /path/to/your/adapted/flutter_sms # 指向包含ohos目录的插件根路径

5.2 调试与日志查看

1. Flutter侧日志 ：使用flutter run --enable-ohos命令把应用跑到鸿蒙设备或模拟器上，Dart层的print和异常信息会在控制台显示。
2. 鸿蒙原生侧日志 ：使用DevEco Studio的Log窗口查看。可以过滤标签FlutterSmsPlugin或MethodChannel，观察原生方法的调用参数和结果。
3. 通道通信验证 ：在onMethodCall方法开始处加一行日志，打印call.method和call.arguments，确保数据传递没问题。

5.3 性能优化建议

虽然flutter_sms插件逻辑不复杂，但下面几条优化原则对大多数插件适配都适用：

• 减少平台通道调用次数：对于批量操作（比如群发短信），尽量在原生侧循环处理，避免每条短信都走一次通道。
• 异步处理 ：耗时的原生操作（比如网络请求、大量数据处理）一定要扔到异步任务（TaskDispatcher）里，别阻塞UI线程（也就是MethodChannel的调用线程）。
• 结果缓存：对于一些不常变化的数据，可以考虑在原生侧做缓存。
• 权限懒加载：别在应用一启动就把所有权限都申请了。只在真正要执行敏感操作（比如发短信）前，再去检查和申请权限。

六、总结

通过上面这些步骤，我们系统地把Flutter三方库flutter_sms适配到了鸿蒙平台。整个过程从环境配置 和源码分析 开始，深入到Flutter平台通道的通信机制 ，然后亲手创建了HarmonyOS端的原生模块。通过实现SmsHelper和FlutterSmsPlugin，我们完成了短信发送与跳转的核心功能。文章也提供了具体的集成步骤、调试方法 和一些通用的性能优化思路。

回顾这次适配，有几个关键点值得记住：

1. 理解桥梁 ：真正搞明白MethodChannel是连接Flutter Dart和HarmonyOS原生世界的桥梁。
2. 对标实现 ：仔细参考Android/iOS端的原生实现，在鸿蒙侧找到功能对等的API（比如SmsManager、Intent）。
3. 规范开发：遵循HarmonyOS的模块化开发规范，把依赖和插件注册信息配对了。

鸿蒙生态还在快速发展，相信未来会有更多Flutter插件提供官方支持。但在那之前，掌握这套适配方法，能让你快速把丰富的Flutter生态引入到鸿蒙世界，也算是在生态发展的早期占了个先机。