更新记录

1.0.0（2026-10-27）

初版

平台兼容性

uni-app(5.26)

omni-amap 高德地图+定位+导航+POI+离线地图+地理围栏（UTS 组件插件）

基于高德官方最新 SDK 封装的 uni-app UTS 插件：地图组件 + 定位（单次/持续/后台保活）+ 地理编码与逆地理 + POI 搜索 + 路线规划与导航 + 离线地图 + 地理围栏，并内置隐私合规接口与日志脱敏（Key 掩码、坐标降精度）。

当前版本 v1.0.0：Android 端全量可用（地图/定位/逆地理/POI/路线/导航/离线地图/围栏）。iOS 端正在按文末「后续规划」逐里程碑补齐，接口签名与 Android 保持一致。

平台支持

功能边界（购买前必读）

插件内没有试用次数、时长、功能开关或白名单，已列出的能力购买后全部可调用。以下是实测确认的边界，请先看一眼再买：

重要：使用前提

1. 高德开放平台账号（https://lbs.amap.com，需实名认证），创建应用并申请 Android Key：需绑定包名 + 发布版安全码 SHA1（keytool -list -v -keystore 你的签名证书）
2. 隐私合规必须先调用：高德 SDK 强制要求，未完成合规调用一切能力返回 1907 错误。
3. 地图组件 <omni-amap-view> 只能在 nvue 页面使用（uni-app 兼容模式 UTS 组件的平台限制）；不需要地图界面的业务可以直接在 vue 页面调用本插件的全部 API 函数。
4. 修改插件原生代码后需重新制作自定义调试基座，标准基座不生效。
5. 关于二次开发：付费插件由插件市场自动加密除 interface.uts 外的全部 .uts 与原生混编文件。需自己改原生代码（扩展属性/方法、调整原生行为）的，请购买源码授权版；普通授权版可正常使用与升级，但无法查看和修改原生实现。

Key 配置（使用方必读）

插件包内不含任何高德 Key。Key 必须由使用方用自己的高德开放平台账号申请后自行配置； Android Key 需绑定你的应用包名与签名证书 SHA1，否则地图/定位会报 INVALID_USER_KEY。

两处都要配，缺一不可：

第 1 项文件位于宿主工程根目录的 nativeResources/android/ 下（目录不存在就自己建）：

{
  "AMAP_ANDROID_KEY": "你的 Android Key"
}

自检方法：启动后日志出现 [omni-amap][自检] Manifest 高德 Key 已生效: abcd****wxyz（前 4 位 + 后 4 位，中间打码）即配置正确。 若看到「缺失」或「占位符未被替换（含 $）」，说明第 1 项没配好。日志中的 Key 已脱敏（前 4 位 + 后 4 位），可用于核对是否用的是自己的 Key。

⚠️ 如果完全没建 manifestPlaceholders.json，云端打包可能报占位符未定义（AMAP_ANDROID_KEY）而中断， 建文件但值留空则能打包成功、但定位会报错——两种情况都按上面的自检日志排查。

隐私合规（上架必读）

高德 SDK 强制要求先完成隐私合规，否则一切能力返回 1907。顺序不可颠倒：

1. 宿主 App 首次启动先展示自己的隐私政策，并在政策中列明高德 SDK（名称、提供方、使用目的、收集的信息、第三方隐私政策链接）；
2. 用户点击「同意」之后，才允许初始化任何地图/定位能力；
3. 同意后再依次调用 updatePrivacyShow → updatePrivacyAgree，之后才能调用定位/POI/路线/导航等能力。

// 注意：下面整段必须在「用户已同意宿主隐私政策」之后执行
setAmapKey('你的AndroidKey', '', () => {
  updatePrivacyShow(() => {
    updatePrivacyAgree(() => {
      // 到这里才能 getAmapLocation / 挂载 <omni-amap-view>
    })
  })
})

• 未同意前不要申请定位权限，也不要挂载地图组件（组件挂载即初始化 SDK）。
• 用户拒绝或撤回同意后，应停止地图与定位能力。
• 插件自身不采集、不存储、不上传任何数据；坐标与关键词由高德 SDK 直接发送至高德服务器。

快速开始

import { setAmapKey, updatePrivacyShow, updatePrivacyAgree, getAmapLocation } from '@/uni_modules/omni-amap'

// 0. 前提：nativeResources/android/manifestPlaceholders.json 已配置 AMAP_ANDROID_KEY（定位必需）

// 1. 配置地图 Key（先于一切高德能力；iOS 端未实现，第二参传空）
setAmapKey('你的AndroidKey', '', res => console.log(res))

