HarmonyOS 定位权限治理实战：授权、精度、超时与兜底

定位能力一旦处理不好，用户看到的不是“API 调用失败”，而是路线规划一直转圈、附近服务不准确、拒绝权限后页面空白。定位治理要把授权、精度、超时、兜底和资源回收拆开：授权不通过时能解释，定位超时时能降级，用户只需要大概位置时不要强行申请高精度。

本文解决四个问题：定位权限怎么按场景申请，精确定位和大致定位怎么选，超时后如何给用户可用兜底，监听结束后如何释放资源。

1. 定位能力先按场景拆分

不同页面对定位的要求不同。天气页只需要城市级位置，导航页需要高精度，附近门店页可以先用缓存位置再刷新。把这些场景混成一个 getLocation()，后面很难解释为什么申请高精度权限。

场景	推荐策略	用户提示
附近内容	先缓存，再低精度刷新	用于展示附近推荐
路线规划	高精度，带超时	用于规划起点
城市选择	大致位置或手动选择	可手动切换城市
后台刷新	谨慎使用	说明触发时机和用途

2. Location Kit 资料边界和工程目录

HarmonyOS 提供位置服务能力，应用需要在权限、隐私说明和生命周期上保持一致。工程上建议把权限判断和定位执行拆开。

资料入口	工程落点
Location Kit	位置能力总体边界
申请位置权限	权限声明与动态申请
获取设备位置	当前定位和持续定位

entry/src/main/ets/common/location/
  PermissionGate.ets
  LocationPolicy.ets
  LocationRunner.ets
  FallbackLocator.ets
  LocationReporter.ets

3. PermissionGate 只处理授权结果

权限层不应该发起定位，它只回答当前场景是否允许继续。

export type LocationScene = 'nearby' | 'route_start' | 'city_select'
export type PermissionState = 'GRANTED' | 'DENIED' | 'NEED_REQUEST'

export interface LocationPermissionDecision {
  state: PermissionState
  reason: string
  preciseRequired: boolean
}

export class PermissionGate {
  decide(scene: LocationScene, granted: boolean): LocationPermissionDecision {
    if (granted) {
      return { state: 'GRANTED', reason: '已授权位置能力', preciseRequired: scene === 'route_start' }
    }
    return {
      state: 'NEED_REQUEST',
      reason: scene === 'route_start' ? '路线规划需要获取当前位置作为起点' : '用于提供附近内容',
      preciseRequired: scene === 'route_start'
    }
  }
}

这里把“为什么需要定位”跟场景绑定，后续弹窗文案和隐私说明都能复用。

4. LocationPolicy 选择精度和超时

定位请求要有精度和超时。没有超时控制，弱网或室内环境下页面会一直等待。

export interface LocationRequestPolicy {
  accuracy: 'LOW' | 'HIGH'
  timeoutMs: number
  acceptCacheMs: number
}

export class LocationPolicy {
  build(scene: LocationScene): LocationRequestPolicy {
    if (scene === 'route_start') {
      return { accuracy: 'HIGH', timeoutMs: 8000, acceptCacheMs: 30000 }
    }
    if (scene === 'city_select') {
      return { accuracy: 'LOW', timeoutMs: 4000, acceptCacheMs: 10 * 60 * 1000 }
    }
    return { accuracy: 'LOW', timeoutMs: 5000, acceptCacheMs: 2 * 60 * 1000 }
  }
}

高精度不是默认选项。只有导航、轨迹记录这类场景才值得承担更高耗电和更强权限解释成本。

5. LocationRunner 包装定位结果

定位结果要表达成功、超时、被拒绝和不可用。页面不应该直接处理底层异常。

export interface GeoPoint {
  lat: number
  lng: number
  accuracyMeter: number
  at: number
}

export type LocationResult =
  | { ok: true; point: GeoPoint; source: 'gps' | 'cache' }
  | { ok: false; code: 'DENIED' | 'TIMEOUT' | 'UNAVAILABLE'; message: string }

export class LocationRunner {
  async locate(policy: LocationRequestPolicy): Promise<LocationResult> {
    try {
      const point: GeoPoint = { lat: 31.2304, lng: 121.4737, accuracyMeter: policy.accuracy === 'HIGH' ? 20 : 800, at: Date.now() }
      return { ok: true, point, source: 'gps' }
    } catch (err) {
      return { ok: false, code: 'UNAVAILABLE', message: `${err}` }
    }
  }
}

业务层读取的是稳定结果，不直接依赖底层实现细节。

6. FallbackLocator 处理失败兜底

定位失败时，路线页可以让用户手动选择起点，附近页可以展示缓存位置，城市页可以展示热门城市。

export interface LocationFallbackView {
  title: string
  action: string
  useCache: boolean
}

export class FallbackLocator {
  build(scene: LocationScene, result: LocationResult): LocationFallbackView {
    if (result.ok) {
      return { title: '已获取当前位置', action: '继续', useCache: false }
    }
    if (scene === 'route_start') {
      return { title: '暂时无法定位起点', action: '手动选择起点', useCache: false }
    }
    return { title: '定位不可用，先使用上次位置', action: '切换城市', useCache: true }
  }
}

兜底的目的不是隐藏错误，而是让用户继续完成任务。

7. 页面只消费视图状态

页面应展示“授权、定位中、已定位、失败兜底”四种状态。

export interface LocationViewState {
  banner: string
  loading: boolean
  primaryAction: string
}

