更新记录

1.3.0（2026-08-30）

• 新增坐标转换、圆形地理围栏、本地轨迹、步行/骑行算路、导航事件类型化、定位高级参数和查询取消。
• 支持 uni-app / uni-app x App Android、iOS；Harmony 仅提供编译兜底。
• Android 使用高德导航定位 11.2.100；iOS 使用 AMapLocation 2.12.2、AMapNavi 11.2.100、AMapFoundation 1.9.0 和本地 AMapTrackKit 1.4.2。
• 修复 Android 高德隐私接口重复调用导致的初始化错误。
• 已知边界：iOS 导航组件仅支持驾车，geoLanguage 仅 Android 生效，deleteTrack 需由业务侧调用服务端接口。

1.0.0（2026-03-29）

• 首次正式发布
• 支持高德定位、猎鹰轨迹、导航能力
• 更新使用文档与示例

平台兼容性

uni-app(5.24)

uni-app x(5.24)

hans-amap-falcon

hans-amap-falcon 是一个面向 uni-app x 的 UTS 功能插件，封装了高德定位、猎鹰轨迹和原生全屏导航能力。

平台支持

• 支持平台：uni-app x App Android、iOS
• Harmony 当前仅提供编译兜底空实现，不提供实际能力
• 插件依赖原生 SDK，建议在自定义基座或原生工程中进行真机联调
• 发布验证基于 HBuilderX 5.24.2026081301；Android 运行态使用自定义基座验证，建议发布时使用该版本或更高版本。

原生依赖

• iOS 定位 SDK：AMapLocation 2.12.2
• iOS 导航 SDK：AMapNavi 11.2.100
• iOS 猎鹰轨迹：仓库内置 AMapTrackKit 1.4.2
• Android 依赖版本和来源以 utssdk/app-android/config.json 及 libs 目录为准。

安装与导入

将插件安装到项目的 uni_modules 后，在页面或业务模块中按需显式导入：

import {
  setup,
  setPrivacyAgree,
  getPermissionSnapshot,
  requestLocationPermission,
  requestBackgroundLocationPermission,
  requestNotificationPermission,
  openPermissionSettings,
  getLocation,
  startLocationUpdate,
  stopLocationUpdate,
  onLocationChangeError,
  startLocationUpdateBackground,
  requestTemporaryFullAccuracyAuthorization,
  onLocationChange,
  offLocationChange,
  setTrackConfig,
  onTrackStateChange,
  onTrackError,
  startTrack,
  startGather,
  getTrackState,
  stopTrack,
  stopGather,
  addTrackTerminal,
  queryTrackTerminal,
  addTrack,
  queryTrackLastPoint,
  queryTrackDistance,
  queryTrackHistory,
  queryTrackHistoryAndDistance,
  cancelTrackQueries,
  calculateDriveRoute,
  calculateRoute,
  setTtsMuted,
  setEmulatorSpeed,
  setNaviOptions,
  onNaviEvent,
  startNavi,
  selectRoute,
  recalculateRoute,
  pauseNavi,
  resumeNavi,
  stopNavi,
  offNaviEvent,
  convertCoordinate,
  createLocalTrackSession,
  addCircleGeofence,
  removeGeofence,
  onGeofenceEvent,
  offGeofenceEvent,
  AmapActionOptions,
  AmapBackgroundLocationOptions,
  AmapDriveRoutePlanOptions,
  AmapListenerId,
  AmapLocationChangeCallback,
  AmapSetupOptions,
  AmapPrivacyOptions,
  AmapOpenPermissionSettingsOptions,
  AmapPermissionSnapshot,
  AmapRequestPermissionOptions,
  AmapLocationOptions,
  AmapLocationResult,
  AmapLocationUpdateOptions,
  AmapRequestTemporaryFullAccuracyOptions,
  AmapStopLocationOptions,
  AmapTrackAddTerminalOptions,
  AmapTrackAddTrackOptions,
  AmapTrackConfig,
  AmapTrackQueryDistanceOptions,
  AmapTrackQueryHistoryOptions,
  AmapTrackQueryLastPointOptions,
  AmapTrackQueryTerminalOptions,
  AmapCalculateRouteOptions,
  AmapConvertCoordOptions,
  AmapConvertCoordResult,
  AmapLocalTrackSessionOptions,
  AmapLocalTrackSession,
  AmapGeofenceAddCircleOptions,
  AmapGeofenceRemoveOptions,
  AmapGeofenceEvent,
  AmapTrackState,
  AmapSetEmulatorSpeedOptions,
  AmapSetNaviOptions,
  AmapSetTtsMutedOptions,
  AmapNaviEvent,
  AmapNaviRouteActionOptions,
  AmapNaviRecalculateOptions,
  AmapNaviStartOptions,
} from '@/uni_modules/hans-amap-falcon'

