Flutter device_info_plus库在鸿蒙端的设备信息获取适配实践

引言

OpenHarmony（以下简称鸿蒙）生态这几年发展很快，分布式架构和全场景能力吸引了越来越多开发者的目光。在这种背景下，跨平台开发框架与鸿蒙的深度融合，已经成了一个明显的技术趋势。Flutter 作为目前主流的跨平台 UI 工具包，凭借高效的渲染引擎、一致的体验和丰富的插件生态，成了许多团队开发复杂跨端应用的首选。

不过，Flutter 生态虽然强大，但不少优秀的社区插件还没有官方支持鸿蒙平台。这成了我们把现有 Flutter 应用迁移到鸿蒙、或者为鸿蒙全新开发应用时的一个现实障碍。就拿设备信息获取来说——这几乎是所有应用的基础需求（比如数据统计、设备识别或兼容性判断），但社区常用的device_info_plus插件在鸿蒙端缺失，直接导致很多功能无法正常使用。

所以，本文就以device_info_plus的鸿蒙适配为例，从头到尾走一遍适配的原理、步骤和落地实践。我们会从 Flutter 的通信机制讲起，接着深入鸿蒙系统的 API 设计，最后给出一个完整、可运行、性能也不错的适配方案。目标不只是解决眼前这个问题，更希望能为大家提供一个可复制、可扩展的 Flutter 插件鸿蒙适配思路，一起推动 Flutter 生态在鸿蒙平台上的发展。

一、技术背景与原理分析

1.1 Flutter 插件的跨平台通信机制

Flutter 应用的主体是 Dart 代码，运行在 Dart 虚拟机里，不能直接调用操作系统底层的原生 API。为了打通这个壁垒，Flutter 设计了Platform Channel（平台通道）这套通信机制。它本质上是一个异步消息系统，让 Dart 代码能够和安全、高效地和原生平台（Android 的 Java/Kotlin、iOS 的 Swift/OC、鸿蒙的 ArkTS/Java）进行对话。

device_info_plus插件主要依赖MethodChannel（方法通道）。它的工作流程可以简单概括为下面几步：

1. Dart 端发起调用：在 Flutter 应用里执行如DeviceInfoPlugin().deviceInfo。
2. 消息编码：插件内部通过一个事先约定好的通道名称（例如‘dev.fluttercommunity.plus/device_info’）创建MethodChannel实例，然后把方法名（比如‘getAndroidDeviceInfo’）和参数（设备信息获取通常为空）序列化成二进制消息。
3. 消息传递：编码后的消息经过 Flutter 引擎的 C++ 层，从 Dart 的隔离堆传到原生平台的环境。
4. 原生端处理：在原生端（这里就是鸿蒙），一个实现了MethodChannel.MethodHandler接口的对象会监听同名的通道。消息一到，它的onMethodCall方法就被触发。
5. 调用原生 API：在onMethodCall内部，根据call.method判断要执行什么操作，然后调用对应的鸿蒙系统 API（比如@ohos.deviceInfo模块）来收集设备信息。
6. 结果返回：把收集到的信息（品牌、型号、系统版本等）组织成 Map 结构，序列化成二进制格式，再通过通道原路返回给 Dart 端。
7. Dart 端解析：Dart 端收到响应，把二进制数据反序列化成 Dart 对象（通常是Map<String, dynamic>），最后交给开发者使用。

整个过程是异步的，保证了 UI 不会卡顿。

1.2 鸿蒙系统的设备信息 API

鸿蒙系统通过@ohos.deviceInfo模块提供设备软硬件信息的获取接口。这个模块遵循鸿蒙的 FA/Stage 模型，接口设计比较清晰，涵盖的信息也比较全。常用的接口包括：

• 基础设备标识：
  • getModel(): 获取设备型号（例如 “HarmonyOS Phone”）。
  • getBrand(): 获取设备品牌（例如 “HUAWEI”）。
  • getManufacturer(): 获取设备制造商。
  • getProduct(): 获取产品名称。
  • getSerial(): 获取设备序列号（需要权限）。
• 系统信息：
  • getOsFullName(): 获取完整的操作系统名称（例如 “OpenHarmony 4.0.0”）。
  • getDisplayVersion(): 获取对用户显示的版本号。
  • getIncrementalVersion(): 获取系统源码的版本号。
  • getSecurityPatchTag(): 获取安全补丁级别。
• 硬件信息：
  • getUdid(): 获取设备唯一标识（需要权限，其机制与 Android ID/IDFA 不同）。
  • getBootloaderVersion()、getAbiList()等，提供更底层的硬件细节。

关键的适配点在于，鸿蒙的 API 命名、返回值类型以及权限模型（比如获取 UDID 需要ohos.permission.APPROXIMATELY_LOCATION）和 Android 有明显区别。所以适配的核心工作之一，就是设计一个“翻译层”，把鸿蒙 API 的返回结果，映射到device_info_plus的 Dart 接口所期望的、并与 Android/iOS 数据结构尽量一致的模型上。

