企业官网建设流程全解析

做HarmonyOS应用开发，定位服务和锁屏实况窗这两个能力基本绕不开。很多LBS类应用的第一道门槛就是位置获取，而实况窗则是鸿蒙生态里非常有代表性的交互形态。把两者放在一起，能做出很多实用的小功能，比如打车时在锁屏上实时盯着司机距离，点外卖后在锁屏看骑手到哪了，或者做一个骑行回家的路线提醒卡片。这篇内容我从实际开发的角度，把位置服务的权限配置、定位参数选择、实况窗的发布和更新流程，以及两者联动时的状态切换思路都梳理一遍，还会附上我在真机调试过程中踩过的坑。

1. 定位和锁屏实况窗的结合点在哪里

1.1 实况窗和普通通知的本质区别

很多开发者第一次接触实况窗时，会把它理解为"高级一点的通知"。这个理解不算错，但会限制你的设计思路。普通通知是一次性的，发完就完事了，用户在锁屏上看到的是静态摘要，想获取更多信息还得点击通知、解锁手机、跳进应用。实况窗的核心价值在于"常驻"和"实时"：它可以在锁屏界面上保留一个卡片形态，内容可以持续更新，用户不用做任何操作就能看到最新状态。

这种体验差异在具体场景里非常明显。外卖场景里，普通通知只能在骑手接单、取餐、送达时各推一条消息，中间那段漫长的配送过程完全靠用户自己反复打开App猜进度。实况窗则是把配送进度、剩余距离、预计到达时间直接钉在锁屏上，用户抬起手腕或点亮屏幕就能看到。更关键的是，实况窗在系统层面有优先级保障，不会被后续的其他通知挤出通知栏，这个特性是普通通知完全做不到的。

从开发角度看，两者的底层实现其实共用一套通知服务框架，但实况窗在通知接口上有独立的模板和生命周期管理方式。它支持在卡片上放按钮、进度条、文本，甚至可以让用户直接点击卡片拉起应用。我习惯把它比作"一块可以远程遥控的小号广告牌"：内容是活的，交互是直达的，展示位置是系统给你保住的。

1.2 这套组合最适合做什么场景

定位加实况窗，本质上是在解决"用户不想频繁打开App，但又需要持续知道位置状态"的问题。我实际做下来感觉这类场景有几个共同特点：状态变化频率适中、数据可以被量化展示、结果有明确的完成任务节点。

出行类是最典型的。骑行或步行导航时，实时显示距离目的地还有多远、进度条走到哪儿了；车队管理场景里，调度员在锁屏上看司机位置趋势；宠物定位器、老人防走丢手环这类设备配套App，也能用实况窗把位置更新推送到锁屏。还有自营配送、同城闪送等业务，锁屏上的距离数字每刷新一次，用户的焦虑感就降低一分。

我这次做的Demo就设定为一个"骑行回家"的场景：应用获取当前位置，实时计算与家庭地址的距离，通过锁屏实况窗展示剩余距离、进度百分比和"即将到达"的状态切换。这个Demo麻雀虽小，但位置服务、实况窗生命周期、数据联动这些关键点全部覆盖到了，你要做复杂场景时只要在这个骨架上往里面填业务逻辑就行。

2. 位置服务开发：权限、参数和连续定位

2.1 先把权限配置写对

HarmonyOS的位置权限有两级，一个是ohos.permission.LOCATION（精确位置），一个是ohos.permission.APPROXIMATELY_LOCATION（模糊位置）。从HarmonyOS NEXT开始，系统在权限管理上更强调"最小化授权"，如果你只申请了精确位置权限而没申请模糊位置，某些版本下反而会被系统判定为不合理申请弹窗拒绝。稳妥的做法是两个一起申请。

模块配置文件里要这样声明权限：

{ "module": { "requestPermissions": [ { "name": "ohos.permission.LOCATION", "reason": "$string:location_reason", "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" } }, { "name": "ohos.permission.APPROXIMATELY_LOCATION", "reason": "$string:location_reason", "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" } } ] } }

注意reason字段是给用户在权限弹窗里看的说明文字，不要写"为了更好体验"这种模糊话术，系统审核和用户授权率都会受影响。比较务实的写法是"用于在骑行回家时展示实时距离和到达提醒"，越具体越容易获得用户信任。