其他 API 同理，按实际使用场景分别显式导入即可。

接入前准备

Android Key 配置

Android 支持两种 Key 来源：

• 运行时传入 setup({ androidKey })
• 项目侧 nativeResources/android/manifestPlaceholders.json 中配置 com.amap.api.v2.apikey

优先级如下：

• setup({ androidKey }) 优先
• 未传 androidKey 时回退到 Android Manifest 中的 meta-data

示例：

{
  "com.amap.api.v2.apikey": "your-android-key"
}

iOS Key 配置

• iOS 仅支持在 setup({ iosKey }) 中传入
• 未传有效 iosKey 时，setup() 会失败

隐私授权

在调用 setup() 前，先调用 setPrivacyAgree() 同步业务侧隐私授权状态。

const privacyOptions : AmapPrivacyOptions = {
  hasContainsPrivacy: true,
  hasShowPrivacy: true,
  hasAgreePrivacy: true,
}

setPrivacyAgree(privacyOptions)

权限与系统配置

Android 权限

业务侧通常需要在工程中声明并按需申请以下权限：

• ACCESS_COARSE_LOCATION
• ACCESS_FINE_LOCATION
• ACCESS_BACKGROUND_LOCATION
• POST_NOTIFICATIONS
• FOREGROUND_SERVICE
• FOREGROUND_SERVICE_LOCATION
• INTERNET
• ACCESS_NETWORK_STATE

iOS 权限

至少需要在 Info.plist 中提供：

• NSLocationWhenInUseUsageDescription
• NSLocationAlwaysAndWhenInUseUsageDescription

如果需要后台定位，还需要在 Xcode 中开启 Location updates capability。

推荐接入顺序

建议按以下顺序接入：

1. 调用 setPrivacyAgree() 同步隐私授权状态。
2. 调用 setup() 完成 SDK 初始化。
3. 调用权限相关 API，确保前台定位、后台定位、通知权限满足业务要求。
4. 接入定位能力。
5. 接入猎鹰轨迹采集。
6. 接入导航算路与导航控制。

初始化

const setupOptions : AmapSetupOptions = {
  androidKey: 'your-android-key',
  iosKey: 'your-ios-key',
  enableLog: true,
  checkPrivacyBeforeSetup: true,
  success: (res) => {
    console.log('setup success', res)
  },
  fail: (err) => {
    console.error('setup fail', err)
  },
}

setup(setupOptions)

权限管理

获取权限快照

const snapshot: AmapPermissionSnapshot = getPermissionSnapshot()
console.log('permission snapshot', snapshot)

申请前台定位权限

const permissionOptions : AmapRequestPermissionOptions = {
  success: (res) => {
    console.log('location permission', res)
  },
  fail: (err) => {
    console.error('location permission fail', err)
  },
}

requestLocationPermission(permissionOptions)

其他权限接口

const settingsOptions : AmapOpenPermissionSettingsOptions = {
  success: () => {
    console.log('open settings success')
  },
}

requestBackgroundLocationPermission(permissionOptions)
requestNotificationPermission(permissionOptions)
openPermissionSettings(settingsOptions)

定位

单次定位