二、完整适配方案设计与实现

2.1 项目结构与工程配置

首先，我们需要在device_info_plus插件的原生代码目录里创建鸿蒙端的实现。一个标准的 Flutter 插件项目结构大致如下：

device_info_plus/ ├── lib/ │ └── device_info_plus.dart # Dart 公共接口 ├── android/ # Android 实现 ├── ios/ # iOS 实现 └── harmonyos/ # 新建：鸿蒙实现目录 ├── src/main/ │ ├── ets/ │ │ ├── entry/ │ │ │ └── src/main/ │ │ │ ├── ets/ │ │ │ │ ├── DeviceInfoPlus.ets # 核心实现类 │ │ │ │ └── utils/ │ │ │ └── resources/ # 资源文件 │ │ └── module.json5 # 鸿蒙模块配置文件 │ └── resources/... └── build.gradle.kts 或 build-profile.json5 # 鸿蒙构建配置

接着，在插件的pubspec.yaml里声明对鸿蒙平台的支持：

flutter: plugin: platforms: android: package: dev.fluttercommunity.plus.device_info pluginClass: DeviceInfoPlusPlugin ios: pluginClass: DeviceInfoPlusPlugin harmonyos: # 新增鸿蒙平台声明 pluginClass: DeviceInfoPlusHarmonyOSPlugin

2.2 鸿蒙端核心实现代码

以下是完整的鸿蒙（ArkTS）端适配类，包含了详细的错误处理和数据映射逻辑：

// DeviceInfoPlus.ets import deviceInfo from '@ohos.deviceInfo'; import { BusinessError } from '@ohos.base'; import hilog from '@ohos.hilog'; import { MethodChannel, MethodData, MethodCodec, StandardMethodCodec } from '@ohos.flutter.plugin'; // 定义与 Dart 端约定的方法名和通道名 const METHOD_GET_DEVICE_INFO = 'getHarmonyOSDeviceInfo'; const CHANNEL_NAME = 'dev.fluttercommunity.plus/device_info'; // 定义返回给 Dart 端的数据模型 interface HarmonyDeviceInfo { brand: string; // 对应 android.brand / ios.model model: string; // 对应 android.model / ios.model manufacturer: string; // 对应 android.manufacturer product: string; // 对应 android.product osVersion: string; // 对应 android.version.release / ios.systemVersion sdkInt: number; // 对应 android.sdkInt incrementalVersion: string; // 对应 android.version.incremental displayVersion: string; // 鸿蒙特有字段，也可一并映射 serial?: string; // 需要权限，可能为空 udid?: string; // 需要权限，可能为空 isPhysicalDevice: boolean; // 是否为物理设备 } export class DeviceInfoPlusHarmonyOSPlugin { private channel: MethodChannel; constructor() { // 初始化 MethodChannel，使用标准编解码器 this.channel = new MethodChannel({ name: CHANNEL_NAME, codec: StandardMethodCodec.getInstance() }); this.channel.setMethodCallHandler(this.onMethodCall.bind(this)); } // 核心：处理来自 Dart 端的调用 private onMethodCall(call: MethodData): void { hilog.info(0x0000, 'DeviceInfoPlus', 'Method called: %{public}s', call.method); try { switch (call.method) { case METHOD_GET_DEVICE_INFO: const deviceInfoData = this._getDeviceInfo(); call.replySuccess(deviceInfoData); break; default: call.replyNotImplemented(); } } catch (error) { const businessError = error as BusinessError; hilog.error(0x0000, 'DeviceInfoPlus', 'Error in onMethodCall: %{public}s', JSON.stringify(businessError)); call.replyError( 'DEVICE_INFO_ERROR', `Failed to get device info: ${businessError.code} - ${businessError.message}`, businessError ); } } // 收集鸿蒙设备信息 private _getDeviceInfo(): HarmonyDeviceInfo { let info: HarmonyDeviceInfo; try { const brand = deviceInfo.getBrand(); const model = deviceInfo.getModel(); const manufacturer = deviceInfo.getManufacturer(); const product = deviceInfo.getProduct(); const osFullName = deviceInfo.getOsFullName(); const displayVersion = deviceInfo.getDisplayVersion(); const incrementalVersion = deviceInfo.getIncrementalVersion(); deviceInfo.getSecurityPatchTag(); // 可按需使用 // 估算 SDK 版本（示例逻辑，实际需查阅官方映射） const sdkInt = this._estimateHarmonyOSApiVersion(displayVersion); info = { brand: brand || 'unknown', model: model || 'unknown', manufacturer: manufacturer || 'unknown', product: product || 'unknown', osVersion: osFullName || displayVersion || 'unknown', sdkInt: sdkInt, incrementalVersion: incrementalVersion || '', displayVersion: displayVersion || '', serial: this._tryGetSerial(), udid: this._tryGetUdid(), // 简单判断是否为模拟器，生产环境需更严谨 isPhysicalDevice: !model.toLowerCase().includes('simulator') && !model.toLowerCase().includes('emulator') }; } catch (apiError) { hilog.error(0x0000, 'DeviceInfoPlus', 'Failed to call HarmonyOS API: %{public}s', JSON.stringify(apiError)); info = this._getFallbackDeviceInfo(); } return info; } // 尝试获取序列号（需要权限） private _tryGetSerial(): string | undefined { try { return deviceInfo.getSerial(); } catch (permissionError) { hilog.warn(0x0000, 'DeviceInfoPlus', 'Cannot get serial, permission may be denied.'); return undefined; } } // 尝试获取 UDID（需要权限） private _tryGetUdid(): string | undefined { try { // 需要 ohos.permission.APPROXIMATELY_LOCATION 权限 return deviceInfo.getUdid(); } catch (permissionError) { hilog.warn(0x0000, 'DeviceInfoPlus', 'Cannot get UDID, permission may be denied.'); return undefined; } } // 根据版本号估算 API Level（示例逻辑，需按官方文档调整） private _estimateHarmonyOSApiVersion(displayVersion: string): number { const match = displayVersion.match(/(\d+)\.(\d+)\.(\d+)/); if (match) { const major = parseInt(match[1], 10); // 简化映射，例如 OpenHarmony 4.0.0 对应 API 10+ return major + 6; } return 0; } // 降级方案：当 API 全部失败时返回最小化信息 private _getFallbackDeviceInfo(): HarmonyDeviceInfo { return { brand: 'unknown', model: 'unknown', manufacturer: 'unknown', product: 'unknown', osVersion: 'unknown', sdkInt: 0, incrementalVersion: '', displayVersion: '', isPhysicalDevice: true }; } // 插件注册方法，供 Flutter 引擎调用 static register(): void { new DeviceInfoPlusHarmonyOSPlugin(); hilog.info(0x0000, 'DeviceInfoPlus', 'DeviceInfoPlus HarmonyOS plugin registered successfully.'); } } // 模块加载时自动注册 DeviceInfoPlusHarmonyOSPlugin.register();