配置完模块文件，还需要在代码里动态申请权限。有两点容易被新手忽略：一是动态申请必须在onWindowStageCreate之后执行，太早发起会因为窗口尚未就绪而失败；二是用户在系统设置里手动关闭权限后，应用不会收到主动回调，需要在重新回到前台时用abilityAccessCtrl.checkAccessToken检查一遍授权状态。

import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit'; async function checkAndRequestLocationPermission(): Promise<boolean> { const atManager = abilityAccessCtrl.createAtManager(); const grantStatus = await atManager.checkAccessToken( { tokenId: 0, permissionName: 'ohos.permission.LOCATION' } ); if (grantStatus === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) { return true; } const permissions: Array<Permissions> = [ 'ohos.permission.LOCATION', 'ohos.permission.APPROXIMATELY_LOCATION' ]; try { await atManager.requestPermissionsFromUser(permissions); return true; } catch (err) { console.error('Permission request failed: ' + JSON.stringify(err)); return false; } }

2.2 定位参数不是随便填的

HarmonyOS的定位服务通过geoLocationManager提供，调用getCurrentLocation或订阅on('locationChange')之前，都要先构造一个LocationRequest对象。这个对象的参数设置直接决定定位成功率、精度和功耗。

最关键的是priority和scenario两个字段，很多人把它们当成冗余配置，实际它们会在底层影响GPS芯片和网络模块的调度策略。

import { geoLocationManager } from '@kit.LocationKit'; import { BusinessError } from '@kit.BasicServicesKit'; let locationRequest: geoLocationManager.LocationRequest = { priority: geoLocationManager.LocationRequestPriority.FIRST_FIX, scenario: geoLocationManager.LocationRequestScenario.NAVIGATION, maxAccuracy: 50, timeoutMs: 10000, maxScale: 1, }; try { const location = await geoLocationManager.getCurrentLocation(locationRequest); console.info(`Latitude: ${location.latitude}, Longitude: ${location.longitude}`); } catch (err) { const e = err as BusinessError; console.error(`getCurrentLocation failed: code=${e.code}, message=${e.message}`); }

FIRST_FIX的含义是"尽快拿到首次定位"，适合骑行、步行等需要快速展示起始位置的场景。NAVIGATION场景会让系统优先启用GPS、提高定位频率，代价是功耗更高。如果你的场景只是每隔几分钟上报一次位置，用DAILY_LIFE_SERVICE配LOW_POWER会更合适。

maxAccuracy是期望精度，单位是米。这里要特别提醒：它表达的是一个期望值，不是保证值。系统会尽量满足，但如果当前环境信号差，返回的定位点精度劣于50米也是正常的，代码里要做兜底判断。timeoutMs建议设置10秒左右，太短容易在室内定位失败，太长又会让用户等得烦躁。

2.3 单次定位还是连续定位

不同的业务要选不同的定位模式。Navigation场景需要持续关注位置变化，应该订阅locationChange；而"打卡""报平安"这类只需要一个点的场景，用getCurrentLocation就够了。

我这次做骑行回家，显然需要连续定位。订阅方式很简单：

import { geoLocationManager } from '@kit.LocationKit'; let subscriptionId = -1; function startLocationTracking(callback: (lat: number, lng: number) => void) { let request: geoLocationManager.LocationRequest = { priority: geoLocationManager.LocationRequestPriority.FIRST_FIX, scenario: geoLocationManager.LocationRequestScenario.NAVIGATION, maxAccuracy: 50, timeoutMs: 10000, maxScale: 1, }; subscriptionId = geoLocationManager.on('locationChange', request, (location) => { callback(location.latitude, location.longitude); }); } function stopLocationTracking() { if (subscriptionId > 0) { geoLocationManager.off('locationChange', subscriptionId); subscriptionId = -1; } }

订阅后有一个容易被忽视的点：off要传入订阅时返回的subscriptionId，否则解绑可能不生效，导致定位一直在后台跑、耗电直线上升。这个坑我在真机上踩过一次，应用都退出了，日志里还能看到位置回调在打印。后来查了社区资料才发现是off参数没带对。