const locationOptions : AmapLocationOptions = {
  highAccuracy: true,
  timeout: 10000,
  needAddress: true,
  success: (res: AmapLocationResult) => {
    console.log('single location', res)
  },
  fail: (err) => {
    console.error('single location fail', err)
  },
}

getLocation(locationOptions)

持续定位监听

const updateOptions : AmapLocationUpdateOptions = {
  interval: 2000,
  highAccuracy: true,
  onceLatest: true,
  needAddress: true,
}

const handleLocationChange : AmapLocationChangeCallback = (res) => {
  console.log('location change', res)
}

const locationListenerId : AmapListenerId = onLocationChange(handleLocationChange)

const stopLocationOptions : AmapStopLocationOptions = {}

onLocationChangeError((err) => {
  console.error('location update error', err)
})

startLocationUpdate(updateOptions)

// 停止时清理
stopLocationUpdate(stopLocationOptions)
offLocationChange(locationListenerId)

开启后台定位

const backgroundLocationOptions : AmapBackgroundLocationOptions = {
  notification: {
    channelId: 'amap-location',
    channelName: '定位服务',
    title: '后台定位中',
    content: '正在持续获取定位信息',
  },
  success: () => {
    console.log('background location enabled')
  },
}

startLocationUpdateBackground(backgroundLocationOptions)

猎鹰轨迹

设置轨迹配置

在调用 startTrack() 或查询接口前，先配置 serviceId / terminalId / trackId。

const trackConfig : AmapTrackConfig = {
  serviceId: 'service-id',
  terminalId: 'terminal-id',
  trackId: 'track-id',
  interval: 5000,
  uploadInterval: 30000,
  uploadMode: 'default',
  cacheSize: 50,              // 本地缓存上限 MB，仅 Android 生效
  customAttribute: { bizLine: 'logistics' }, // 自定义点位业务字段，随上报点透传
}

setTrackConfig(trackConfig)

启动轨迹采集与上传

const startTrackOptions : AmapActionOptions = {
  success: () => {
    console.log('startTrack success')
  },
}

const startGatherOptions : AmapActionOptions = {
  success: () => {
    console.log('startGather success')
  },
}

onTrackStateChange((state: AmapTrackState) => {
  console.log('track state', state)
})

onTrackError((err) => {
  console.error('track error', err)
})

startTrack(startTrackOptions)
startGather(startGatherOptions)

const trackState : AmapTrackState = getTrackState()
console.log('current track state', trackState)

停止轨迹采集与上传

const stopGatherOptions : AmapActionOptions = {
  success: () => {
    console.log('stopGather success')
  },
}

const stopTrackOptions : AmapActionOptions = {
  success: () => {
    console.log('stopTrack success')
  },
}

stopGather(stopGatherOptions)
stopTrack(stopTrackOptions)

轨迹管理与查询

const addTrackTerminalOptions : AmapTrackAddTerminalOptions = {
  serviceId: 'service-id',
  terminalName: 'device-001',
  terminalDesc: 'test device',
  success: (res) => {
    console.log('addTrackTerminal', res)
  },
}

const queryTrackTerminalOptions : AmapTrackQueryTerminalOptions = {
  serviceId: 'service-id',
  terminalName: 'device-001',
  success: (res) => {
    console.log('queryTrackTerminal', res)
  },
}

const addTrackOptions : AmapTrackAddTrackOptions = {
  serviceId: 'service-id',
  terminalId: 'terminal-id',
  success: (res) => {
    console.log('addTrack', res)
  },
}

const queryTrackLastPointOptions : AmapTrackQueryLastPointOptions = {
  serviceId: 'service-id',
  terminalId: 'terminal-id',
  trackId: 'track-id',
  correctionMode: 'driving',
  success: (res) => {
    console.log('queryTrackLastPoint', res)
  },
}

