定位权限不只是“开“与“关“:精准位置和模糊位置的组合申请与处理【鸿蒙心迹】

你是不是也在想——“鸿蒙这么火,我能不能学会?”
答案是:当然可以!
这个专栏专为零基础小白设计,不需要编程基础,也不需要懂原理、背术语。我们会用最通俗易懂的语言、最贴近生活的案例,手把手带你从安装开发工具开始,一步步学会开发自己的鸿蒙应用。
不管你是学生、上班族、打算转行,还是单纯对技术感兴趣,只要你愿意花一点时间,就能在这里搞懂鸿蒙开发,并做出属于自己的App!
📌 关注本专栏《零基础学鸿蒙开发》,一起变强!
每一节内容我都会持续更新,配图+代码+解释全都有,欢迎点个关注,不走丢,我是小白酷爱学习,我们一起上路 🚀
前言
大多数开发者对定位权限的第一印象是:用户要么允许,要么拒绝。但实际上,HarmonyOS 在前台定位场景下把权限拆成了两个:ohos.permission.LOCATION(精准位置)和 ohos.permission.APPROXIMATELY_LOCATION(模糊位置)。这两个权限不是非此即彼的关系,它们可以单独授予,也可以组合授予,应用拿到的结果因此有四种情况,而不是两种。
如果代码只判断"有没有权限",就很容易在用户只授予了模糊位置时拿不到预期精度的坐标,甚至直接报错,问题出在哪里却不明显。这篇文章就专门把这件事说清楚。
一、这两个权限到底有什么区别
在 HarmonyOS 中,精准位置和模糊位置分别对应两个独立的 user_grant 权限:
| 权限名 | 说明 | 精度范围 |
|---|---|---|
ohos.permission.APPROXIMATELY_LOCATION | 模糊位置,API 9 起支持 | 误差约 5 千米 |
ohos.permission.LOCATION | 精准位置,API 9 起支持,必须同时持有 APPROXIMATELY_LOCATION | GPS/网络精准定位 |
这里有一条容易被忽视的规则:申请 ohos.permission.LOCATION 时,必须同时申请 ohos.permission.APPROXIMATELY_LOCATION,否则精准位置权限无法正常授权。 这不是建议,是系统层面的强制依赖关系。
用户在系统弹框中看到的选项通常是:
- 仅允许模糊位置
- 允许精准位置(此时模糊位置也同时授权)
- 拒绝
所以从应用侧来看,前台定位的授权结果有以下几种组合:
APPROXIMATELY_LOCATION | LOCATION | 实际能获取到的位置精度 |
|---|---|---|
| GRANTED | GRANTED | 精准位置 |
| GRANTED | DENIED | 仅模糊位置 |
| DENIED | DENIED | 无法获取位置 |
第二种情况——有模糊无精准——才是最容易被忽略的。此时 geoLocationManager 的部分接口仍然可以调用,但返回的坐标精度很低,如果业务逻辑依赖精确坐标(如导航、LBS 签到),会静默地产生错误结果。
二、官方权限声明要求
在 module.json5 中,两个权限都需要声明。如果只写 LOCATION、漏掉 APPROXIMATELY_LOCATION,运行时权限申请会直接失败。
// module.json5 片段
{
"module": {
"requestPermissions": [
{
"name": "ohos.permission.APPROXIMATELY_LOCATION",
"usedScene": {
"abilities": ["EntryAbility"],
"when": "inuse"
}
},
{
"name": "ohos.permission.LOCATION",
"usedScene": {
"abilities": ["EntryAbility"],
"when": "inuse"
}
}
]
}
}
几个配置细节:
when填"inuse"表示仅前台使用,本文只讨论这个场景。后台定位需要额外申请ohos.permission.LOCATION_IN_BACKGROUND,配置方式不同,不在本文范围内。usedScene.abilities填写实际调用定位的 Ability 名称,不要写通配符。- 两条权限都必须声明,缺一不可。
三、搭一个最小实践场景
目标:应用启动后,判断当前定位权限状态,分三种情况处理:
- 已有精准权限 → 直接获取精准坐标;
- 仅有模糊权限 → 告知用户精度不足,给出升级引导;
- 两者都没有 → 发起权限申请弹窗。
需要用到:
@kit.AbilityKit中的abilityAccessCtrl,用于查权限状态;@ohos.abilityAccessCtrl的GrantStatus枚举;@kit.LocationKit中的geoLocationManager,用于获取位置;- UIAbility 的
onWindowStageCreate生命周期作为入口。
四、核心代码实现
4.1 权限状态检查
这段代码的目标是在调用定位之前,先判断精准权限和模糊权限各自处于什么状态,不要把两个权限混在一起只判断一次。
// PermissionChecker.ets
import { abilityAccessCtrl, bundleManager, Permissions } from '@kit.AbilityKit';
export enum LocationPermLevel {
PRECISE, // 精准位置
APPROXIMATE, // 仅模糊位置
NONE // 未授权
}
export async function checkLocationPermLevel(): Promise<LocationPermLevel> {
const atManager = abilityAccessCtrl.createAtManager();
let tokenId: number = 0;
try {
const bundleInfo = await bundleManager.getBundleInfoForSelf(
bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION
);
tokenId = bundleInfo.appInfo.accessTokenId;
} catch (err) {
return LocationPermLevel.NONE;
}
const preciseStatus = await atManager.checkAccessToken(
tokenId,
'ohos.permission.LOCATION' as Permissions
);
const approxStatus = await atManager.checkAccessToken(
tokenId,
'ohos.permission.APPROXIMATELY_LOCATION' as Permissions
);
if (preciseStatus === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
return LocationPermLevel.PRECISE;
} else if (approxStatus === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
return LocationPermLevel.APPROXIMATE;
}
return LocationPermLevel.NONE;
}
真正需要关注的地方是:checkAccessToken 需要应用自身的 accessTokenId,通过 bundleManager.getBundleInfoForSelf 获取,不需要任何系统权限,普通应用可以直接调用。
4.2 权限申请
申请时必须把两个权限一起传入 requestPermissionsFromUser,由系统统一弹框给用户选择。
// 在 UIAbility 中调用
import { abilityAccessCtrl, common, Permissions } from '@kit.AbilityKit';
async function requestLocationPermissions(context: common.UIAbilityContext): Promise<void> {
const atManager = abilityAccessCtrl.createAtManager();
const permissions: Permissions[] = [
'ohos.permission.APPROXIMATELY_LOCATION',
'ohos.permission.LOCATION'
];
const result = await atManager.requestPermissionsFromUser(context, permissions);
// result.authResults 按 permissions 数组顺序对应
const approxGranted = result.authResults[0] === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;
const preciseGranted = result.authResults[1] === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;
if (preciseGranted) {
// 用户选择了精准位置
console.info('已获取精准位置权限');
} else if (approxGranted) {
// 用户选择了仅模糊位置
console.info('仅获取模糊位置权限,坐标精度约 5km');
} else {
// 用户拒绝
console.info('位置权限被拒绝');
}
}
result.authResults 的顺序和传入 permissions 数组的顺序一一对应,所以传入顺序要固定,不要在不同地方用不同顺序传入同一批权限,否则下标判断会乱。
4.3 在页面中组合使用
// LocationPage.ets
import { checkLocationPermLevel, LocationPermLevel } from './PermissionChecker';
import { geoLocationManager } from '@kit.LocationKit';
import { common } from '@kit.AbilityKit';
import { promptAction } from '@kit.ArkUI';
@Entry
@Component
struct LocationPage {
@State locationText: string = '点击按钮获取位置';
@State permLevel: LocationPermLevel = LocationPermLevel.NONE;
private context = getContext(this) as common.UIAbilityContext;
async aboutToAppear(): Promise<void> {
this.permLevel = await checkLocationPermLevel();
}
async handleGetLocation(): Promise<void> {
if (this.permLevel === LocationPermLevel.NONE) {
// 跳转系统设置或重新申请
promptAction.showToast({ message: '请先授予位置权限' });
return;
}
const request: geoLocationManager.CurrentLocationRequest = {
// 精准权限时优先使用高精度优先策略
priority: this.permLevel === LocationPermLevel.PRECISE
? geoLocationManager.LocationRequestPriority.ACCURACY
: geoLocationManager.LocationRequestPriority.LOW_POWER,
scenario: geoLocationManager.LocationRequestScenario.UNSET,
timeoutMs: 10000
};
try {
const location = await geoLocationManager.getCurrentLocation(request);
this.locationText =
`纬度:${location.latitude.toFixed(6)}\n` +
`经度:${location.longitude.toFixed(6)}\n` +
`精度:${location.accuracy} 米\n` +
`权限级别:${this.permLevel === LocationPermLevel.PRECISE ? '精准' : '模糊'}`;
} catch (err) {
this.locationText = `获取失败:${JSON.stringify(err)}`;
}
}
build() {
Column({ space: 16 }) {
if (this.permLevel === LocationPermLevel.APPROXIMATE) {
Text('当前仅授予模糊位置权限,坐标精度约 5 千米。如需精准定位,请前往系统设置修改权限。')
.fontSize(14)
.fontColor('#FF6B00')
.padding(12)
}
Text(this.locationText)
.fontSize(16)
.padding(16)
Button('获取当前位置')
.onClick(() => {
this.handleGetLocation();
})
}
.width('100%')
.padding(24)
}
}
这里选择把 permLevel 存到组件状态里,而不是每次点击都重新检查,原因是权限状态变化只发生在用户主动操作系统设置后。如果需要感知用户从设置回来后的权限变化,可以在 onForeground 生命周期中重新调用 checkLocationPermLevel() 刷新状态。
五、几个关键点拆开看
5.1 LOCATION 依赖 APPROXIMATELY_LOCATION,这是系统强制的
官方文档明确说明,申请 ohos.permission.LOCATION 时必须同时申请 ohos.permission.APPROXIMATELY_LOCATION。只申请前者会导致权限申请弹框无法正常弹出,或者权限始终处于 DENIED 状态。很多初次接触 HarmonyOS 定位权限的开发者会单独申请 LOCATION,这是最常见的失误。
5.2 requestPermissionsFromUser 的弹框由系统控制,开发者无法自定义
系统会根据传入的权限列表以及用户历史授权状态,决定弹框的展示形式。如果用户此前已经永久拒绝了位置权限,再次调用 requestPermissionsFromUser 时系统不会再次弹框,authResults 会直接返回 DENIED。这种情况下,引导用户去系统设置页手动开启是唯一的路径。
可以通过 context.startAbility 跳转到系统设置的应用权限页,具体 want 参数可参考官方的"应用隐私保护指导"相关文档。本文不展开这个分支,但实际项目里需要处理。
5.3 模糊权限下 accuracy 字段的含义
当用户只授予了模糊位置权限时,geoLocationManager.getCurrentLocation 返回的 location.accuracy 并不能简单地用于判断定位是否"足够精准"——该字段在模糊位置模式下的实际语义与精准定位场景不同,不要直接用这个数值做业务判断。判断精度是否满足业务需要,应该在获取位置之前先判断权限级别,而不是获取位置之后再看 accuracy。
5.4 checkAccessToken 只是快照,不是监听
checkAccessToken 返回的是当前时刻的权限状态快照。如果用户在系统设置里动态修改了权限,应用内缓存的状态不会自动更新。建议在每次需要调用定位功能之前(而不只是在页面初始化时),都重新检查一次权限状态。
5.5 CurrentLocationRequest 的 priority 和 scenario 组合
LocationRequestPriority 和 LocationRequestScenario 是两个独立字段,官方文档说明两者同时设置时以 scenario 为准。如果只设置 priority 而把 scenario 设为 UNSET,则以 priority 生效。上面代码选择的就是后者,行为比较可预测。
六、容易踩坑的地方
module.json5 漏写 APPROXIMATELY_LOCATION
这是最高频的问题。LOCATION 单独声明时,运行时权限申请在某些设备或系统版本上会静默失败,也有可能弹框出来但用户选择精准位置后 authResults 仍返回 DENIED。先检查 module.json5 里两个权限是否都有声明。
requestPermissionsFromUser 必须在 UIAbility 的上下文中调用
如果把权限申请逻辑封装在一个普通的工具类里,要确保传入的 context 是 UIAbilityContext,而不是 ApplicationContext 或其他上下文类型。用错 context 类型会导致弹框无法弹出。
忘记处理"仅模糊位置"这个中间态
代码只写了"有权限"和"无权限"两个分支,而漏掉了"仅模糊权限"这个情况,是最容易产生静默错误的地方。用户感觉授权了,应用也没有报错,但坐标精度始终在几千米级别。一定要把三种状态都处理到位。
权限弹框不会重复弹出
在 HarmonyOS 中,如果用户选择了"拒绝且不再询问",后续调用 requestPermissionsFromUser 不会再弹框。如果应用没有处理这个情况,用户会看到一个没有任何反应的界面,体验很差。这里需要检查 authResults 并给出跳转设置的引导。
七、实际项目中怎么排查
如果运行时位置功能表现异常,可以按下面顺序逐步排查:
-
先看 module.json5:确认
APPROXIMATELY_LOCATION和LOCATION都已声明,when为"inuse",abilities填写正确。 -
看
checkAccessToken的返回值:把两个权限的状态都打出来,而不只是LOCATION一个。确认是精准授权、仅模糊授权,还是全部拒绝。 -
看
requestPermissionsFromUser的authResults:按数组下标核对每个权限的授权结果,注意顺序要和permissions入参一致。 -
看系统设置里的权限状态:有时候代码看起来没问题,但用户设备上该应用的权限曾经被永久拒绝过。直接去"设置 → 隐私 → 权限管理"里看当前应用的位置权限状态。
-
看
geoLocationManager是否 enabled:调用geoLocationManager.isLocationEnabled()确认设备定位总开关是否开启。权限已经授予但定位总开关关闭时,getCurrentLocation会抛出错误码,需要引导用户开启系统定位。 -
最后看业务逻辑:确认上面都没问题之后,再排查坐标使用逻辑是否混淆了精准/模糊两种精度来源。
开发经验总结
LOCATION和APPROXIMATELY_LOCATION是两个独立的 user_grant 权限,二者需要同时声明并同时申请,缺少APPROXIMATELY_LOCATION时精准定位权限无法正常授予。- 前台定位权限的授权结果有三种有意义的状态:精准、仅模糊、全部拒绝,三种都要在代码里有明确处理,不能只区分"有"和"没有"。
- 权限状态检查是快照而非监听,建议在每次调用定位前重新检查,而不是只在页面加载时检查一次。
- 用户永久拒绝后系统不再弹框,需要在代码里判断这个情况并给出跳转设置的引导,否则用户体验会出问题。
如果你的应用目前只判断了 LOCATION 一个权限,可以查一下在"仅模糊位置"状态下,业务逻辑里所有依赖坐标精度的地方是否都有对应的降级处理——这类问题通常不报错,但坐标偏差在实际设备上会非常明显。
❤️ 如果本文帮到了你…
- 请点个赞,让我知道你还在坚持阅读技术长文!
- 请收藏本文,因为你以后一定还会用上!
- 如果你在学习过程中遇到bug,请留言,我帮你踩坑!
更多推荐



所有评论(0)