Flutter 三方库 `flutter_phone_direct_caller` 在 OpenHarmony 平台的适配实战

Flutter 三方库flutter_phone_direct_caller在 OpenHarmony 平台的适配实战

引言

OpenHarmony（下文简称 OHOS）作为新一代的智能终端操作系统，其生态的完善离不开大量应用的支持。Flutter 凭借高效的渲染引擎和优秀的跨平台一致性，成为快速拓展应用生态的一个有力选项。不过，Flutter 应用的很多核心功能其实依赖原生平台的能力——比如蓝牙、传感器、系统服务等，这些功能通常通过 Flutter 插件（也就是三方库）来桥接。因此，能否把成熟的 Flutter 插件生态平滑地引入 OHOS，直接决定了 Flutter 应用在鸿蒙设备上的功能完整性和体验流畅度，这也是当前很多开发者正在面对的挑战。

本文我们将通过一个具体且常用的插件——flutter_phone_direct_caller（用于直接调起系统拨号界面），来完整走一遍它在 OHOS 平台上的适配过程。我们不止会介绍步骤，还会深入分析背后的技术原理（比如Pigeon通信、FFI机制以及鸿蒙的Ability调度机制），探讨适配时的注意事项和最佳实践，并提供从环境搭建、代码实现、性能优化到最终集成的全流程参考。希望能为大家提供一个可复用、可扩展的 Flutter-OHOS 插件适配思路，降低跨平台迁移的成本。

一、 准备工作与环境配置

1.1 开发环境清单

开始之前，需要确保以下工具链就位，并注意版本之间的兼容性：

• Flutter SDK: 版本 ≥ 3.19.0（从这个版本开始，Flutter 开始实验性支持--platforms=ohos构建目标）。
• Dart SDK: 跟随 Flutter SDK 安装即可，版本 ≥ 3.3.0。
• DevEco Studio: 版本 ≥ 4.0 Release，用于 OHOS 原生开发，主要管理 OHOS SDK 和构建 HAR（HarmonyOS Ability Resource）包。
• OHOS SDK: API Version ≥ 10，通过 DevEco Studio 的 SDK Manager 安装。
• 环境变量: 确认ohpm（OpenHarmony 包管理器）、hdc（调试命令行工具）等路径已添加到系统的 PATH 中。

1.2 环境验证

打开终端，执行以下命令，验证 Flutter 是否已准备好支持 OHOS：

flutter doctor -v

查看输出中是否包含OpenHarmony设备选项。接着，可以创建一个测试项目并添加 OHOS 平台支持：

flutter create ohos_caller_demo cd ohos_caller_demo flutter create --platforms=ohos .

二、 技术分析与适配原理

动手写代码之前，有必要先搞清楚 Flutter 插件在 OpenHarmony 平台是怎么工作的。

2.1 Flutter 插件通信机制

Flutter 应用通过**平台通道（Platform Channel）**与原生端通信。常见的方式有：

1. MethodChannel: 用于异步方法调用，也是本次适配主要采用的方式。
2. EventChannel: 用于原生端向 Flutter 端持续发送事件流。
3. Pigeon: 一个基于代码生成的类型安全通信工具，它通过定义接口自动生成两端代码，替代手写MethodChannel调用，能减少出错并提升开发体验。本次适配我们会用Pigeon来进行优化。

2.2 OpenHarmony 原生能力调用

在 OHOS 中，调起系统拨号界面属于启动其他应用的 Ability。主要通过@ohos.app.ability.common模块的StartOptions和wantConstant来实现。核心是构造一个正确的Want对象，指定bundleName和abilityName；对于拨号这类系统应用，通常可以直接使用预定义的 Action（如ohos.want.action.call）或 URI Scheme（tel:）。

2.3 适配架构设计

我们计划采用下面这样的分层结构：

• Dart 接口层: 定义插件对外的 API（FlutterPhoneDirectCaller类），并用Pigeon生成通信接口。
• 通信桥接层: 在 OHOS 侧实现Pigeon生成的接口，充当 Dart 与 HarmonyOS Native 代码之间的桥梁。
• 原生实现层: 用 ArkTS 编写具体的系统能力调用逻辑，包括权限申请、构造Want、启动拨号 Ability。
• FFI 动态库层（可选高级方案）: 如果对性能有极致要求，可以通过dart:ffi直接调用预编译的 Native (C/C++) 库，绕过 Channel 的序列化开销。本文也会简要介绍这种方案。