const queryTrackDistanceOptions : AmapTrackQueryDistanceOptions = {
  serviceId: 'service-id',
  terminalId: 'terminal-id',
  trackId: 'track-id',
  startTime: Date.now() - 60 * 60 * 1000,
  endTime: Date.now(),
  correctionMode: 'driving',
  recoupMode: 'default',
  recoupGap: 5000,
  success: (res) => {
    console.log('queryTrackDistance', res)
  },
}

const queryTrackHistoryOptions : AmapTrackQueryHistoryOptions = {
  serviceId: 'service-id',
  terminalId: 'terminal-id',
  trackId: 'track-id',
  startTime: Date.now() - 60 * 60 * 1000,
  endTime: Date.now(),
  correctionMode: 'driving',
  recoupMode: 'default',
  recoupGap: 5000,
  order: 'desc',
  pageIndex: 1,
  pageSize: 20,
  success: (res) => {
    console.log('queryTrackHistory', res)
  },
}

const queryTrackHistoryAndDistanceOptions : AmapTrackQueryHistoryOptions = {
  serviceId: 'service-id',
  terminalId: 'terminal-id',
  trackId: 'track-id',
  startTime: Date.now() - 60 * 60 * 1000,
  endTime: Date.now(),
  success: (res) => {
    console.log('queryTrackHistoryAndDistance', res)
  },
}

addTrackTerminal(addTrackTerminalOptions)
queryTrackTerminal(queryTrackTerminalOptions)
addTrack(addTrackOptions)
queryTrackLastPoint(queryTrackLastPointOptions)
queryTrackDistance(queryTrackDistanceOptions)
queryTrackHistory(queryTrackHistoryOptions)
queryTrackHistoryAndDistance(queryTrackHistoryAndDistanceOptions)

导航

算路

const routeOptions : AmapDriveRoutePlanOptions = {
  startPoint: {
    latitude: 31.2304,
    longitude: 121.4737,
    name: '起点',
  },
  endPoint: {
    latitude: 31.2243,
    longitude: 121.4768,
    name: '终点',
  },
  strategy: 'default',
  success: (res: AmapDriveRoutePlanResult) => {
    console.log('calculateDriveRoute', res)
  },
  fail: (err) => {
    console.error('calculateDriveRoute fail', err)
  },
}

calculateDriveRoute(routeOptions)

设置导航选项

const setNaviOptionsOptions : AmapSetNaviOptions = {
  broadcastMode: 'detailed',
  multiRouteEnabled: true,
  trafficInfoEnabled: true,
  vehicleInfo: {
    vehicleId: '沪A12345',
    vehicleType: 'car',
    restrictionEnabled: true,
  },
}

const setTtsMutedOptions : AmapSetTtsMutedOptions = {
  muted: false,
}

const setEmulatorSpeedOptions : AmapSetEmulatorSpeedOptions = {
  speed: 60,
}

setNaviOptions(setNaviOptionsOptions)
setTtsMuted(setTtsMutedOptions)
setEmulatorSpeed(setEmulatorSpeedOptions)

启动导航

const naviListenerId : AmapListenerId = onNaviEvent((event: AmapNaviEvent) => {
  console.log('navi event', event)
})

const startNaviOptions : AmapNaviStartOptions = {
  startPoint: {
    latitude: 31.2304,
    longitude: 121.4737,
    name: '起点',
  },
  endPoint: {
    latitude: 31.2243,
    longitude: 121.4768,
    name: '终点',
  },
  routeId: 'optional-route-id',
  mode: 'gps',
  launchMode: 'native-fullscreen',
  success: () => {
    console.log('startNavi success')
  },
  fail: (err) => {
    console.error('startNavi fail', err)
  },
}

startNavi(startNaviOptions)

导航运行控制

const selectRouteOptions : AmapNaviRouteActionOptions = {
  routeId: 'route-id',
}

const recalculateRouteOptions : AmapNaviRecalculateOptions = {
  strategy: 'avoid-congestion',
}

const pauseNaviOptions : AmapActionOptions = {}
const resumeNaviOptions : AmapActionOptions = {}

const stopNaviOptions : AmapActionOptions = {
  success: () => {
    console.log('stopNavi success')
  },
}