export function buildLocationView(result?: LocationResult): LocationViewState {
  if (!result) {
    return { banner: '正在获取位置', loading: true, primaryAction: '等待' }
  }
  if (result.ok) {
    return { banner: `定位精度约 ${result.point.accuracyMeter} 米`, loading: false, primaryAction: '使用当前位置' }
  }
  return { banner: result.message, loading: false, primaryAction: result.code === 'DENIED' ? '去授权' : '手动选择' }
}

用户需要看到下一步动作，而不是一个空白地图。

8. 验收动作

场景	操作	预期结果
首次进入路线页	未授权时打开	展示用途说明并申请权限
拒绝权限	点击拒绝	提供手动选择起点
定位超时	模拟室内弱定位	进入兜底，不无限转圈
低精度场景	打开城市选择	不强制高精度
页面离开	返回上一页	停止定位监听

export function assertLocationPoint(point: GeoPoint): void {
  if (point.lat < -90 || point.lat > 90 || point.lng < -180 || point.lng > 180) {
    throw new Error('定位坐标超出合法范围')
  }
  if (point.accuracyMeter <= 0) {
    throw new Error('定位精度必须大于 0')
  }
}

9. 定位异常排查表

定位问题要先区分权限、设备环境和策略配置。权限没给、定位超时、缓存过期，处理方式完全不同。

现象	优先查看	处理建议
一直定位中	超时时间和回调	必须设置超时
拒绝后页面空白	兜底页	提供手动选择
定位不准	精度策略	高精度场景单独申请
耗电明显	持续监听	页面离开后释放
审核问权限用途	场景说明	文案和功能保持一致

建议给每次定位请求记录场景、策略、结果和耗时。不要记录完整用户轨迹，只记录本次请求是否成功和失败原因。

export interface LocationAuditRecord {
  scene: LocationScene
  accuracy: 'LOW' | 'HIGH'
  result: 'success' | 'fail'
  costMs: number
  reason?: string
}

export class LocationAuditLog {
  private readonly records: LocationAuditRecord[] = []

  append(record: LocationAuditRecord): void {
    this.records.push(record)
  }

  latestFailures(): LocationAuditRecord[] {
    return this.records.filter(item => item.result === 'fail').slice(-10)
  }
}

这类日志能回答“为什么这次没有定位成功”：是用户拒绝、策略超时，还是底层不可用。排查时不需要反复复现用户现场。

定位超时复现场景：给读者一组可执行核验

定位文章要验证精度、超时和拒绝授权。只拿到一次坐标不够，读者还需要看到失败时如何回到手动选择。

核验维度	读者需要准备的证据
输入	页面入口、用户动作、关键参数
过程	日志、状态变化、异常分支
输出	UI 表现、回调结果、持久化结果
回归	同场景重复执行后的结果

interface LocationReplayCase {
  scene: any
  accuracy: any
  timeoutMs: any
  fallback: any
}

const replay82: LocationReplayCase = {
  scene: 'sample',
  accuracy: 'sample',
  timeoutMs: 'sample',
  fallback: 'sample',
}

function assertReplay82(item: LocationReplayCase): void {
  if (item.timeoutMs > 10000 && item.fallback.length === 0) throw new Error('定位超时缺少兜底')
}

这组核验让定位能力同时覆盖授权、精度和超时兜底，避免只验证成功获取坐标。

定位失败回放表：把文章方法变成可复现动作

定位能力要覆盖失败路径。建议分别验证拒绝授权、低精度、超时、无网络四种情况，确认页面不会卡在等待状态。

回放动作	核验方式
拒绝后展示手动选择	准备输入、执行操作、记录结果、给出结论
低精度提示扩大范围	准备输入、执行操作、记录结果、给出结论
超时进入兜底	准备输入、执行操作、记录结果、给出结论
无网络使用缓存位置	准备输入、执行操作、记录结果、给出结论

定位能力需要把失败路径当作正常路径设计。读者可以在拒绝授权、低精度、定位超时、无网络四个场景下分别执行页面流程：拒绝后能手动选择，低精度时给出范围说明，超时后不阻塞页面，无网络时可以使用缓存或提示用户。这样定位功能才不会变成页面卡死点。

定位体验的落地边界：不要把边界留给读者猜

定位功能要明确何时必须自动定位，何时允许用户手动选择。导航、附近服务更依赖自动定位；城市选择、门店筛选可以优先给手动入口。读者如果把所有场景都写成强制定位，拒绝授权后体验会很差。

落地项	处理要求
导航依赖实时位置	需要有明确输入、处理边界和失败兜底
附近服务需要精度	需要有明确输入、处理边界和失败兜底
城市选择允许手动	需要有明确输入、处理边界和失败兜底
筛选场景可使用缓存	需要有明确输入、处理边界和失败兜底

这类边界写清楚后，读者不需要猜哪些逻辑属于页面、哪些属于服务、哪些属于发布前验收。文章的价值也会从“讲了一个功能”变成“给了一套可迁移的工程判断”。

定位联调步骤：按真实路径走一遍

定位功能建议使用四组账号或四组设备状态联调。第一组授权并开启高精度，确认页面能直接使用坐标；第二组拒绝授权，确认手动选择入口可用；第三组关闭网络，确认缓存或默认城市兜底；第四组制造超时，确认页面不会一直 loading。读者按这四组执行，能覆盖大多数定位投诉场景。

这一步的意义是让读者拿到文章后可以直接复现，而不是只理解概念。技术文章如果能把“输入、动作、日志、结果、失败兜底”写完整，读者照着做时出错概率会低很多。

10. 小结：定位要让用户有选择

定位能力不是越精确越好。按场景申请、按精度执行、按超时兜底、按生命周期释放，才能既满足业务，又降低权限解释成本。