三、 代码实现：完整适配流程

3.1 步骤一：创建 Flutter 插件项目

flutter create --template=plugin --platforms=android,ios,ohos flutter_phone_direct_caller_ohos cd flutter_phone_direct_caller_ohos

3.2 步骤二：定义 Dart API 与 Pigeon 协议

1. 安装 Pigeon：在pubspec.yaml的dev_dependencies下添加pigeon: ^10.0.0。
2. 创建协议文件：在项目根目录创建pigeons/call_api.dart。

   // pigeons/call_api.dart import 'package:pigeon/pigeon.dart'; // 配置 Pigeon 生成的文件路径和语言 @ConfigurePigeon( PigeonOptions( dartOut: './lib/src/generated/call_api.dart', dartTestOut: './test/generated_test.dart', kotlinOut: '../android/src/main/kotlin/com/example/flutter_phone_direct_caller_ohos/CallApi.kt', kotlinPackage: 'com.example.flutter_phone_direct_caller_ohos', // OpenHarmony (ArkTS) 输出路径 // 注意：目前 Pigeon 对 OHOS 的 ArkTS 支持还处于社区扩展阶段，可能需要使用特定版本或生成后手动调整。 // 这里我们先生成接口定义，再手动编写 ArkTS 实现。 ), ) // 定义通信接口 @HostApi() abstract class CallApi { // 调起拨号界面，phoneNumber 为电话号码字符串 // 返回布尔值表示是否成功发起意图 @async bool dialNumber(String phoneNumber); }

3. 运行 Pigeon 生成代码：

   dart run pigeon --input pigeons/call_api.dart

   成功后会看到lib/src/generated/目录下生成了 Dart 接口文件call_api.dart。

3.3 步骤三：实现 Dart 层插件主类

修改lib/flutter_phone_direct_caller_ohos.dart：

// lib/flutter_phone_direct_caller_ohos.dart library flutter_phone_direct_caller_ohos; import 'src/generated/call_api.dart'; // 引入 Pigeon 生成的接口 import 'package:flutter/services.dart'; /// 用于直接调起系统拨号界面的插件。 class FlutterPhoneDirectCaller { static const MethodChannel _channel = MethodChannel('flutter_phone_direct_caller_ohos'); // Pigeon 生成的 API 实例 static final CallApi _api = CallApi(); /// 直接调起系统拨号界面并填充指定的电话号码。 /// /// [phoneNumber] 需要拨打的电话号码字符串。 /// 返回 Future<bool>，成功发起拨号意图为 true，失败为 false。 /// /// 示例： /// ```dart /// bool result = await FlutterPhoneDirectCaller.dialNumber('10086'); /// if (result) { /// print('拨号界面已调起'); /// } else { /// print('调起失败，请检查权限或号码格式'); /// } /// ``` static Future<bool> dialNumber(String phoneNumber) async { try { // 输入校验 if (phoneNumber.isEmpty) { throw ArgumentError('phoneNumber cannot be empty'); } // 简单清理号码格式（移除空格、横杠等） final sanitizedNumber = phoneNumber.replaceAll(RegExp(r'[\s\-\(\)]+'), ''); // 通过 Pigeon 生成的接口调用原生方法 bool success = await _api.dialNumber(sanitizedNumber); return success; } on PlatformException catch (e) { // 捕获平台通道异常 print('Platform exception occurred: ${e.message}'); return false; } catch (e) { // 捕获其他异常（如参数错误） print('Unexpected error: $e'); rethrow; // 重新抛出非平台相关的异常，交给调用方处理 } } /// （可选）一个便捷方法，用于检查并请求拨号权限（主要用于Android）。 /// 注意：OpenHarmony 的权限模型不同，此方法在OHOS端可能不适用。 static Future<bool> checkAndRequestPermission() async { try { final bool? result = await _channel.invokeMethod('requestPermission'); return result ?? false; } on PlatformException { return false; } } }

3.4 步骤四：实现 OpenHarmony (ArkTS) 平台端代码

这一步是适配的核心。我们主要在ohos/目录下进行开发。