2.3 Dart 端兼容性封装

为了让 Dart 层代码无需关心底层平台差异，我们需要在device_info_plus的 Dart 库里增加对鸿蒙平台的判断和封装：

// 在原有 device_info_plus.dart 中扩展 import 'dart:io' show Platform; class DeviceInfoPlus { // ... 其他代码 Future<BaseDeviceInfo> get deviceInfo async { if (Platform.isAndroid) { // 原有 Android 逻辑 } else if (Platform.isIOS) { // 原有 iOS 逻辑 } else if (_isHarmonyOS) { // 新增鸿蒙判断 return _getHarmonyOSInfo(); } else { throw UnsupportedError('Unsupported platform'); } } // 判断是否为鸿蒙平台 static bool get _isHarmonyOS { // 可通过环境变量、FFI 或引擎特性判断，此处为示例 return const bool.fromEnvironment('HARMONYOS', defaultValue: false); } Future<HarmonyOSDeviceInfo> _getHarmonyOSInfo() async { final Map<String, dynamic> data = await _channel.invokeMethod('getHarmonyOSDeviceInfo'); return HarmonyOSDeviceInfo.fromMap(data); } } // 鸿蒙设备信息模型类 class HarmonyOSDeviceInfo implements BaseDeviceInfo { final String brand; final String model; final String manufacturer; final String product; final String osVersion; final int sdkInt; final String incrementalVersion; final String displayVersion; final String? serial; final String? udid; final bool isPhysicalDevice; HarmonyOSDeviceInfo({ required this.brand, required this.model, required this.manufacturer, required this.product, required this.osVersion, required this.sdkInt, required this.incrementalVersion, required this.displayVersion, this.serial, this.udid, required this.isPhysicalDevice, }); factory HarmonyOSDeviceInfo.fromMap(Map<String, dynamic> map) { return HarmonyOSDeviceInfo( brand: map['brand'] as String? ?? 'unknown', model: map['model'] as String? ?? 'unknown', manufacturer: map['manufacturer'] as String? ?? 'unknown', product: map['product'] as String? ?? 'unknown', osVersion: map['osVersion'] as String? ?? 'unknown', sdkInt: (map['sdkInt'] as num?)?.toInt() ?? 0, incrementalVersion: map['incrementalVersion'] as String? ?? '', displayVersion: map['displayVersion'] as String? ?? '', serial: map['serial'] as String?, udid: map['udid'] as String?, isPhysicalDevice: map['isPhysicalDevice'] as bool? ?? true, ); } @override Map<String, dynamic> toMap() { return { 'brand': brand, 'model': model, 'manufacturer': manufacturer, 'product': product, 'osVersion': osVersion, 'sdkInt': sdkInt, 'incrementalVersion': incrementalVersion, 'displayVersion': displayVersion, 'serial': serial, 'udid': udid, 'isPhysicalDevice': isPhysicalDevice, 'platform': 'HarmonyOS', }; } }