selectRoute(selectRouteOptions)
recalculateRoute(recalculateRouteOptions)
pauseNavi(pauseNaviOptions)
resumeNavi(resumeNaviOptions)
stopNavi(stopNaviOptions)

offNaviEvent(naviListenerId)

本地轨迹记录

createLocalTrackSession() 提供不依赖猎鹰云端的轻量轨迹会话：数据源为插件 startLocationUpdate() 的持续定位采点，默认内存态，适合跑步、巡检回显等轻量场景。猎鹰定位是“云端重轨迹”（上报/里程/合规），本地轨迹是“端侧轻轨迹”，两者互补而非替代。

const localTrackSession = createLocalTrackSession({
  minInterval: 2000,   // 最小采样间隔 ms（默认 2000）
  minDistance: 5,      // 最小位移过滤 m（默认 5）
  maxPoints: 5000,     // 内存上限，超出丢最旧
  onPointAdded: (point) => console.log('new point', point),
})

localTrackSession.startRecord()

会话方法：startRecord() / stopRecord() / getPoints() / smoothPath() / clear() / destroy()。

行为约定：

• 前置条件：必须已完成 setup() 且处于持续定位中；未开启时 startRecord() 报 9012002，不做静默等待。
• smoothPath() 为轻量等距抽稀（保留首尾点 + 按约 20m 间距取样），不是地图级平滑；输出可直接喂给内置 map 组件 polyline 回放。
• 纯 UTS 实现、无原生依赖，三端（含 Harmony 编译兜底）行为一致；插件 destroy() 会销毁全部会话。

定位高级参数

AmapLocationOptions / AmapLocationUpdateOptions 支持以下高级参数（按平台能力实现，不支持的组合 fail-fast 报错、不做静默降级）：

startLocationUpdate({
  highAccuracy: true,
  interval: 2000,
  scene: 'sport',            // 仅 Android 生效
  geoLanguage: 'zh',         // 仅 Android 生效
})

iOS 专属 API：临时精确定位授权（iOS 14+）。

// 需要在 Info.plist 的 NSLocationTemporaryUsageDescriptionDictionary 中配置 purposeKey
// 缺省 key 为 AMapLocationFullAccuracy
requestTemporaryFullAccuracyAuthorization({
  purposeKey: 'YourPrecisionKey',
  success: () => console.log('temporary full accuracy granted'),
  fail: (err) => console.error(err.errCode, err.errMsg),
})

错误码：9012004 参数取值非法、9012005 临时精确定位授权申请失败、9011005 当前平台不支持。

已知 iOS 真机限制：当前版本曾出现临时精确定位请求停留在“调用中”且不触发 success/fail 的情况；请在目标 HBuilderX/自定义基座上复验后再依赖该回调推进业务流程。

步行 / 骑行算路

calculateRoute() 是 calculateDriveRoute() 的通用版，新增出行方式参数：

calculateRoute({
  mode: 'walk', // drive（默认）| walk | ride
  startPoint: { latitude: 39.909, longitude: 116.397 },
  endPoint: { latitude: 39.920, longitude: 116.410 },
  success: (res) => console.log(res.distance, res.duration),
  fail: (err) => console.error(err.errCode, err.errMsg),
})

平台差异：

• 算路：双端均支持（iOS 走 Walk/Ride Manager 独立算路接口）。
• 导航拉起：walk/ride 算路成功后调用 startNavi()，Android 会以对应出行类型拉起原生导航页；iOS 导航组件仅支持驾车，walk/ride 后调 startNavi() 会失败（当前实测外层错误码为 9014003，消息内包含 9011005）。
• mode 非法取值 fail-fast 报 9017001；walk/ride 不支持途经点。
• 结果结构复用驾车返回（AmapDriveRoutePlanResult）。

导航数据事件类型化

onNaviEvent() 回调的 AmapNaviEvent 在原 payload JSON 字符串之外，提供跨端稳定的类型化字段（payload 至少保留一个大版本作为兼容兜底）：