1. 创建入口 Ability：编辑ohos/src/main/ets/entryability/EntryAbility.ts。

   // ohos/src/main/ets/entryability/EntryAbility.ts import UIAbility from '@ohos.app.ability.UIAbility'; import window from '@ohos.window'; import { CallApi } from '../pigeon/CallApi'; // 稍后手动创建的实现类 import { CallApiProxy } from '../pigeon/CallApiProxy'; // 代理类（Pigeon生成或手动创建） export default class EntryAbility extends UIAbility { onCreate(want, launchParam) { console.info('EntryAbility onCreate'); // 初始化 Pigeon 代理，将 Dart 端的请求转发到我们的实现类 CallApiProxy.setup(new CallApiImpl(this.context)); } // ... 其他生命周期方法 }

2. 手动创建 Pigeon 接口的 ArkTS 实现： 因为 Pigeon 对 ArkTS 的完整自动生成支持还在演进中，这里我们手动创建接口和实现。

   // ohos/src/main/ets/pigeon/CallApi.ts export interface CallApi { dialNumber(phoneNumber: string): Promise<boolean>; }

   // ohos/src/main/ets/pigeon/CallApiImpl.ts import { CallApi } from './CallApi'; import common from '@ohos.app.ability.common'; import { BusinessError } from '@ohos.base'; import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; import hilog from '@ohos.hilog'; const TAG = 'CallApiImpl'; const DOMAIN = 0xFF00; export class CallApiImpl implements CallApi { private context: common.Context; constructor(context: common.Context) { this.context = context; } async dialNumber(phoneNumber: string): Promise<boolean> { hilog.info(DOMAIN, TAG, `Attempting to dial: ${phoneNumber}`); try { // 1. 参数校验 if (!phoneNumber || phoneNumber.trim().length === 0) { hilog.error(DOMAIN, TAG, 'Phone number is empty'); return false; } // 2. 检查并申请权限 (OHOS权限名称为`ohos.permission.PLACE_CALL`) let permissionGranted = await this.checkCallPermission(); if (!permissionGranted) { hilog.warn(DOMAIN, TAG, 'Call permission not granted, the system may prompt the user.'); // 在OHOS中，部分能力（如拉起拨号界面）可能不需要显式授权，或由系统弹窗处理。 // 这里我们继续执行，让系统决定如何处理权限问题。 } // 3. 构造 Want 对象，使用 URI Action 调起拨号界面 let want = { action: 'ohos.want.action.call', // 对于拨号，通常用 uri 传递电话号码 uri: `tel:${phoneNumber}`, // 也可以显式指定系统电话应用的bundleName和abilityName（因设备而异） // bundleName: 'com.android.contacts', // 示例，实际OHOS系统应用包名可能不同 // abilityName: 'com.android.contacts.activities.TwelveKeyDialer', parameters: { // 可附加额外参数 } }; // 4. 启动拨号 Ability await this.context.startAbility(want, { windowMode: 0 }); hilog.info(DOMAIN, TAG, `Dial intent started successfully for: ${phoneNumber}`); return true; } catch (error) { const err: BusinessError = error as BusinessError; hilog.error(DOMAIN, TAG, `Failed to start dial activity. Code: ${err.code}, Message: ${err.message}`); return false; } } private async checkCallPermission(): Promise<boolean> { try { let atManager = abilityAccessCtrl.createAtManager(); // 检查权限状态 let grantStatus = await atManager.checkAccessToken(abilityAccessCtrl.AccessTokenID.BASE, 'ohos.permission.PLACE_CALL'); return grantStatus === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED; } catch (error) { hilog.error(DOMAIN, TAG, `Check permission failed: ${JSON.stringify(error)}`); return false; } } }

3. 创建代理类，桥接 Dart 与 ArkTS：

   // ohos/src/main/ets/pigeon/CallApiProxy.ts import { CallApi } from './CallApi'; // 一个简单的代理管理器，用于在 EntryAbility 中注册实现 export class CallApiProxy { private static instance: CallApi | null = null; static setup(impl: CallApi): void { CallApiProxy.instance = impl; // 这里可以注册到全局或某个管理器，供 Flutter C++ 层调用。 // 实际上，Flutter Engine 的 OHOS 平台通道会通过 C++ 层调用到这里。 // 下面是一个简化示意，真实集成需要遵循 Flutter OHOS 插件的官方规范。 // 假设我们有一个全局的通道管理器 `pluginChannel`： // pluginChannel.registerHandler('dialNumber', (data) => impl.dialNumber(data.phoneNumber)); console.info('CallApi implementation registered.'); } static getInstance(): CallApi | null { return CallApiProxy.instance; } } // 注意：与 Flutter Engine 的实际 C++/ArkTS 桥接代码需要参考 flutter/ohos 的模板插件来写。 // 上面的 `setup` 和 `getInstance` 是概念性代码。真正的调用链路是从 Flutter C++ 层通过 `dart:ffi` 或平台通道发起， // 经过OHOS的Native层（C++），再通过NAPI调用到这里的ArkTS类。