此外，连续定位的回调频率通常比业务需要的频率高。实况窗的卡片刷新也不宜过于频繁，我建议在回调层做一次节流，比如距离变化超过50米或者时间间隔超过3秒才触发UI更新。这样既能保证体验，又避免无谓的性能消耗。

3. 锁屏沉浸实况窗开发要点

3.1 实况窗的工作机制概述

实况窗在HarmonyOS里走的是NotificationKit这套框架，但它和普通通知是不同类型。发布时指定NotificationContentType为NOTIFICATION_CONTENT_LIVE_VIEW，系统就会把它当作实况窗处理。实况窗内容由LiveViewContent描述，支持标题、文本、图标、进度条和按钮这些元素。

"沉浸"体现在锁屏场景下系统会用专门的模板来渲染实况窗，卡片层级高于普通通知，并且可以展示进度条等动态元素。你可以把它理解成系统给应用划出了一块"锁屏画布"，应用只需要上传内容和更新指令，绘制工作由系统统一完成。

这套机制的好处是不同应用的实况窗在视觉和交互上有统一的规范，不会出现某个应用霸屏锁屏的情况。系统层面做了严格的限制：锁屏上同时展示的实况窗数量有限，超过限制后新的实况窗要排队，所以不要指望靠多发几条实况窗来刷存在感，把一条做好做精才是正道。

3.2 用代码发布一张实况窗卡片

发布实况窗的核心是构造NotificationRequest，把content.notificationContentType设为NOTIFICATION_CONTENT_LIVE_VIEW，再把liveView属性赋上内容对象。