onNaviEvent((event) => {
  if (event.naviInfo != null) {
    console.log(`${event.naviInfo.currentRoadName} -> ${event.naviInfo.nextRoadName}`)
    console.log(`路线剩余 ${event.naviInfo.routeRemainDistance}m`)
  }
})

平台差异：

• naviInfo：Android 额外的 currentSpeed 与 iOS 额外的 routeDriveDistance / routeDriveTime 不进类型化子集，仍在 raw 中。
• laneInfo：iOS SDK 的车道数据为编码串（laneBackInfo / laneSelectInfo），无法对齐 Android 结构，因此 iOS 端该字段为空、继续走 raw。
• parallelRoadInfo.status 为平台各自编码，语义对照见高德各端文档；iOS 的 hwFlag 细分在 raw 中。
• serviceAreaInfo 不含 detail 字段（双端类型不一致：Android int / iOS String），原始值在 raw。

圆形地理围栏

插件提供圆形地理围栏的创建、移除与事件监听，双端基于高德定位 SDK 原生围栏能力实现。

import {
  addCircleGeofence,
  removeGeofence,
  onGeofenceEvent,
} from '@/uni_modules/hans-amap-falcon'

// 1. 监听围栏事件（enter / exit / stayed / locfail）
const listenerId = onGeofenceEvent((event) => {
  console.log('geofence event', event.type, event.fenceId, event.latitude, event.longitude)
})

// 2. 添加圆形围栏；fenceId 省略时自动生成
addCircleGeofence({
  latitude: 39.909,
  longitude: 116.397,
  radius: 200,
  success: (res) => console.log('fence added', res.fenceId),
  fail: (err) => console.error(err.errCode, err.errMsg),
})

// 3. 移除：传 fenceId 移除单个；省略 fenceId 移除全部
removeGeofence({ fenceId: 'amap-fence-1' })
removeGeofence({})

行为约定：

• 驻留(stayed)为 SDK 固定行为：在围栏内停留 10 分钟以上才触发，双端口径一致，不可配置。
• 初始状态不派发事件：冷启动时若已在围栏内，SDK 会同步一次当前状态（在圈内/圈外），插件只做基线记录、不会派发 enter；之后真实穿越边界才会收到 enter / exit。
• 业务侧 fenceId 映射 Android customId / iOS customID，可自定义、留空自动生成；SDK 内部 id 在事件的 raw 字段透出。
• 错误码段位 9015xxx：9015001 参数非法、9015002 添加失败、9015003 引擎启动失败、9015004 围栏不存在。
• 后台触发围栏依赖后台定位能力：Android 需要后台定位权限且各 ROM 有保活前提；iOS 需要 Always 授权与 Location updates capability。国产 ROM 的围栏后台触发不稳定属于系统限制，错误码会区分参数错误与系统限制。
• Harmony 当前为编译兜底空实现，调用返回不支持错误。

轨迹可视化

本插件专注“定位 + 猎鹰 + 导航”的数据层能力，不内置地图渲染组件。轨迹上图的推荐姿势是：用插件查询轨迹，用 uni-app 内置 map 组件的 polyline / markers 渲染，无需额外购买或集成地图插件。

// 1. 查询猎鹰历史轨迹
queryTrackHistory({
  serviceId: 'service-id',
  terminalId: 'terminal-id',
  trackId: 'track-id',
  startTime: Date.now() - 24 * 60 * 60 * 1000,
  endTime: Date.now(),
  correctionMode: 'driving',
  pageIndex: 1,
  pageSize: 200,
  success: (res) => {
    // 2. 把点集直接喂给内置 map 组件
    polyline.value = [{
      points: (res.points ?? []).map((p) => ({
        latitude: p.latitude,
        longitude: p.longitude,
      })),
      color: '#22a6f2',
      width: 6,
    }]
  },
})

<!-- 3. 模板里一个内置 map 组件即可 -->
<map :polyline="polyline" :markers="markers" :include-points="fitPoints" />

