AI工具 码道 推荐https://developer.huaweicloud.com/codeartsco.html?sourcedmzntgwatomgit1sourceaddmzntgwatomgiths欢迎加入CPF-Flutter 鸿蒙社区https://atomgit.com/CPF-Flutter本文配套仓库https://atomgit.com/oh-flutter/OH-pedometerpedometer是一个 Flutter 计步插件原生支持 Android 和 iOS可持续返回设备累计步数并根据步伐检测事件判断用户处于walking还是stopped状态。本文以pedometer 4.2.0为例完整介绍它在 HarmonyOS 上的适配思路、工程配置、权限处理、ArkTS 实现和真机验证过程。[!NOTE]本文所说的“鸿蒙化适配”是为 Flutter 插件增加ohos平台实现。业务侧继续使用原有 Dart API不需要为 HarmonyOS 单独维护一套调用代码。一、适配结果速览项目适配结果插件名称pedometer插件版本4.2.0Flutter3.44.9OpenHarmony 版本HarmonyOS7.0.0API 26累计步数已适配SensorId.PEDOMETER步伐检测已适配SensorId.PEDOMETER_DETECTION运行权限ohos.permission.ACTIVITY_MOTION通信方式FlutterEventChannel真机验证累计步数更新、walking与stopped切换均通过这次适配保持了插件原有的两个公开数据流Pedometer.stepCountStream返回设备自最近一次系统启动以来的累计步数Pedometer.pedestrianStatusStream返回walking、stopped或unknownAndroid、iOS 和 HarmonyOS 共用同一套 Flutter 业务代码。二、真机运行验证视频下面的视频由本文配套仓库中的example工程在 HarmonyOS 真机上直接运行录制不是模拟器画面也不是后期制作的示意素材。当前页面不支持内嵌播放请打开下方视频链接查看。视频文件点击查看或下载真机运行视频从视频中可以看到Pedometer Example能够在 HarmonyOS 真机正常启动累计步数从44951更新到44965说明计步传感器事件已通过通道传到 Flutter连续产生步伐事件时页面显示walking停止行走约 2 秒后页面自动切换为stopped。为什么首次显示的是 44951而不是 0这是设备从最近一次系统启动开始累计的步数并非应用启动后的相对步数。该行为与插件原有 API 语义一致。真机验收记录视频可直接确认应用能够在真机启动Flutter 页面能够收到并更新累计步数行走时能够显示walking停止行走后能够显示stopped此外源码检查确认插件在取消订阅和引擎分离时会调用sensor.off用于释放两个传感器监听。权限拒绝、传感器缺失等异常分支仍建议在正式发布前按本文第十三节的步骤逐项回归。三、适配前先梳理插件的数据链路pedometer不是一次请求、一次响应的普通方法调用而是持续监听传感器数据。因此HarmonyOS 侧应使用EventChannel而不是MethodChannel。HarmonyOS 计步传感器 │ ├── SensorId.PEDOMETER ────────── step_count │ │ └── SensorId.PEDOMETER_DETECTION ─ step_detection │ Flutter EventChannel │ ┌───────────────────┴───────────────────┐ │ │ StreamStepCount StreamPedestrianStatus两个通道名必须与 Dart 层完全一致Dart 通道HarmonyOS 传感器输出数据step_countSensorId.PEDOMETER累计步数整数step_detectionSensorId.PEDOMETER_DETECTION单步检测脉冲适配工作的关键不是改业务 API而是让 HarmonyOS 原生层按照这份既有协议发送相同类型的数据。四、声明 Flutter 插件的 OHOS 平台入口首先在插件的pubspec.yaml中增加ohos平台声明flutter:config:enable-swift-package-manager:trueplugin:platforms:android:package:com.example.pedometerpluginClass:PedometerPluginios:pluginClass:PedometerPluginohos:pluginClass:PedometerPlugin这一步告诉 Flutter OHOS 工具链当前包包含一个名为PedometerPlugin的鸿蒙插件实现。完成声明后插件目录需要增加以下结构ohos/ ├── build-profile.json5 ├── hvigorfile.ts ├── index.ets ├── oh-package.json5 └── src/main/ ├── module.json5 ├── ets/components/plugin/PedometerPlugin.ets └── resources/base/element/string.json其中ohos模块类型为har因为它会作为库被业务应用的entry模块依赖{ module: { name: pedometer, type: har, deviceTypes: [ default, tablet ], requestPermissions: [ { name: ohos.permission.ACTIVITY_MOTION, reason: $string:activity_motion_reason } ] } }五、导出并注册插件ohos/index.ets是模块对 Flutter 工具链暴露的入口importPedometerPluginfrom./src/main/ets/components/plugin/PedometerPlugin;exportdefaultPedometerPlugin;PedometerPlugin实现FlutterPlugin接口并提供唯一类名exportdefaultclassPedometerPluginimplementsFlutterPlugin{getUniqueClassName():string{returnPedometerPlugin;}onAttachedToEngine(binding:FlutterPluginBinding):void{// 创建 EventChannel 并注册 StreamHandler。}onDetachedFromEngine(_binding:FlutterPluginBinding):void{// 停止传感器监听并释放通道。}}示例应用中的EntryAbility通过自动生成的注册器加载插件configureFlutterEngine(flutterEngine:FlutterEngine){super.configureFlutterEngine(flutterEngine)GeneratedPluginRegistrant.registerWith(flutterEngine)}GeneratedPluginRegistrant.ets是 Flutter 工具链生成的文件不应手工维护也不应作为适配代码复制到其他项目。六、实现累计步数事件通道先定义与 Dart 层一致的通道名并保存通道、事件出口和监听状态constSTEP_COUNT_CHANNELstep_count;privatestepCountChannel:EventChannel|nullnull;privatestepCountSink:EventSink|nullnull;privateisStepCountListening:booleanfalse;privatereadonlystepCountCallback(data:sensor.PedometerResponse,):void{this.stepCountSink?.success(Math.trunc(data.steps));};Flutter 开始监听时订阅系统传感器取消监听时解除订阅this.stepCountChannelnewEventChannel(binding.getBinaryMessenger(),STEP_COUNT_CHANNEL,);this.stepCountChannel.setStreamHandler({onListen:(_arguments:Object,events:EventSink):void{this.startStepCount(events);},onCancel:(_arguments:Object):void{this.stopStepCount();},});核心订阅逻辑如下privatestartStepCount(events:EventSink):void{this.stopStepCount();if(!this.isSensorAvailable(sensor.SensorId.PEDOMETER,events,Step Count,)){return;}this.stepCountSinkevents;try{sensor.on(sensor.SensorId.PEDOMETER,this.stepCountCallback);this.isStepCountListeningtrue;}catch(error){this.stepCountSinknull;this.reportError(events,Step Count,errorasBusinessError);}}这里有三个值得保留的细节新订阅开始前先调用stopStepCount()避免重复监听使用Math.trunc把系统返回值转换为 Dart 层预期的整数同时保存isStepCountListening与EventSink便于插件销毁时正确释放资源。七、实现步伐检测事件通道步伐检测通道的生命周期与累计步数通道相同但底层传感器 ID 不同constSTEP_DETECTION_CHANNELstep_detection;privatereadonlystepDetectionCallback(data:sensor.PedometerDetectionResponse,):void{this.stepDetectionSink?.success(Math.trunc(data.scalar));};privatestartStepDetection(events:EventSink):void{this.stopStepDetection();if(!this.isSensorAvailable(sensor.SensorId.PEDOMETER_DETECTION,events,Step Detection,)){return;}this.stepDetectionSinkevents;try{sensor.on(sensor.SensorId.PEDOMETER_DETECTION,this.stepDetectionCallback,);this.isStepDetectionListeningtrue;}catch(error){this.stepDetectionSinknull;this.reportError(events,Step Detection,errorasBusinessError);}}HarmonyOS 原生层只负责把检测脉冲送到 Flutter。walking与stopped的状态转换仍沿用插件原有 Dart 逻辑持续收到脉冲时为walking连续 2 秒没有新脉冲则切换为stopped。这样可以保持 Android 与 HarmonyOS 的表现一致。八、检查设备能力并统一错误返回不同设备不一定同时提供累计计步和步伐检测传感器因此不能直接假设传感器存在。订阅前应查询设备传感器列表privateisSensorAvailable(type:sensor.SensorId,events:EventSink,label:string,):boolean{try{constavailablesensor.getSensorListSync().some((item:sensor.Sensor)item.sensorIdtype,);if(!available){events.error(UNAVAILABLE,${label}is not available on this device,null,);}returnavailable;}catch(error){this.reportError(events,label,errorasBusinessError);returnfalse;}}错误统一通过EventSink.error回传privatereportError(events:EventSink,label:string,error:BusinessError,):void{constcodeerror.code201?PERMISSION_DENIED:UNAVAILABLE;constmessageerror.message??${label}is not available;hilog.error(0,TAG,${label}error:${error.code}${message});events.error(code,message,null);}错误码含义业务侧建议PERMISSION_DENIED用户未授权运动权限引导用户授权后重新订阅UNAVAILABLE设备无对应传感器或系统调用失败降级显示并停止依赖该能力九、在 Dart 层识别 OHOS 平台原插件在 Android 上会把单步检测脉冲转换为行走状态。HarmonyOS 的PEDOMETER_DETECTION也提供同类脉冲因此只需让 OHOS 复用这段逻辑importdart:ioshowPlatform;staticStreamPedestrianStatusgetpedestrianStatusStream{StreamPedestrianStatusstream_stepDetectionChannel.receiveBroadcastStream().map((event)PedestrianStatus._(event));if(Platform.isAndroid||Platform.operatingSystemohos){return_stepDetectionStream(stream);}returnstream;}累计步数 API 无需增加平台分支因为原生层已经确保发送的是整数staticStreamStepCountgetstepCountStream_stepCountChannel.receiveBroadcastStream().map((event)StepCount._(event));这种做法保留了插件的公共接口已有业务代码升级到鸿蒙适配版本后无需修改调用方式。十、配置运动权限计步能力属于受保护的运动数据。仅在 HAR 模块里声明权限还不够最终应用的entry模块也要声明权限并在运行时向用户申请。10.1 在 entry 模块声明权限编辑业务应用的ohos/entry/src/main/module.json5{ module: { requestPermissions: [ { name: ohos.permission.ACTIVITY_MOTION, reason: $string:activity_motion_reason, usedScene: { abilities: [EntryAbility], when: inuse } } ] } }然后在资源文件中补充权限说明例如{string:[{name:activity_motion_reason,value:用于计步和检测步行状态}]}10.2 在 EntryAbility 动态申请权限示例工程在EntryAbility.onCreate中申请权限privateasyncrequestActivityMotionPermission():Promisevoid{constpermissions:ArrayPermissions[ohos.permission.ACTIVITY_MOTION,];try{constresultawaitabilityAccessCtrl.createAtManager().requestPermissionsFromUser(this.context,permissions);if(result.authResults.length0||result.authResults[0]!0){console.warn(ACTIVITY_MOTION permission was not granted.);}}catch(error){constbusinessErrorerrorasBusinessError;console.error(Failed to request ACTIVITY_MOTION permission:${businessError.code}${businessError.message},);}}[!IMPORTANT]必须先完成授权再订阅两个事件流。权限被拒绝时不要循环弹窗应在 Flutter 页面说明功能不可用并允许用户稍后重新授权。十一、配置 HarmonyOS 构建工程示例工程使用以下 SDK 配置{ app: { products: [ { name: default, signingConfig: default, compatibleSdkVersion: 5.1.0(18), compileSdkVersion: 26.0.0, targetSdkVersion: 26.0.0, runtimeOS: HarmonyOS } ] } }使用 API 26 构建时应安装与该 SDK 匹配的 DevEco Studio并使用它自带的 Hvigor 6.26.x 工具链。Flutter OHOS SDK 可从社区仓库获取gitclone https://atomgit.com/CPF-Flutter/flutter_flutter.git\-boh-3.44.9-devexportPATH$PWD/flutter_flutter/bin:$PATHflutter--versionflutter doctor-v调试签名使用 DevEco Studio 打开example/ohos在File Project Structure Signing Configs中配置本机调试签名。不要把以下信息写进文章或提交到公共仓库证书和 Profile 的本机绝对路径keyPassword、storePassword等口令.p12私钥文件、.cer证书和.p7bProfile。十二、从 AtomGit 引入适配后的插件业务项目可在pubspec.yaml中直接依赖配套仓库的main分支dependencies:flutter:sdk:flutterpedometer:git:url:https://atomgit.com/oh-flutter/OH-pedometer.gitref:main执行依赖解析flutter pub getFlutter 侧调用方式与 Android、iOS 保持一致lateStreamStepCount_stepCountStream;lateStreamPedestrianStatus_pedestrianStatusStream;voidonStepCount(StepCountevent){finalint stepsevent.steps;finalDateTimetimeStampevent.timeStamp;print(steps$steps, time$timeStamp);}voidonPedestrianStatusChanged(PedestrianStatusevent){finalStringstatusevent.status;finalDateTimetimeStampevent.timeStamp;print(status$status, time$timeStamp);}voidinitPedometer(){_stepCountStreamPedometer.stepCountStream;_pedestrianStatusStreamPedometer.pedestrianStatusStream;_stepCountStream.listen(onStepCount).onError((error)print(step count error:$error));_pedestrianStatusStream.listen(onPedestrianStatusChanged).onError((error)print(status error:$error));}十三、构建与验证进入示例工程后依次执行cdexample flutter pub get flutter analyze fluttertestflutter build hap--debugflutter devices flutter run-ddevice-id建议按下面的顺序做真机回归首次启动应用允许运动权限记录页面初始累计步数持手机连续步行确认步数递增并显示walking停止行走并等待至少 2 秒确认状态变为stopped退出并重新进入页面确认没有重复订阅或崩溃拒绝权限后重新测试确认错误能够回传到 Flutter在不支持对应传感器的设备上验证降级提示。点击展开常见问题排查1. 应用启动后一直显示问号检查ACTIVITY_MOTION是否同时完成静态声明和动态授权并确认订阅发生在授权完成之后。2. 初始步数很大这是累计计步传感器的正常语义。若业务需要“本次运动步数”请在开始运动时保存基准值展示当前累计值 - 基准值。3. 行走停止后状态没有立刻变化当前 Dart 实现使用 2 秒定时器判断停止状态因此存在约 2 秒的设计延迟。4. 真机可以运行但模拟器没有数据计步依赖真实运动传感器。最终验收应以真机为准模拟器只能用于检查页面和插件注册是否正常。5. 构建阶段提示 Hvigor 或 SDK 不兼容确认compileSdkVersion、targetSdkVersion、DevEco Studio 与 Hvigor 属于同一套兼容版本不要混用旧版全局 Hvigor。6. 提示设备不支持传感器通过sensor.getSensorListSync()检查PEDOMETER和PEDOMETER_DETECTION。两个能力应分别判断业务页面也应允许只展示可用的一项。十四、适配要点总结本次pedometer鸿蒙化适配没有改变插件的 Dart 公共 API而是在 OHOS 原生层补齐了相同的数据协议在pubspec.yaml注册ohos插件入口新建 HAR 模块并导出PedometerPlugin用两个EventChannel分别桥接累计步数和步伐检测通过SensorId.PEDOMETER与SensorId.PEDOMETER_DETECTION订阅系统传感器在应用侧声明并动态申请ACTIVITY_MOTION权限复用 Dart 层的 2 秒状态判断逻辑维持跨平台 API 一致性使用真实 HarmonyOS 设备完成步数递增和行走状态切换验证。最终原有 Flutter 业务代码可以无感复用HarmonyOS 平台也能持续获得累计步数与步行状态。相关链接CPF-Flutter 鸿蒙社区https://atomgit.com/CPF-FlutterFlutter OHOS SDKhttps://atomgit.com/CPF-Flutter/flutter_flutterPedometer 适配仓库https://atomgit.com/oh-flutter/OH-pedometerPedometer Issueshttps://atomgit.com/oh-flutter/OH-pedometer/issuesAI工具 码道https://developer.huaweicloud.com/codeartsco.html?sourcedmzntgwatomgit1sourceaddmzntgwatomgiths本文代码、配置和验证结果以配套仓库当前main分支为准。Flutter OHOS 工具链、HarmonyOS SDK 与设备传感器能力会持续演进升级依赖后请重新执行静态检查、构建和真机回归。