更新记录

1.0.0（2026-03-29）

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

平台兼容性

uni-app(5.05)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
- √ - - - - √ √ -
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
- - - - - - - - - - - -

uni-app x(5.05)

Chrome Safari Android iOS 鸿蒙 微信小程序
- - √ √ - -

hans-amap-falcon

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

平台支持

  • 支持平台：uni-app x App Android、iOS
  • Harmony 当前仅提供编译兜底空实现，不提供实际能力
  • 插件依赖原生 SDK，建议在自定义基座或原生工程中进行真机联调

安装与导入

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

import {
  setup,
  setPrivacyAgree,
  getPermissionSnapshot,
  requestLocationPermission,
  requestBackgroundLocationPermission,
  requestNotificationPermission,
  openPermissionSettings,
  getLocation,
  startLocationUpdate,
  stopLocationUpdate,
  onLocationChangeError,
  startLocationUpdateBackground,
  onLocationChange,
  offLocationChange,
  setTrackConfig,
  onTrackStateChange,
  onTrackError,
  startTrack,
  startGather,
  getTrackState,
  stopTrack,
  stopGather,
  addTrackTerminal,
  queryTrackTerminal,
  addTrack,
  queryTrackLastPoint,
  queryTrackDistance,
  queryTrackHistory,
  queryTrackHistoryAndDistance,
  calculateDriveRoute,
  setTtsMuted,
  setEmulatorSpeed,
  setNaviOptions,
  onNaviEvent,
  startNavi,
  selectRoute,
  recalculateRoute,
  pauseNavi,
  resumeNavi,
  stopNavi,
  offNaviEvent,
  AmapActionOptions,
  AmapBackgroundLocationOptions,
  AmapDriveRoutePlanOptions,
  AmapListenerId,
  AmapLocationChangeCallback,
  AmapSetupOptions,
  AmapPrivacyOptions,
  AmapOpenPermissionSettingsOptions,
  AmapPermissionSnapshot,
  AmapRequestPermissionOptions,
  AmapLocationOptions,
  AmapLocationResult,
  AmapLocationUpdateOptions,
  AmapStopLocationOptions,
  AmapTrackAddTerminalOptions,
  AmapTrackAddTrackOptions,
  AmapTrackConfig,
  AmapTrackQueryDistanceOptions,
  AmapTrackQueryHistoryOptions,
  AmapTrackQueryLastPointOptions,
  AmapTrackQueryTerminalOptions,
  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',
}

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)

API 一览

基础与权限

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

定位

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

猎鹰轨迹

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

导航

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

注意事项

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

隐私、权限声明

1. 本插件需要申请的系统权限列表：

Android 可能需要 ACCESS_COARSE_LOCATION、ACCESS_FINE_LOCATION、ACCESS_BACKGROUND_LOCATION、POST_NOTIFICATIONS、FOREGROUND_SERVICE、FOREGROUND_SERVICE_LOCATION、INTERNET、ACCESS_NETWORK_STATE；iOS 需要 NSLocationWhenInUseUsageDescription、NSLocationAlwaysAndWhenInUseUsageDescription，并在需要后台定位时开启 Location updates capability。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

插件可能处理定位、轨迹与导航相关数据；具体采集、上传与保存策略由业务侧配置和后端策略决定。

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

评论列表 撰写评论 向官方投诉

暂无用户评论。