// 2. 隐私合规两步（顺序固定，必须等用户点了「同意」之后再做）
updatePrivacyShow(res => {})   // 声明隐私政策包含高德 SDK 条款
updatePrivacyAgree(res => {})  // 用户实际同意后调用

// 3. 单次定位
getAmapLocation({ needAddress: true, timeout: 8000, locationMode: 'high' }, res => {
  if (res.errorCode === 0) {
    console.log(res.longitude, res.latitude, res.address) // GCJ-02 坐标
  } else {
    console.log('失败', res.errorCode, res.errorInfo)
  }
})

地图组件（nvue 页面）

重要：组件的全部数值/开关属性必须传字符串（uni-app 非 x 的 nvue 下，UTS 组件的 Number/Boolean 属性过桥会静默失败， 并连带破坏整个页面布局：地图层丢失、日志框被顶到页面最上方）。 同理，nvue 下请不要依赖 this.$refs 调用组件方法（该通道实测不生效），操控地图请走下方「属性指令通道」。

<template>
  <omni-amap-view
    v-if="sdkReady"
    class="map"
    :maptype="mapType"
    :center="centerCmd"
    :markpoint="markCmd"
    @maploaded="onMapLoaded">
  </omni-amap-view>
</template>

// 视角："纬度,经度[,缩放],序号"（末尾序号保证同一坐标重复下达也能触发）
this.centerCmd = '39.90923,116.397428,15,' + (++this.seq)
// 落点："纬度,经度,序号"
this.markCmd = '39.909,116.397,' + (++this.seq)
// 批量标记 / 路线折线："纬度,经度;纬度,经度;...;序号"
// 控件开关："zoom:1,compass:1,scale:1,locbtn:1,序号"
// 蓝点：showmylocation = "1" / "0"
// 导航：navifrom/navito/navivia + naviact("embed|calc|start|emu|stop,序号")

API 一览

API 函数（App 端，当前仅 Android）

导航两种用法：① 要“和高德地图 App 一样”的完整体验（多方案选、导航中可全览/设置/退出）→ 用 naviStartPage； ② 要在自己的页面里内嵌导航视图（<omni-amap-view maptype="navi"> + naviact）→ 能出画面、能下发指令， 但回执事件在 nvue 页面不可靠（见「功能边界」），且内嵌的原生按钮可能被叠加层吃触摸； 除非确实需要自定义外框，否则建议直接用 ①。

定位注意：getAmapLocation 必须在 updatePrivacyAgree 之后调用（早于合规会返回 1907）； 地图自带的定位按钮只有在 showmylocation="1"（蓝点开启）之后才会响应， 因此进页先开蓝点再取坐标，定位按钮才会“点了有反应”。

地图组件 <omni-amap-view>

属性指令通道（推荐，全部 String 类型）

事件（@绑定）：mapclick、maplongclick、markerclick、markerdragstart、markerdrag、markerdragend、camerachange、cameraidle、maploaded、mylocation、navievent

注意：事件载荷在 uni-app 兼容模式下包在 e.detail 里，统一用 const e = ev.detail || ev 取值。 navievent（导航状态/算路结果回执）在 uni-app 兼容模式的 nvue 页面实测不可靠，请勿依赖它做业务分支； 需要导航状态时用 naviAddStatusListener()（函数接口，走 JS 回调，不经 nvue 事件通道）。 它监听的是 AMapNavi 应用级单例，而内嵌导航视图与 naviStartPage 都自绑同一个单例， 所以两种导航方式的状态（算路成败/播报/剩余距离时间）都能从这一条回调里拿到——请用这个代替 navievent。

方法（仅用于 Android 侧二次开发参考，需购买源码授权版；nvue 页面请改用上面的属性指令通道）

常见错误码

后续规划（路线图）

本插件以“同一套接口、逐端逐能力对齐”为目标推进，iOS 端分里程碑交付，每个里程碑完成即作为同一插件的更新版本发布：

几点承诺与说明：

• 接口不变：iOS 端沿用现有函数名与回调结构（包括 setAmapKey(androidKey, iosKey) 的第二参），已接入 Android 的项目上 iOS 时业务代码无需重写。
• 需自备 iOS Key：高德 Key 分平台，iOS 绑定 Bundle ID，需你在高德控制台单独申请（接口已预留，不需改代码）。
• 里程碑顺序可能根据实际需求调整，但不会删减已发布的能力；已发布能力的问题修复优先级高于新功能。
• 小程序 / H5 不在规划内（UTS 原生插件的平台限制）。

License

商业授权，详见 license 条款。