三、集成步骤与实践指南

3.1 环境准备与项目配置

1. 开发环境：
   • 安装 Flutter SDK（建议 3.19.0 或更高版本，对鸿蒙支持更完善）。
   • 安装 DevEco Studio 4.0+，并配置好 OpenHarmony SDK。
   • 确保 Flutter 项目已支持鸿蒙平台（可通过flutter create --platforms=harmonyos .生成，或手动配置）。
2. 插件集成：
   • 方式一（修改社区插件）：Forkdevice_info_plus仓库，将上述鸿蒙实现代码放入harmonyos/目录，然后在项目的pubspec.yaml中通过git依赖指向你的分支。
   • 方式二（作为本地插件）：在项目里新建一个harmonyos_device_info_plus插件包，实现上述代码，然后在主项目的pubspec.yaml中通过path引用。
3. 权限配置：在鸿蒙工程的module.json5中按需添加权限声明。

   { "module": { "requestPermissions": [ { "name": "ohos.permission.APPROXIMATELY_LOCATION", "reason": "$string:reason_udid", "usedScene": { "ability": ["EntryAbility"], "when": "always" } } ] } }

3.2 调试与问题排查

1. 查看日志：利用鸿蒙的hilog系统输出日志。在DeviceInfoPlus.ets的关键节点添加日志，然后通过hdc shell hilog | grep DeviceInfoPlus在终端过滤查看。
2. 测试通道连通性：在 Dart 端可以写个简单的测试，确认通道是否建立成功。

   final testChannel = MethodChannel('dev.fluttercommunity.plus/device_info'); try { final result = await testChannel.invokeMethod('testPing'); print('Channel is working: $result'); } on PlatformException catch (e) { print('Channel failed: ${e.message}'); }

3. 验证数据格式：确保 ArkTS 端返回的Map能被StandardMethodCodec正确编码。尽量避免使用undefined（用null代替）和过于复杂的嵌套对象。
4. 处理权限动态申请：对于serial和udid这类敏感信息，应在 ArkTS 端实现动态权限申请逻辑，并在用户拒绝后提供降级处理。

3.3 性能优化建议

1. 数据缓存：设备信息在应用生命周期内基本不会变。可以在 ArkTS 端做一次静态缓存，避免反复调用系统 API。

   private static cachedInfo: HarmonyDeviceInfo | null = null; private _getDeviceInfo(): HarmonyDeviceInfo { if (DeviceInfoPlusHarmonyOSPlugin.cachedInfo) { return DeviceInfoPlusHarmonyOSPlugin.cachedInfo; } // ... 原始获取逻辑 DeviceInfoPlusHarmonyOSPlugin.cachedInfo = info; return info; }

2. 懒加载：插件的注册和通道监听可以在启动时完成，但实际的数据获取可以延迟到首次调用时进行。
3. 精简数据：只收集和返回 Dart 端真正需要的字段。可以通过在MethodCall里传递参数，让 Dart 端指定需要哪些信息，减少不必要的数据传输。

四、性能对比与数据

我们在同一台运行 OpenHarmony 4.0 的华为设备上做了简单的性能对比测试：

五、总结与展望

通过上面的步骤，我们完成了device_info_plus库在鸿蒙端的适配。整个过程从理解 Flutter 的 Platform Channel 通信机制开始，到深入鸿蒙的设备信息 API，最后通过具体的 ArkTS 和 Dart 代码实现了一座连接 Dart 生态和鸿蒙原生能力的桥梁。

这次实践的核心收获，是总结出了一套通用的适配思路：

1. 理解通信机制：吃透 MethodChannel 的工作流程是基础。
2. 做好 API 与数据模型的映射：准确地把目标平台的 API 映射到插件约定的通用数据结构上是关键。
3. 保证健壮性：完善的错误处理、权限申请和降级方案是稳定性的前提。
4. 关注性能：适当使用缓存、懒加载等手段优化体验。

随着 OpenHarmony 生态的持续发展和 Flutter 对鸿蒙官方支持的完善，未来肯定会有更多社区插件官方适配鸿蒙。但在现阶段，掌握上面这套方法，能让你具备主动扩展 Flutter 能力边界的能力——不仅仅是设备信息，其他原生功能也可以快速集成到 Flutter 鸿蒙应用里，在全场景互联的时代保持技术上的主动性。

让跨平台开发，真正覆盖到每一个平台。