3.5 步骤五：配置插件与权限

1. 修改ohos/build-profile.json：确保apiType为stageMode，compileSdkVersion与你的 SDK 版本匹配。
2. 配置模块级build-profile.json：确认runtimeOS为HarmonyOS。
3. 声明权限：在ohos/src/main/module.json5中添加拨号权限。

   { "module": { "requestPermissions": [ { "name": "ohos.permission.PLACE_CALL", "reason": "$string:reason_call", "usedScene": { "abilities": ["EntryAbility"], "when": "always" } } ] } }

4. 在resources/base/element/string.json中定义reason_call。

四、 性能优化与调试

4.1 性能优化策略

1. 通信优化：使用Pigeon替代手写MethodChannel，避免了手动编解码，既提升了类型安全，也提高了性能。
2. 懒加载与缓存：在 ArkTS 实现中，像权限检查结果或系统 Ability 信息这类不太变化的数据，可以适当缓存，避免重复查询。
3. FFI 高级路径：如果对延迟极其敏感，可以考虑dart:ffi方案。这需要编写 C/C++ 代码直接调用 OHOS NDK 的AppExecFwk相关 API 来启动 Ability，并编译成动态库（.so）。Dart 端通过ffi直接加载和调用。这种方案牺牲了一些可读性和开发便捷性，但能获得极致的性能，适合那些基础、高频调用的插件。

4.2 调试方法

1. 日志系统：充分利用 OHOS 的hilog进行分级日志输出，在 DevEco Studio 的 Log 窗口查看。
2. HDC 命令行：使用hdc shell连接设备，通过bm命令管理应用，aa命令测试 Ability 启动。

   hdc shell aa start -a ohos.want.action.call -u tel:10086

3. 性能分析：使用 DevEco Studio 的 Profiler 工具分析插件调用过程中的 CPU、内存占用，特别是对比Pigeon与原始MethodChannel的开销差异。

4.3 性能对比数据（模拟）

在搭载 OpenHarmony 4.0 的测试设备上，对dialNumber方法进行 1000 次连续调用（模拟压力测试），粗略对比结果如下：

可以看到，Pigeon在性能、安全性和开发效率上取得了不错的平衡。

五、 集成与总结

5.1 集成到主应用

1. 在你的 Flutter 应用的pubspec.yaml中依赖本地插件路径：

   dependencies: flutter_phone_direct_caller_ohos: path: ../path/to/flutter_phone_direct_caller_ohos

2. 运行flutter pub get。
3. 在 Dart 代码中导入并使用：

   import 'package:flutter_phone_direct_caller_ohos/flutter_phone_direct_caller_ohos.dart'; // ... ElevatedButton( onPressed: () async { bool success = await FlutterPhoneDirectCaller.dialNumber('10010'); ScaffoldMessenger.of(context).showSnackBar( SnackBar(content: Text(success ? '拨号中...' : '调起失败')), ); }, child: const Text('拨打客服'), )

5.2 总结与展望

本文通过flutter_phone_direct_caller这个具体插件，详细展示了将 Flutter 插件适配到 OpenHarmony 平台的完整过程，涵盖了环境准备、技术原理解析、代码实现、性能优化与调试等多个环节。其中的关键点在于：

• 理解双端通信模型：摸清 Flutter Channel 与 OHOS Ability 之间是如何交互的。
• 善用代码生成工具：Pigeon能显著提升跨平台插件的开发质量和效率。
• 遵循平台规范：OHOS 的权限声明、Want构造等方面与 Android 存在差异，需要仔细查阅官方文档。

随着 Flutter 对 OpenHarmony 的支持越来越完善，其插件生态的迁移也会越来越常见。希望本文提供的实战经验能帮助开发者更顺利地将丰富的 Flutter 生态能力引入 OpenHarmony，共同丰富万物互联的生态基石。

后续展望：社区正在积极推动flutter_ohos工具链的成熟以及Pigeon对 ArkTS 的正式支持，未来的适配流程肯定会更加标准化和自动化。大家可以多关注 Flutter 和 OpenHarmony 的官方进展，持续优化自己的适配方案。