import { notificationManager } from '@kit.NotificationKit'; import { wantAgent } from '@kit.AbilityKit'; async function publishLiveView() { // 先构造一个WantAgent，用于用户点击卡片时拉起应用 let wantAgentInfo: wantAgent.WantAgentInfo = { wants: [ { bundleName: 'com.example.locationlive', abilityName: 'EntryAbility' } ], actionType: wantAgent.OperationType.START_ABILITY, requestCode: 0 }; let wantAgentObj = await wantAgent.getWantAgent(wantAgentInfo); let liveViewContent: notificationManager.LiveViewContent = { title: '回家路线', text: '正在定位当前进度', icon: $r('app.media.app_icon'), progress: { value: 0, maxValue: 100 }, button: { names: ['查看详情'], wantAgent: wantAgentObj } }; let notificationRequest: notificationManager.NotificationRequest = { id: 1001, content: { notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_LIVE_VIEW, liveView: liveViewContent } }; await notificationManager.publish(notificationRequest); }

id字段在这个流程里很重要。后续更新、删除实况窗都要靠它定位到具体的那条通知，所以建议用一个专门的常量来管理，别随便写个魔法数字。

代码里的icon我直接用了应用图标，实际业务中可以换成语义更明确的图片，比如一辆自行车或者一个家的图标。button是可选的，如果你希望用户点击卡片上的按钮跳到特定页面，就用WantAgent去拉起对应Ability。不传按钮，整个卡片区域也可以响应点击。

3.3 更新和结束：实况窗的生命周期管理

实况窗的"活"主要体现在它支持原地更新。方法很简单，把publish换成update，传入同样的id，内容替换成新状态即可。

async function updateLiveView(newText: string, progressValue: number) { let updatedContent: notificationManager.LiveViewContent = { title: '回家路线', text: newText, icon: $r('app.media.app_icon'), progress: { value: progressValue, maxValue: 100 }, button: { names: ['查看详情'], wantAgent: wantAgentObj } }; let updateRequest: notificationManager.NotificationRequest = { id: 1001, content: { notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_LIVE_VIEW, liveView: updatedContent } }; await notificationManager.update(updateRequest); }

更新时有个细节值得注意：LiveViewContent里的title每次都要带上，如果更新时只传了变化的字段，某些版本的系统模板可能会把未传字段重置成默认值，导致卡片上的标题消失。我在模拟器上验证过这个现象，稳妥做法是每次更新都把完整内容对象构造好。

任务结束时，要记得把实况窗从通知中心清掉，避免用户完成行程后在锁屏上还挂着一个"已完成"的卡片。删除同样走notificationManager：

await notificationManager.cancel(1001);

到这里，实况窗的完整生命周期就闭环了：发布、更新、结束。这三个阶段对应到业务上就是开始行程、行程进行中、行程结束。

4. 定位数据驱动实况窗的联动实现

4.1 从定位回调到界面刷新的数据链路

定位和实况窗两者单独看都不算复杂，真正有意思的是联动部分。我把整条链路设计成这样的单向数据流：

定位回调产生坐标点，坐标点经过距离计算变成"剩余距离"和"进度百分比"，这两个数值再包装成LiveViewContent推送出去。

这个链路里有个设计原则：实况窗的更新函数应该是纯展示逻辑，不要在里面去获取定位、不要做耗时计算。原因很简单，实况窗更新走的是系统通知通道，如果每次更新前还要等定位回调，消息就变成异步串联了，卡片上的数字会滞后。正确做法是先把距离算好，然后立刻更新卡片。

代码结构上，我用一个updateLoop统一处理：

function onLocationUpdate(lat: number, lng: number) { const distance = calculateDistance(lat, lng, HOME_LAT, HOME_LNG); const progress = Math.min(100, Math.round((1 - distance / TOTAL_DISTANCE) * 100)); const displayText = formatDistanceText(distance); if (distance < ARRIVE_THRESHOLD) { updateLiveView('你已经到达目的地附近', 100); stopLocationTracking(); return; } updateLiveView(displayText, progress); }

这里把所有的业务判断都放在定位回调里做，实况窗更新就变成了一个无脑执行的动作。调试时思路特别清晰：看到定位日志就猜到会更新什么UI。

4.2 距离计算与到达判断

"距离"这个值看似简单，实际实现时有个关键选择：是调用系统提供的计算接口，还是自己写球面距离公式。

我选择了自己写Haversine公式。原因是传统定位SDK里经常封装好的距离计算函数在HarmonyOS的geoLocationManager里没有直接暴露，与其到处找工具类，不如自己写一个，顺便还能加深对球面几何的理解。

function calculateDistance(lat1: number, lng1: number, lat2: number, lng2: number): number { const R = 6371000; // 地球平均半径，单位米 const toRad = (deg: number) => deg * Math.PI / 180; const dLat = toRad(lat2 - lat1); const dLng = toRad(lng2 - lng1); const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) + Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLng / 2) * Math.sin(dLng / 2); const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a)); return R * c; }

对于骑行回家这种几百米到几公里的尺度，Haversine公式的误差完全可以接受。如果你做的场景是跨城市的长距离运输，或者对精度要求达到米级以下，建议换成更适合的算法，但实际业务中很少遇到这种需求。

到达判断的阈值我设为100米。这个值不是拍脑袋定的，参考了系统通知和地图导航场景的常见值：太小的阈值如20米，GPS漂移很容易造成误判；太大的阈值如500米，用户还没真正到达就触发提醒，体验反而奇怪。100米配合上"是否处于移动状态"的判断，基本能做到准确。

const ARRIVE_THRESHOLD = 100; // 米 const DISTANCE_CHANGE_THRESHOLD = 50; // 米，触发UI更新的最小距离变化 function formatDistanceText(distance: number): string { if (distance >= 1000) { return `距目的地还有 ${(distance / 1000).toFixed(1)} 公里`; } return `距目的地还有 ${Math.round(distance)} 米`; }

4.3 状态切换与防抖

实况窗最忌讳的就是"内容反复横跳"。定位点天然有噪声，同一个地方停着不动，连续两次定位的坐标也可能相差30到50米。如果不做处理，卡片上的距离数字会像呼吸灯一样一高一低地跳。

我做了两个层面的防抖。

第一层是距离变化阈值。连续定位回调到达时，先计算一下新距离和当前展示距离的差值，小于50米就跳过UI更新。这样屏幕上显示的数字是阶梯式下降的，符合用户预期。

第二层是时间间隔限制。即使距离变化超过阈值，也要求距离上次UI更新至少间隔2秒。这个限制对功耗特别有用，因为实况窗更新本身会触发系统通知的重新渲染，太频繁会让蓝牙和显示模块都处于高负荷状态。

状态切换我用一个简单的有限状态机来管理：

enum TripState { IDLE, MOVING, NEAR_ARRIVE, ARRIVED }

MOVING状态下，距离大于1000米时显示公里数，小于1000米时显示米数；进入NEAR_ARRIVE时，卡片文案切换为"即将到达"，进度条跳到90以上；到达后直接走cancel逻辑清理实况窗。

状态机的好处是整个流程的可预测性很强，不会出现"已经提示到达了，又因为一次定位抖动变回配送中"的尴尬情况。切到终态后，后续即使还有定位回调进来，也会被状态机拦住不再更新UI。

5. 实战中的常见问题与处理经验

5.1 位置权限明明申请了，却一直拿不到定位

这个现象最常见的原因，是应用在onWindowStageCreate之前发起了权限请求。在HarmonyOS里，用户授权弹窗必须依赖窗口才能展示，太早调用requestPermissionsFromUser会直接走异常分支。你检查一下代码就会发现catch里确实捕获到了错误，但很多时候日志不够详细，容易被忽略。

另一个原因是权限声明和实际使用场景不符。如果只在module.json5里声明了LOCATION，APPROXIMATELY_LOCATION没加，部分版本在requestPermissionsFromUser时会因为权限组不完整而拒绝。把两个权限都配上，同时在真机上检查系统设置里的"位置信息"开关是否打开，基本能解决90%的问题。

注意：模拟器上定位行为与真机差异极大，权限弹窗和GPS信号在模拟器里都是模拟的。我建议定位相关功能一律在真机上调试。

5.2 实况窗在锁屏上不出现

代码没有任何报错，publish也返回了成功，但锁屏上就是看不到实况窗卡片。这个问题我排查了很久，最后定位到是通知渠道的原因。NotificationRequest里如果没有显式指定渠道，系统会使用默认渠道，而默认渠道的锁屏展示属性可能是关闭的。

解决办法是在发布前创建或获取一个锁屏可见的通知渠道，并确认渠道的allowBanner和锁屏权限都被正确设置。另外还要检查用户在系统设置里是不是对当前应用关闭了"锁屏通知"，这个开关在HarmonyOS的设置路径比较深，普通用户很容易误触。

还有一种情况是"实况窗确实发布了，但被其他应用的实况窗挤掉了"。系统对同时展示的实况窗数量有限制，测试时建议先把不相关的实况窗清掉再观察。

5.3 定位点抖动导致距离数字乱跳

如前文所述，这是GPS噪声的必然结果，不是代码bug，但处理不好体验会很差。我的方案是距离变化阈值加时间节流双重过滤。如果做了这两层处理还跳，那就要看定位请求参数了——maxAccuracy设得过大、scenario选了低功耗场景，都会放大抖动幅度。

调试这类问题时有个实用技巧：把每次定位回调的经纬度和计算出的距离打印到日志里，画一条距离变化曲线。看到原始数据后，你就能分清抖动是GPS信号问题还是代码逻辑问题。实测室外开阔地带的定位误差大约在5到15米，室内或高架桥下误差可能超过100米，UI层面的防抖阈值建议按这个量级设定。

5.4 实况窗更新太频繁，耗电量明显上涨

实况窗每次更新，系统都要重新渲染锁屏卡片，这本身就比普通通知的展示更耗电。加上连续定位在后台运行，两个因素叠加，耗电翻倍都不奇怪。

优化思路有两个方向。一是定位侧：降低定位频率、选择更省电的scenario，当任务结束或应用退到后台超过一定时间后主动调用off('locationChange')。二是实况窗侧：更新前做距离阈值判断，100米或500米才更新一次，而不是每次定位回调都触发。

我实际测试下来，把更新频率从无限刷新降到2秒一次、距离变化50米才刷新后，整机功耗下降了大概三分之一。如果你的业务允许，进一步放宽阈值也没有问题，实况窗展示的本质是"趋势"和"关键节点"，不是秒级刷新的仪表盘。

最后分享一点我自己的体会：这套联动方案跑顺畅之后，我发现最有价值的不只是最终效果，而是过程中培养的"状态管理思维"。定位数据和UI展示之间不是简单的一对一关系，中间隔着精度误差、功耗约束和用户预期，只有把状态机、防抖、生命周期这些细节都考虑进去，做出来的功能才扛得住真机考验。后来我又把同样的思路扩展到了电池电量提醒和音乐播放控制场景，核心框架基本不用改，改改数据源和卡片文案就能复用。