★ FEATURED ARTICLE 很多人学HarmonyOS位置服务都停在把当前经纬度打出来这一步——拿一次定位画个点完事。但位置服务真正有魅力的地方是和方向传感器结合起来形成一种位置朝向的空间判断能力。这也是我这次做位置与方向寻宝的初衷用一个有点游戏感的Demo把定位获取、持续监听、方向传感器、罗盘UI、距离与方位角计算全部串成一条完整链路。文章不是文档复述而是我从零搭起这个项目时的完整思路、代码细节和踩坑记录适合已经能熟练写页面和状态管理的开发者也适合想认真理解HarmonyOS定位与传感器API的新手。1. 先搞清楚寻宝这个Demo到底在练什么基本功1.1 一个看似游戏实则硬核的场景拆解寻宝听起来像玩具但把它拆开看其实是两个系统级能力在协作一个是地理定位告诉你你在哪、你动了没有另一个是方向传感器告诉你你的手机朝哪个方向。合在一起就构成一个完整的空间判断模型——这也是导航、AR引导、探宝类应用、室内导览等场景最核心的那块地基。我给的设定很简单在页面里预设一个宝藏点的经纬度坐标用户拿着手机在真实空间里走动App实时计算当前定位与宝藏点的距离并在屏幕上给出提示。当用户靠近到一定范围、且手机朝向也基本对准宝藏方向时就算找到宝藏。这样设计定位误差、方向抖动、角度差值计算、传感器回调频率控制这些问题全部会暴露出来比单纯读一个经纬度接口有价值得多。1.2 主流程与状态机设计这个Demo的关键是要想清楚用户从开始到成功的路径是什么每个阶段的提示是什么我在动手写代码之前先画了一个简单的状态流转——放在前面说是因为后面所有代码都围绕它展开初始状态App启动请求定位权限显示开始寻宝按钮。寻找中拿到实时坐标计算并展示与宝藏点的距离同时读取方向传感器让一个罗盘指针指向目标方位。接近状态距离进入阈值比如30米内提示已经很近了罗盘指针强化显示。命中状态距离小于命中半径比如15米且朝向偏差在合理范围内连续若干次判定通过触发找到宝藏成功界面。结束状态清除监听、停止传感器回调展示成绩或重新开始的入口。状态机用两个判定条件做约束距离判定和朝向判定。只算距离会太无聊只算朝向又不符合寻宝直觉两者组合才能把一个定位Demo升级成空间交互Demo。后面每一块代码都服务于这套状态逻辑读者可以先把这个状态表记在心里再往下看实现方式。2. 权限与基础环境准备LocationKit能用的前提条件2.1 权限声明与实际申请HarmonyOS的位置服务包是kit.LocationKit模块名叫geoLocationManager。用之前必须做两件事第一在模块配置文件里声明权限第二在运行时动态申请用户授权。只做第一件不做第二件调用接口时会失败而且错误码比较难排查——很多新手都卡在这一步。在配置文件src/main/module.json5的requestPermissions节点里加上{ requestPermissions: [ { name: ohos.permission.LOCATION, reason: 用于获取当前位置以完成寻宝游戏, usedScene: { abilities: [EntryAbility], when: inuse } } ] }这里要补充一点ohos.permission.LOCATION在授权类型上属于用户授权也就是必须弹窗让用户肉眼确认。when字段填inuse表示只在前台使用这是我最推荐的模式。如果位置服务需要在后台持续使用得额外申请后台位置权限ohos.permission.LOCATION_BACKGROUND而且上架审核时会要求说明用途复杂度直接上一个台阶。我做的寻宝场景全程前台所以不碰后台权限。2.2 动态申请权限的正确姿势权限声明配好后运行时还要调用授权接口。使用kit.AbilityKit里的abilityAccessCtrl来处理import { abilityAccessCtrl, Permissions } from kit.AbilityKit; import { BusinessError } from kit.BasicServicesKit; async function requestLocationPermission(): Promiseboolean { const permissions: Permissions[] [ohos.permission.LOCATION]; const atManager abilityAccessCtrl.createAtManager(); try { const result await atManager.requestPermissionsFromUser(permissions); const authResult result.authResults[0]; return authResult 0; // 0 表示授权成功 } catch (err) { const error err as BusinessError; console.error(请求权限失败: ${error.code}, ${error.message}); return false; } }这里有一个容易忽略的经验点requestPermissionsFromUser在用户首次点击拒绝后再次调用时可能不会再弹窗而是直接返回拒绝结果。所以我在页面里加了一个兜底逻辑——如果授权失败显示一个说明页面引导用户去系统设置里手动打开定位。开发阶段可能觉得烦但真要给用户使用时这是必备的体验兜底。2.3 LocationRequest参数配置定位不是随手调一个接口就行的关键在于LocationRequest参数。我用表格把几个重要字段说明一下这是整个项目中第一个有门道的地方参数作用我的设置说明priority定位优先级FIRST_FIX首帧定位优先适合打开就快点出位置的场景scenario使用场景NAVIGATION导航场景会更激进地调用GNSS提高精度maxAccuracy期望精度5单位米值越小对硬件要求越高太苛刻容易定位超时timeInterval回调时间间隔1单位秒控制更新频率避免频繁刷新distanceInterval回调距离间隔1单位米移动超过1米才回调注意FIRST_FIX和ACCURACY的区别。ACCURACY追求精度但首帧可能很慢FIRST_FIX则是尽快给第一帧误差先不管。我在寻宝场景里用FIRST_FIX加maxAccuracy:5后面再通过持续监听不断修正。实际体感是第一次定位大约1到3秒市区室外精度大概5到10米完全够用。3. 设备定位的获取与持续监听经纬度只是第一步3.1 一次性定位与持续监听的组合打法拿到权限后就是核心环节取坐标。geoLocationManager给了一键定位getCurrentLocation()和持续监听on(locationChange)两个入口。新手常犯的误区是只用一次性定位——但在寻宝场景里用户是会走动的一次性坐标只能保证打开那一刻你在哪没法感知你在往哪移动。要做出越来越近的体验必须上持续监听。我的做法是进入寻宝页面后先调一次getCurrentLocation让UI立刻有数据显示这一步叫首帧初始化然后马上注册locationChange监听后续所有坐标更新走监听回调持续修正位置。初始化那一下不是为了省事而是让用户面对的不是空白的等待界面。import { geoLocationManager } from kit.LocationKit; let locationRequest: geoLocationManager.LocationRequest { priority: geoLocationManager.LocationRequestPriority.FIRST_FIX, scenario: geoLocationManager.LocationRequestScenario.NAVIGATION, maxAccuracy: 5, timeInterval: 1, distanceInterval: 1 }; // 1. 首帧定位 geoLocationManager.getCurrentLocation(locationRequest).then((location) { updateUserLocation(location); }).catch((err) { console.error(定位失败: ${JSON.stringify(err)}); }); // 2. 持续监听 geoLocationManager.on(locationChange, locationRequest, (location) { updateUserLocation(location); });3.2 拿到坐标之后要做的数据清洗监听回调里的location对象有latitude、longitude、accuracy、timeStamp等字段。直接拿latitude和longitude就去算距离我的经验是先在updateUserLocation()里做两道清洗第一道判空和异常值。监听回调不能保证每次都有效拿到的坐标可能是0,0这种无效数据直接参与计算会得到离谱的距离。我的做法是过滤掉经纬度都为0的坐标并检查accuracy字段超过80米的定位结果直接丢弃等下一帧。function isValidLocation(location: geoLocationManager.Location): boolean { if (!location || !location.latitude || !location.longitude) { return false; } // accuracy 单位是米大于 80 米的坐标对寻宝场景没有参考价值 if (location.accuracy 80) { return false; } return true; }第二道做一次防抖。定位芯片返回的坐标是会有随机抖动的即使人站在原地连续回调的两次坐标也会有几米偏差。如果每次都拿最新坐标去算距离UI上的数字会跳来跳去。我的方案是保留上一次有效坐标只有当两次坐标的距离超过2米时才更新UI上的位置信息。2米这个阈值我调试时调过几次设大了感觉迟钝设小了数字抖动明显最终定在2米是比较舒服的体感平衡点。4. 方向传感器与设备朝向判定决定你面朝哪里4.1 为什么不用陀螺仪而用方向传感器寻宝场景里需要判断手机朝向是否对着宝藏点这里就轮到方向传感器上场。HarmonyOS的传感器模块kit.SensorKit提供了多种传感器类型其中SensorId.DIRECTION就是方向传感器也常被称为旋转向量传感器或电子罗盘。它返回三个关键数据方位角azimuth、俯仰角pitch、翻滚角roll。对我们最有用的就是方位角它表示设备顶部相对于地球北极的夹角正北是0度顺时针增加正东90度正南180度正西270度范围0到360。可能有读者会问直接用陀螺仪积分算角度行不行理论上行实际上不行。陀螺仪输出的是角速度要得到角度必须积分而积分过程会不断累积漂移误差——早上校准好是0度放口袋里走一圈回来可能漂了15度。方向传感器是系统把加速度计、磁力计、陀螺仪三个数据源融合后的输出直接给我们稳定的绝对方向这才是手机指南针应用背后的原理。4.2 数据监听与角度归一化监听方向传感器比定位监听简单一行就够import { sensor } from kit.SensorKit; sensor.on(sensor.SensorId.DIRECTION, (data) { const azimuth data.azimuth; // azimuth 范围 0~360表示当前的设备朝向 updateHeading(azimuth); }, { interval: 100 });这个{ interval: 100 }是很多人会漏掉的关键参数单位是毫秒表示回调的最小间隔。不设的话传感器可能以几十毫秒的频度疯狂回调UI状态被频繁刷新页面就容易卡顿。我当时遇到的现象是页面掉帧明显加了这个参数之后立刻好转。100毫秒对寻宝场景足够顺滑——你看罗盘UI时指针的转动本身也需要一个流畅但不至于晃瞎眼的刷新率。还有一个小坑方向传感器的方位角在某些手机上偶尔会跳出小于0或大于360的异常值所以拿到数据后我做了归一化处理确保角度值永远落在0到360之间。做法很简单function normalizeAngle(angle: number): number { return (angle % 360 360) % 360; }如果直接把data.azimuth和计算出来的目标方位角做减法就会遇到350度和10度其实只差20度但直接相减得到340度的经典问题。归一化之后再用取绝对值不大于180度的方式求差值才能正确判断朝向是否对准。5. 从距离和方位角到宝藏命中核心逻辑实现5.1 Haversine距离计算距离计算用的是经典的Haversine公式。它是球面三角学里计算大圆距离的标准方法公式不复杂却能保证在经纬度跨几千米的尺度下误差控制在很小的范围内。业务侧完全没有必要用平面直角坐标近似——Haversine的计算成本对现代设备来说可以忽略不计而且逻辑清晰、不容易出边界问题。function calculateDistance( lat1: number, lon1: number, lat2: number, lon2: number ): number { const R 6371000; // 地球平均半径单位米 const toRad (deg: number) (deg * Math.PI) / 180; const dLat toRad(lat2 - lat1); const dLon toRad(lon2 - lon1); const a Math.sin(dLat / 2) * Math.sin(dLat / 2) Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLon / 2) * Math.sin(dLon / 2); return 2 * R * Math.asin(Math.sqrt(a)); }这里有一个我自己在实现时反复验证过的细节点6371000这个地球平均半径值单位是米。如果你用的是千米最后算出来的结果会差三个数量级距离显示成几千千米就非常让人头大。另外公式里的三角运算都是弧度制经纬度是角度制必须先做toRad转换我第一次写就把这个转换漏了导致距离全是错的。后来加了一段单测验证用两个相距已知的坐标点反复计算核对输出是否在误差范围内。关于坐标系也顺带提一句这里拿到的经纬度是WGS-84标准坐标系直接用于数学计算完全没问题。但如果后续要把宝藏点显示在自带地图组件上国内地图通常要求GCJ-02坐标系需要做偏移转换。我这个Demo里没有接地图而是纯文字和罗盘引导所以避开这个坑。读者如果要接入地图组件记得单独处理坐标系转换的环节。5.2 目标方位角与设备朝向的匹配判定知道了距离还要知道该朝哪个方向走这就得算从当前位置指向宝藏点的方位角。这个公式也是导航类应用的经典算法function calculateBearing( lat1: number, lon1: number, lat2: number, lon2: number ): number { const toRad (deg: number) (deg * Math.PI) / 180; const toDeg (rad: number) (rad * 180) / Math.PI; const dLon toRad(lon2 - lon1); const y Math.sin(dLon) * Math.cos(toRad(lat2)); const x Math.cos(toRad(lat1)) * Math.sin(toRad(lat2)) - Math.sin(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.cos(dLon); const bearing toDeg(Math.atan2(y, x)); return normalizeAngle(bearing); }normalizeAngle就是前面4.2节里那个取模归一化的函数这里再复用一次保证返回值在0到360之间。接下来就是整个项目最核心的判定逻辑当距离小于命中半径我设为15米且设备朝向与目标方位角的差值小于30度时判定为找到宝藏。但直接这么做会有问题——定位和传感器都有噪声可能出现某一帧刚好凑对了就触发成功体验很突兀。我的做法是加连续命中判定连续5次回调约0.5秒都同时满足距离和朝向条件才真正进入成功状态。这个设计灵感其实来自按键防抖在物理世界中意义更明显它能滤掉绝大多数偶发抖动const MATCH_DISTANCE 15; // 命中距离单位米 const MATCH_ANGLE 30; // 命中朝向偏差单位度 const MATCH_COUNT 5; // 连续命中次数 let matchStreak 0; function checkTreasureHit(distance: number, targetBearing: number, heading: number): boolean { if (distance MATCH_DISTANCE) { matchStreak 0; return false; } let diff Math.abs(targetBearing - heading); diff diff 180 ? 360 - diff : diff; // 处理角度环绕 if (diff MATCH_ANGLE) { matchStreak; } else { matchStreak 0; } return matchStreak MATCH_COUNT; }角度差值计算里diff 180 ? 360 - diff : diff这一段就是处理350度和10度这类环绕场景的关键。如果不处理朝向差会算成340度命中判定永远不可能通过。这算是我在这个项目里觉得最值得记录的一个小算法点。5.3 宝藏点配置与UI反馈设计宝藏点的坐标我放在一个单独配置对象里方便替换成任意测试位置。演示代码里用一个示意坐标就行const TREASURE_POINT { latitude: 30.123456, longitude: 120.654321 };真正调试的时候还是要换成你自己所在位置附近的坐标——我在开发初期直接用了一个离我很远的坐标结果发现不管怎么走都离目标几百公里还以为是定位坏了。最好先在当前地点随便选一个50米外的坐标放进去这样能在小范围里快速验证整套流程。UI方面我按状态机做了三档反馈距离数字大字展示实时变化一个圆盘指针指示目标方位相对设备朝向的角度差距离越近、角度差越小指针颜色就越偏暖形成一种越接近越热的直觉反馈。这套设计让用户不读数字也能凭感知判断方向是否接近是方向寻宝体验感的重要来源。指针指示更新时注意用animateTo做一点平滑动画直接硬切指针会造成视觉上的生硬感这一点在交互细节上体验差距很明显。6. 真机调试中的精度问题与排查经验6.1 模拟器与真机的差异方向传感器不是能读就行第一版代码在模拟器上跑的时候定位数据能拿到但方向传感器返回的数据一直在固定值附近跳动而且无论我怎么旋转模拟器手机数值都不发生变化。排查到最后才确认这是模拟器的硬件抽象限制——方向传感器依赖真实的磁力计和陀螺仪数据模拟器没有这些真实输入源返回的数据不具备实际参考价值。所以这个项目必须真机调试。有些读者可能会问那没有真机怎么办我的建议是先把业务逻辑在模拟器里跑通距离计算、状态切换、UI反馈这些不依赖传感器数据的部分都能测方向判定部分临时用一个固定朝向值代替传感器输出来模拟构造几个预置场景验证逻辑分支最后上了真机再做完整联调。这个可控输入源替换的调试思路在做任何依赖真实硬件的功能时都非常好用。6.2 定位漂移与命中误判现场排查的完整链路真机联调阶段遇到的最恼火的问题是明明已经站在宝藏点上了距离数字却在8米和20米之间来回跳导致命中状态一会触发一会消失。一开始我怀疑是MATCH_COUNT连续5次这个条件太苛刻改成3次之后仍然复发。后来我一步步定位把问题拆成了两层第一层是定位本身在漂移。GPS在静止状态下也有几米的随机抖动导航芯片会融合加速度计和陀螺仪做轨迹推测但纯GPS坐标在静止时依然可能画出一个小圆。我采用的策略是前面3.2节提到的位置防抖——两次坐标距离小于2米时不更新显示位置。这个策略在走动时几乎无感但能显著减少静止状态下的UI波动。第二层是命中条件里的距离阈值与防抖逻辑产生了耦合。我最初在checkTreasureHit里使用最新一次回调的坐标来计算距离但最新坐标可能是一个漂移出去的坏点。修正方案是距离计算统一使用防抖后保留的有效位置而不是每次回调的原始坐标这样距离数值本身就是稳定的命中判定自然不再频繁失效。排查过程中还有一条重要经验给关键逻辑都加上日志。我在定位回调、传感器回调、命中判定三个位置各打了一条带标签的日志用打印的方式观察原始数据和判定中间值。没有这些日志面对命中状态反复横跳的现象就只能靠猜。日志格式要带上关键数值比如[hit] distance12.3 diff28 count3下一次看日志就能立刻还原现场上下文。6.3 资源释放与生命周期最后一个特别好用但也特别容易被忽略的点监听和传感器回调用完之后一定要关掉。geoLocationManager.on能注册监听对应的geoLocationManager.off用来解除sensor.on对应的解除方法是sensor.off。我在页面onPageHide和命中成功分支里都做了清理防止页面退到后台后还在持续接收定位和传感器事件既浪费功耗又可能导致状态错乱。function stopFinding() { geoLocationManager.off(locationChange, onLocationChange); sensor.off(sensor.SensorId.DIRECTION, onDirectionChange); matchStreak 0; }这里有个细节off时最好把之前传入的回调函数引用也带上传参而不是只传事件名。只传事件名在某些版本上确实也能解绑全部回调但只要你想针对某一个回调精确解绑就必须带引用。我统一养成了保存回调函数引用的习惯这样代码更可控也方便在页面销毁时按顺序清理所有注册资源。资源释放这部分测试时的直观感受是没做清理的版本连续进入退出页面五六次后日志里能看到回调次数叠加——每次进入都会重复注册导致同样是走动一米UI却更新了两次甚至出现两个坐标交替闪烁的诡异现象。做完on/off成对清理之后这个现象彻底消失。所以我的建议是把on、off看成必须配对出现的一对操作写on的时候就顺手把对应off的位置确定好。我自己做完这个项目后最大的体会是方向寻宝这类Demo真正的难点不在某个API怎么调而在如何让两个独立的数据源在一个场景里稳定地协作。定位有噪声传感器有噪声命中判定要防抖状态切换要平滑——这些工程细节才是比API本身更值钱的积累。后续如果想继续扩展可以在这个基础上接入地图组件做可视化寻宝或者把宝藏点改成服务端下发的打卡任务玩法上还能加多人竞技模式。整个项目代码量不大但覆盖的知识点足够让一个刚接触位置与传感器的开发者完成一次很扎实的进阶练习。
阅读完成 · 觉得有帮助？