说明：

• 内置 map 组件在 App-Android / App-iOS 底层即为高德地图，坐标直接使用高德 gcj02，无需转换。
• 猎鹰返回点即 gcj02；如果你拿到的是 WGS84（如部分 GPS 设备原始输出）或 BD09 坐标，先用插件的 convertCoordinate() 转成 gcj02 再上图。
• 点量很大时建议对 include-points 抽样传入以控制视野计算开销。
• 两个 playground 的“轨迹可视化”示例页演示了完整链路：模拟点集绘制、queryTrackHistory 真实查询绘制。

坐标转换

插件内置 convertCoordinate()，提供 gcj02 / wgs84 / bd09 六向互转。它是纯数学实现、同步返回结果，双端（含 Harmony 编译兜底）共用同一份逻辑。

import { convertCoordinate } from '@/uni_modules/hans-amap-falcon'

const result = convertCoordinate({
  from: 'wgs84',
  to: 'gcj02',
  latitude: 39.91359571849836,
  longitude: 116.39775550083061,
})
console.log(result.latitude, result.longitude) // gcj02 坐标

行为约定：

• from === to 时原样返回。
• 同步纯函数不走 success / fail 回调：传入非法坐标系或越界经纬度时返回带 errCode: 9016001 的结果对象（errMsg 含失败原因），不会抛异常；调用方应检查 errCode，不做静默降级。
• gcj02 ↔ wgs84 为行业通用偏移算法的近似逆变换，往返残差通常在 1e-6 度量级，不承诺米级精度；gcj02 ↔ bd09 为解析式变换。
• 中国大陆以外区域 gcj02 与 wgs84 视为重合（原值返回）；bd09 仍按公式换算。

API 一览

基础与权限

• setup(options)
• setPrivacyAgree(options)
• destroy()
• getPermissionSnapshot()
• requestLocationPermission(options)
• requestBackgroundLocationPermission(options)
• requestNotificationPermission(options)
• openPermissionSettings(options)

定位

• getLocation(options)
• startLocationUpdate(options)
• stopLocationUpdate(options?)
• startLocationUpdateBackground(options)
• requestTemporaryFullAccuracyAuthorization(options)（iOS）
• onLocationChange(callback) / offLocationChange(listenerId?)
• onLocationChangeError(callback) / offLocationChangeError(listenerId?)

猎鹰轨迹

• setTrackConfig(options)
• addTrackTerminal(options)
• queryTrackTerminal(options)
• addTrack(options)
• queryTrackLastPoint(options)
• queryTrackDistance(options)
• queryTrackHistory(options)
• queryTrackHistoryAndDistance(options)
• cancelTrackQueries(options?)
• startGather(options?) / stopGather(options?)
• startTrack(options?) / stopTrack(options?)
• getTrackState()
• onTrackStateChange(callback) / offTrackStateChange(listenerId?)
• onTrackError(callback) / offTrackError(listenerId?)

导航

• calculateDriveRoute(options)
• calculateRoute(options)
• setNaviOptions(options)
• setTtsMuted(options)
• setEmulatorSpeed(options)
• selectRoute(options)
• recalculateRoute(options?)
• startNavi(options)
• pauseNavi(options?) / resumeNavi(options?)
• stopNavi(options?)
• onNaviEvent(callback) / offNaviEvent(listenerId?)

坐标、会话与围栏

• convertCoordinate(options)
• createLocalTrackSession(options)
• addCircleGeofence(options)
• removeGeofence(options)
• onGeofenceEvent(callback) / offGeofenceEvent(listenerId?)

注意事项

• 业务侧需要自行准备高德开放平台 Key、猎鹰 serviceId / terminalId / trackId 以及服务端策略配置
• 涉及后台定位、轨迹上传、导航拉起时，应结合业务工程权限声明、前台服务通知和系统设置进行联调
• 页面侧请统一从 @/uni_modules/hans-amap-falcon 导入，不要直接引用 utssdk/app-* 目录