更新记录

1.0.0（2026-10-22）

• 新版发布

平台兼容性

uni-app x(5.23)

其他

yt-amapkit 高德地图、导航与定位插件

面向 uni-app x 的标准式组件插件，提供 Android、iOS、HarmonyOS 同名调用接口。先看接入与完整页面，再按需查 150 个业务方法的参数、默认值、返回值和简短调用片段。仅描述本插件实际封装的能力，不代表高德 SDK 的全部底层接口。

iOS 端必须使用 HBuilderX（HBX）5.25 及以上版本（含 5.25）。低于 5.25 的版本不在本插件当前 iOS 接入支持范围内，请先升级，再重新制作并安装 iOS 自定义基座。 这是编译/打包工具的要求，不是 iPhone 的系统版本要求。

特别提醒

• 购买本插件前，请先试用、并充分自测后再购买，购买后无法退款；
• 如有使用上的疑问、bug，可以进交流群联系作者；
• 结合文档和示例代码集成使用；
• 试用必须先打基座、试用必须先打基座、试用必须先打基座重要事情说三遍；
• 本插件仅支持uniapp-x项目
• Android手机型号太多，各品牌对手机的限制不尽相同，需要保活而进行的设置也不一样。随着Android系统的更新迭代，保活的难度也在不断加大。最有效的保活方式还是联系厂家添加白名单以实现进程保活。
• uniappX使用本插件保活、后台定位、后台导航功能iOS需在manifest.json/ios App设置中后台运行能力配置audio,location
• iOS/Android/HarmonyOS需更换appKey,更换位置见下面集成步骤

功能介绍

• 地图显示：支持标准式组件展示地图、切换地图类型，显示实时路况、三维楼块、3D 地形及室内地图，并提供自定义地图样式配置。
• 地图交互：支持移动地图、缩放、旋转、调整倾斜角度、手势开关、指南针与比例尺等控件，以及地图点击取坐标和地图截图。
• 点标记与气泡：支持普通点标记、自定义图片标记、动态更换图标、文字标签、自定义信息窗及标记/气泡点击事件。
• 图形绘制：支持折线、圆、多边形、弧线、文字、地面图片覆盖物、本地图片瓦片及三角网格三维模型。
• 平滑移动：支持图标沿指定轨迹平滑移动，自定义小车等移动图标，移动过程中动态换图、暂停和继续。
• 海量点与点聚合：支持海量点图层，以及随地图缩放自动聚合、拆分点标记；支持更新点数据、图标、聚合样式和图层显隐。
• 热力图：支持根据坐标点生成热力图，动态修改渐变颜色、透明度、点数据及图层显示状态。
• 定位功能：支持单次定位、连续定位、独立后台定位、地址信息返回，以及地图定位蓝点、定位样式和回到当前位置。
• 地点与地址查询：支持关键词搜索、周边地点、输入提示、地点详情、地址转坐标、坐标转地址，以及公交、行政区划和天气查询。
• 出行路线规划：支持驾车、步行、公交、骑行、货车路线查询及未来驾车路线查询，获取路线坐标和对应方案信息。
• 实时导航：支持驾车、步行、骑行、货车导航，提供模拟导航、真实 GPS 导航、驾车/货车算路策略、语音播报及后台导航能力。
• 地理围栏：支持圆形、多边形、关键词地点、周边地点、行政区划围栏，接收进入、离开、停留事件，并提供后台监测及围栏管理接口。
• 猎鹰轨迹（仅 Android、iOS）：支持终端和轨迹创建、位置采集与上报、离线缓存，以及最新位置、历史轨迹和里程查询；HarmonyOS 暂不支持猎鹰轨迹。
• 离线地图：提供城市列表查询、城市离线地图下载、暂停及下载状态回调，实际可用范围受各端 SDK 和服务授权限制。
• 坐标与轨迹工具：支持坐标校验与转换、两点距离、区域面积、地图交互测距及轨迹纠偏。

以上是本插件已封装功能的概览，不代表所有功能在三端的参数、表现和返回字段完全一致。室内地图、地形、离线地图等还受 SDK 能力、区域数据及服务授权影响，具体见必须了解的平台差异。后台定位、围栏、轨迹采集和导航需用户授权及宿主后台配置，不承诺强制停止或系统回收后永久运行。开始接入请按插件调用顺序操作，具体方法、参数和返回值见全接口索引。

阅读导航

• 五分钟跑通地图：一个完整选项式页面。
• 公共参数与返回值：只需看一次的约定。
• 插件调用顺序：定位、后台围栏、猎鹰、导航如何开始与停止。
• 标准式组件 / 全接口索引：按功能找方法和简短调用片段。
• 坐标与嵌套参数 / 点聚合 / 返回值字段词典：复杂对象按需查。
• 常见问题 / 官方错误码 / 平台差异：出现问题再查。

接入与平台配置

将插件放在项目 uni_modules/yt-amapkit 中。地图由标准式组件 <yt-amapkit> 展示；只导入函数不会出现地图。本文示例使用 uni-app x 的选项式 API，Web/小程序不在支持范围内，请使用平台条件编译隔离。

插件包含原生依赖，需制作包含本插件的自定义基座。新增插件、改变原生配置或升级依赖后，重新制作基座；仅热更新页面不足以更新原生库。运行前真实展示隐私说明并取得同意，再初始化；不要把示例中的同意参数当成可以跳过隐私确认。

高德 Key 配置位置

各平台 Key 不能混用。请替换为自己的 Key，不要沿用演示工程身份信息；猎鹰 SID/TID/TRID 也不是地图 Key，需要另外配置真实的猎鹰服务和终端。初始化成功不代表在线服务鉴权已通过。

鸿蒙 Key：试用与普通授权也可修改

打开上表的 string.json，在已有 string 数组中找到下列项，只把 value 改为自己的鸿蒙 Key，不要改 name，也不要删除其他位置权限用途说明：

{ "name": "yt_amapkit_harmony_key", "value": "替换成你自己的鸿蒙平台高德Key" }

修改 Key 后需要重新制作、安装包含本插件的鸿蒙运行包/自定义基座，仅热更新页面不会替换已安装的原生资源。JSON 不是保密容器，Key 仍须在高德后台绑定真实应用身份；不要把测试 Key 当成所有用户通用的凭据。

Android 接入要求

使用定位前申请位置权限；通知、后台定位和前台服务按系统版本及用途分步授权。权限被拒绝时先处理结果，不要循环弹窗；后台运行不等于永久保活。

iOS资源与基座要求

开发工具最低要求：HBuilderX 5.25 及以上（含 5.25）。 最低系统 iOS 13，目前库面向 arm64 真机，不提供模拟器架构。原生依赖通过插件 utssdk/app-ios/config.json 中的 Pod 配置引入，不需要再手动复制一套高德 framework。

地图/导航不仅需要库，还需要资源包。当前配置使用 dependencies-pod-resources: "app" 将 Pod 资源复制到最终 App 根目录，此方式要求 HBuilderX 5.25 或更高版本。最终 App 应包含 AMap.bundle、AMapNavi.bundle、AMapLocation.bundle；缺失时可能定位正常但地图空白，出现 9010004 资源错误。

HBuilderX 低于 5.25 时，请先升级，不要通过向插件 app-ios/Resources/ 重复复制三个 bundle 来规避版本要求；这还会增加上传体积。资源统一由 Pod 提供，不能删除 Pod 仓库的资源或同时采用两种方式重复打包。升级 HBX 后必须重新制作、安装自定义基座，不能只热更新页面。配置支持版本见 DCloud CocoaPods 官方说明。

定位须保留用途说明；后台定位需要后台定位模式，后台导航语音需要对应音频模式。iOS 前台定位授权与 Always 授权应按业务分步申请，由用户决定是否授予。

HarmonyOS 接入要求

当前配置最低 API 12，高德依赖由插件 utssdk/app-harmony/config.json 的 ohpm 配置引入。请核对宿主权限与 entry Ability 配置；后台定位/后台导航所需长时任务模式包括 location、audioPlayback，按实际用途合并到 backgroundModes，不要覆盖宿主其他已有配置。

HarmonyOS 后台功能配置步骤

1. 点击运行->运行到手机/模拟器->运行到鸿蒙
2. 运行成功会在项目根目录下生成unpackage文件夹，找到unpackage/dist/dev/app-harmony/entry,将该文件夹复制到项目根目录下的harmony-configs文件夹下
3. 在 harmony-configs/entry/src/main/module.json5 的已有 entry Ability 中合并下方字段。这是片段，不可替换完整文件；保留 module.type:"entry"、name、mainElement、pages、其他 abilities 等原字段，避免 00303196。

// 合并到完整 module.json5；以下省略其他已有字段
{
    "module": {
        "abilities": [
            {
                // 保留其他已有字段
                "backgroundModes": [
                    "location",
                    "audioPlayback"
                ],
                "continuable": true
            }
        }
    }
}

调用后台功能时插件会按需检查并申请位置权限、准备相应长时任务，但用户可以拒绝；先等待成功事件，再继续定位或导航。鸿蒙猎鹰方法保留同名入口，但返回不支持，不会自动上传轨迹。

五分钟跑通地图

先完成上方 Key / 自定义基座配置。下面是一个完整的选项式页面：用户确认隐私说明后才创建地图，地图就绪后添加标记，点击标记显示标题，退出页面释放资源。隐私说明正文需替换为你应用真实的政策与高德 SDK 数据处理说明。

<template>
  <view class="page">
    <yt-amapkit v-if="showMap" map-id="my-map" class="map"
      @ready="onMapReady" @event="onMapEvent" @error="onMapError" />
    <text class="status">{{ status }}</text>
  </view>
</template>

<script lang="uts">
import { initialize, mapMoveCamera, mapAddMarkerWithIcon,
  releaseOwner, AmapResult } from '@/uni_modules/yt-amapkit'

export default {
  data() {
    return { showMap: false, ready: false, markerId: '', status: '等待隐私确认' }
  },
  onLoad() {
    uni.showModal({
      title: '位置与地图服务说明',
      content: '请先阅读本应用隐私政策及高德 SDK 说明；是否同意使用地图服务？',
      success: (choice) => {
        if (!choice.confirm) { this.status = '未同意，不启用地图'; return }
        const res = initialize({ owner: 'my-page', privacyShown: true, privacyAgreed: true })
        if (res.code != 0) { this.status = res.message; return }
        this.showMap = true // 不在 initialize 之前创建原生组件
      }
    })
  },
  onUnload() {
    this.ready = false
    this.markerId = ''
    releaseOwner({ owner: 'my-page' }) // 组件卸载自动销毁地图
  },
  methods: {
    onMapReady(res: AmapResult) {
      if (res.code != 0) { this.onMapError(res); return }
      this.ready = true
      const camera = mapMoveCamera({ owner: 'my-page', mapId: 'my-map',
        latitude: 30.2741, longitude: 120.1551, zoom: 15 })
      if (camera.code != 0) { this.onMapError(camera); return }
      const marker = mapAddMarkerWithIcon({ owner: 'my-page', mapId: 'my-map',
        latitude: 30.2741, longitude: 120.1551, title: '我的地点', snippet: '点击显示信息窗',
        icon: { path: '/static/logo.png', width: 40, height: 40 } })
      if (marker.code != 0) { this.onMapError(marker); return }
      this.markerId = JSON.parseObject(marker.dataJson)?.getString('id') ?? ''
      this.status = '地图已就绪，标记编号：' + this.markerId
    },
    onMapEvent(res: AmapResult) {
      if (res.code != 0) { this.onMapError(res); return }
      if (res.event == 'markerClick') this.status = '已点击标记：' + res.dataJson
      // cameraChange 触发频繁，不要每帧 stringify、刷长日志或重画所有标记。
    },
    onMapError(res: AmapResult) { this.status = res.event + '：' + res.message }
  }
}
</script>

<style>
.page { flex: 1; position: relative; }
.map { position: absolute; top: 0; right: 0; bottom: 0; left: 0; }
.status { position: absolute; left: 12px; right: 12px; bottom: 20px;
  padding: 8px; background-color: #ffffff; color: #333333; }
</style>

准备项目中真实存在的 static/logo.png，页面加入 pages.json，用包含插件的真机自定义基座运行。这里只显示地图，不会启动定位或导航。再次进入时可用 hasConsent 检查已存同意状态，再 ensureInitialized；不得替用户无条件同意。

统一调用格式与返回值

全部方法形式为 export function 方法名(option : XxxOptions) : AmapResult。从 @/uni_modules/yt-amapkit 导入方法及对应 XxxOptions 类型即可；不是 Promise，不能用 await / then 等待定位或算路完成。所有方法都要传 option，没有业务参数时传 {}。

公共参数只看一次

每个接口下方只列业务参数；公共参数是否适用会单独标明。必填字段不能省略；“可选，默认 …”来自当前 Android 门面的真实兜底值；“可选，按功能处理”不代表统一保留原值，跨端差异见文末。

返回结果 AmapResult

接口速查中的片段只演示本方法，不是独立页面。需要回调的片段使用下面的 handleEvent；复制到选项式 methods 内可改为 this.handleEvent。所有立即结果也要检查 code，不能只检查回调。

import { AmapResult, Point } from '@/uni_modules/yt-amapkit'
function handleEvent(res: AmapResult) {
  if (res.code != 0) { console.error(res.event, res.code, res.message); return }
  if (res.event == 'location') {
    const data = JSON.parseObject(res.dataJson) // 此事件约定为对象
    console.log(data?.getNumber('latitude'), data?.getNumber('longitude'))
  } else if (res.event == 'poi') {
    const data = JSON.parseObject(res.dataJson)
    const items = data?.getArray<UTSJSONObject>('items')
    console.log('地点数量', items?.length ?? 0)
  }
}
// 下方接口示例共用的测试坐标；不是用户当前位置。折线/移动至少2点，多边形至少3点。
const points: Point[] = [
  { latitude: 30.2741, longitude: 120.1551 },
  { latitude: 30.2791, longitude: 120.1601 },
  { latitude: 30.2691, longitude: 120.1641 }
]

对象用 JSON.parseObject；数组用 JSON.parse<UTSJSONObject[]>，布尔/数字/文本分别用 JSON.parse<boolean/number/string>。不要在普通 JS 对象或字符串上直接调 getString；也不要将 dataJson 的 null 当错误。详见返回值字段词典。

权限、隐私与后台

蓝点、定位、真实导航、围栏和猎鹰采集会在插件内部按需申请权限。传 onEvent 并等待结果：同步可能返回 pendingPermission:true，拒绝后回调 code=9010003，本次业务中止；用户拒绝时不要继续算路/采集或循环弹窗。普通地图、静态覆盖物、仅算路及前台模拟导航不要求定位权限。requestPermissions 供需要单独授权入口的业务使用，成功看 permissions 事件的 granted，不是前置必调方法。

后台能力仍须正确配置宿主。iOS 按需从前台授权升级 Always；Android 使用前台服务，鸿蒙准备 LOCATION 长时任务，不无条件强索“始终允许”。@UTSJS.keepAlive 只是插件保留回调的注解，不保证手机进程保活，调用页面不需要添加。用户强停、撤权、系统回收后不承诺继续；后台原生采集也不保证页面 JS 回调或 uni.request 持续执行。

插件调用顺序

总顺序：平台配置 → 真实隐私同意 → initialize → 需要显示地图才挂载组件并等 @ready → 调用业务 → 检查同步结果和对应事件 → 按业务停止/释放。箭头是成功条件，不是连续执行所有方法；不要用固定延时代替 ready。只定位、查询、围栏或猎鹰不需要先显示地图。

覆盖物 id 只从创建成功返回值读取，例如 JSON.parseObject(result.dataJson)?.getString('id')；标记、移动、海量、热力、聚合句柄不能互换。聚合用 clusterRemove，海量用 massRemove，普通覆盖物用 mapRemove。新建围栏先 start 再 add 可避免 Android 后台服务尚未创建客户端时，等待 created 而流程停住；后续控制同样检查回调。

猎鹰后台采集与上报（仅 Android / iOS）

1. trackListen 注册 handleEvent → trackConfigure（例如 gather=2 秒、upload=20 秒、cacheMB=50）。upload 须为 gather 的 5～50 倍，iOS 还要求整数倍及缓存至少 50MB。
2. 准备真实 SID → trackFindTerminal → 等 onQueryTerminalCallback；不存在才 trackCreateTerminal → 从成功 onCreateTerminalCallback 保存 TID。需要新轨迹时 trackCreateTrack → 等 onAddTrackCallback 保存 TRID；已有编号可复用，-1 表示散点。
3. 用户明确同意采集 → trackStart → 等 onStartTrackCallback / onStartGatherCallback 成功再认为已运行；内部顺序启动采集，不必紧接着再 resumeGather。查轨迹/里程同样等 trackListen 的事件。
4. 退出业务 trackStop；只暂停采集用 trackPauseGather，恢复 trackResumeGather；trackDetach 仅解绑，trackDestroy 释放。SID/TID/TRID 不是地图 Key，0 仅是占位；HarmonyOS 返回 9010001，不继续执行。

模拟、真实与真实后台导航

1. 配置页选择出行方式/策略/终点/货车参数，点“模拟导航”“真实导航”或“真实后台导航”跳转纯全屏页。示例位置为 pages/index/navigation.uvue 和 navigation-map.uvue。
2. 导航组件 navigation=true；步行/骑行 travel=true，驾车/货车 travel=false。navigationId 与其 map-id 一致。导航引擎单例，不同时挂两张。
3. 等组件 @ready → navigationCalculate → 成功 naviRouteReady → navigationStart。算路/后台准备/开始的 simulate 保持一致。模拟为 true。
4. 真实模式先由用户确认 → 单次 locationStart 成功 → 用真实当前位置为起点重新算路 → simulate=false 开始；拒绝权限直接结束，不沿用固定测试起点。
5. 后台额外调用 navigationEnableBackground → 等 naviBackgroundReady，路线和后台两项均成功后才 start；失败事件 naviRouteFailed / naviInitFailed / naviBackgroundError 应结束等待。使用 navigationInnerVoice 开启语音，naviText 不证明已经出声。
6. 切后台要保持导航组件挂载。Android/iOS 可 navigationViewPause/Resume 暂停/恢复画面，不要 onHide 调 navigationPause/Stop；鸿蒙 View 生命周期由 ArkUI 管理。用户结束 navigationStop，卸载组件自动销毁。

退出页面、继续后台与重建

releaseOwner({owner}) 清理本页客户端与监听，不代替后台业务 stop。明确继续后台采集时保持对应服务、返回后重订阅；必须提供停止入口。同一应用的后台定位、围栏、猎鹰是共享原生任务，owner 不会让它们变成多套隔离服务。撤回隐私前先停止已开的任务，再 revokeConsent。

普通地图按需 mapPause/mapResume；组件卸载自动销毁地图/导航，旧 id 全部失效。主动 mapDestroy 后需 v-if 卸载，在下一次视图更新重建并等新 ready；不能只把 ready 变量设成 true。map-id/navigation/travel 是创建参数，修改也需重建。配置地形/渲染必须在创建任何地图或导航之前 configureMapRendering。

标准式组件 yt-amapkit

组件通过 native-view 显示原生地图，不是 Web 地图。uvue 按钮放在同级兄弟节点，不要塞入组件；不要用透明全屏层遮住地图。普通页面无需调用内部 mountNativeView。组件创建失败先按常见问题排查。

全接口索引

按模块找方法，点击名称跳到参数表；每项返回均为 AmapResult，下文“返回”专指 dataJson 的含义。控制方法无独立完成事件时不必等待回调；非 0 先看 message。公共参数不重复展开。

片段中的 points 见入门示例，tracePoints / clusterPoints 见对应结构章节；图片需真实存在。示例不是默认值，POI/样式/室内建筑/覆盖物 id 与猎鹰 SID/TID/TRID 须换成真实值。所有方法先做初始化；含 mapId / navigationId 的方法须先等相应组件 ready。

初始化与权限

initialize

已展示隐私政策且用户同意后初始化；不会自动申请权限或开始定位。

initialize(option : InitializeOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：initialize({owner:"my-page", privacyShown:true, privacyAgreed:true})

hasConsent

读取已保存的隐私同意状态。

hasConsent(option : HasConsentOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = boolean：true曾同意，false未同意/已撤回；无独立完成事件。

调用片段：hasConsent({owner:"my-page"})

ensureInitialized

检查已有同意记录并同步各SDK隐私状态；不会替用户同意。

ensureInitialized(option : EnsureInitializedOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：ensureInitialized({owner:"my-page"})

configureMapRendering

创建任何地图/导航前选择渲染引擎；切换前先卸载旧组件。

configureMapRendering(option : ConfigureMapRenderingOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：configureMapRendering({owner:"my-page", terrain:false, world:false, language:0})

revokeConsent

停止本插件的任务、销毁地图导航、解除监听后撤回隐私授权。

revokeConsent(option : RevokeConsentOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；需重新同意后才能使用SDK；无独立完成事件。

调用片段：revokeConsent({owner:"my-page"})

requestPermissions

从可见页面申请权限；先申请前台定位，再单独申请后台定位。

requestPermissions(option : RequestPermissionsOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null，部分已授权情况直接返回授权结果；onEvent → permissions：{granted,denied}；granted=true 且 code=0 才获准。

调用片段：requestPermissions({owner:"my-page", kind:"location", onEvent:handleEvent})

releaseOwner

页面卸载时释放页面内客户端与监听；不会暗中停止独立后台定位、围栏或猎鹰服务。

releaseOwner(option : ReleaseOwnerOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；地图/导航由组件卸载释放；无独立完成事件。

调用片段：releaseOwner({owner:"my-page"})

地图显示与交互

mapControls

显示或隐藏指南针、比例尺、缩放和定位按钮。

mapControls(option : MapControlsOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：mapControls({owner:"my-page", mapId:"my-map", compass:true, scale:true, zoom:true, location:false})

mapGestures

控制用户是否可以拖动、双指缩放、旋转和倾斜地图。

mapGestures(option : MapGesturesOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：mapGestures({owner:"my-page", mapId:"my-map", scroll:true, zoom:true, rotate:true, tilt:true})

mapMoveCamera

把地图视口移到指定坐标；只移动镜头，不开始定位。

mapMoveCamera(option : MapMoveCameraOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：mapMoveCamera({owner:"my-page", mapId:"my-map", latitude:30.2741, longitude:120.1551, zoom:15, animate:true})

mapType

切换底图类型，不改变路况和覆盖物。

mapType(option : MapTypeOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：mapType({owner:"my-page", mapId:"my-map", type:"normal"})

mapTraffic

开启/关闭实时路况图层。

mapTraffic(option : MapTrafficOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：mapTraffic({owner:"my-page", mapId:"my-map", enabled:true})

mapBuildings

开启/关闭3D楼块，不是3D地形开关。

mapBuildings(option : MapBuildingsOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：mapBuildings({owner:"my-page", mapId:"my-map", enabled:true})

mapIndoor

显示有高德室内数据的建筑内部楼层；不是室内定位。

mapIndoor(option : MapIndoorOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：mapIndoor({owner:"my-page", mapId:"my-map", enabled:true, showFloorControl:true})

mapCurrentIndoorBuilding

读取当前激活的室内建筑和楼层。

mapCurrentIndoorBuilding(option : MapCurrentIndoorBuildingOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

无额外业务参数。

返回：dataJson = {active:boolean,poiId?:string,activeFloorIndex?:number,activeFloorName?:string,floors:[{index:number,name:string}]}。active=false表示当前位置没有激活的室内建筑；无独立完成事件。

调用片段：mapCurrentIndoorBuilding({owner:"my-page", mapId:"my-map"})

mapSelectIndoorFloor

用当前室内建筑的真实楼层编号切楼层。

mapSelectIndoorFloor(option : MapSelectIndoorFloorOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：mapSelectIndoorFloor({owner:"my-page", mapId:"my-map", poiId:"填当前建筑poiId", floorIndex:1})

mapMeasureDistance

开启后连续点击地图累计直线距离，接收 distanceMeasured 事件。

mapMeasureDistance(option : MapMeasureDistanceOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；组件 → distanceMeasured（meters 累计米数，points 点数量）；不自动画线或弹面板。

调用片段：mapMeasureDistance({owner:"my-page", mapId:"my-map", enabled:true, onEvent:handleEvent})

mapLocationBlueDot

显示定位蓝点；首次需 requestPermissions。

mapLocationBlueDot(option : MapLocationBlueDotOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；组件 → myLocationChange；拒绝权限由本次 onEvent 返回。

调用片段：mapLocationBlueDot({owner:"my-page", mapId:"my-map", enabled:true, mode:1, interval:2000, showButton:true, onEvent:handleEvent})

mapMyLocation

使用基础MyLocationStyle启停蓝点；常规场景推荐mapLocationBlueDot。

mapMyLocation(option : MapMyLocationOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；组件 → myLocationChange；定位异步产生，不是同步读取当前位置。

调用片段：mapMyLocation({owner:"my-page", mapId:"my-map", enabled:true, mode:1, interval:2000, onEvent:handleEvent})

mapScreenshot

保存地图截图到应用缓存目录，不需存储权限。

mapScreenshot(option : MapScreenshotOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；onEvent → screenshot（path、width、height、renderStatus）。

调用片段：mapScreenshot({owner:"my-page", mapId:"my-map", onEvent:handleEvent})

mapResume

恢复地图渲染，由组件与页面生命周期调用。

mapResume(option : MapResumeOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：mapResume({owner:"my-page", mapId:"my-map"})

mapPause

暂停地图渲染，不停止独立后台定位。

mapPause(option : MapPauseOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：mapPause({owner:"my-page", mapId:"my-map"})

mapLowMemory

通知地图释放可丢弃缓存。

mapLowMemory(option : MapLowMemoryOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：mapLowMemory({owner:"my-page", mapId:"my-map"})

mapSaveState

测试原生状态保存；返回Bundle键名，不等于可跨进程序列化的地图快照。

mapSaveState(option : MapSaveStateOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

无额外业务参数。

返回：dataJson = {keys:string[]}：SDK保存的状态键，桥接层不暴露Bundle；无独立完成事件。

调用片段：mapSaveState({owner:"my-page", mapId:"my-map"})

mapDestroy

释放地图；必须同时卸载组件后才能重建，旧mapId不能继续调用。

mapDestroy(option : MapDestroyOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：mapDestroy({owner:"my-page", mapId:"my-map"})

mapTypeNumber

使用SDK原生数字类型切换底图，通常推荐易读的mapType字符串。

mapTypeNumber(option : MapTypeNumberOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：mapTypeNumber({owner:"my-page", mapId:"my-map", type:1})

覆盖物与动态图标

mapAddMarker

添加默认图标的普通标记；点击显示标题与说明。

mapAddMarker(option : MapAddMarkerOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = {id:string}。保存此id用于修改/删除；清空地图或组件卸载后失效；无独立完成事件。

调用片段：mapAddMarker({owner:"my-page", mapId:"my-map", latitude:30.2741, longitude:120.1551, title:"自定义标记", snippet:"点击标记查看信息"})

mapAddMarkerWithIcon

添加自定义图标的普通标记。

mapAddMarkerWithIcon(option : MapAddMarkerWithIconOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = {id:string}。保存此id用于修改/删除；清空地图或组件卸载后失效；无独立完成事件。

调用片段：mapAddMarkerWithIcon({owner:"my-page", mapId:"my-map", latitude:30.2741, longitude:120.1551, icon:{"path":"/static/icon_annotation.png","width":30,"height":42}, title:"自定义标记", snippet:"点击标记查看信息"})

mapUpdateMarkerIcon

动态换图标，不重新创建业务标记。

mapUpdateMarkerIcon(option : MapUpdateMarkerIconOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

前置：先 mapAddMarkerWithIcon 保存对应 id；同一 mapId，不混用句柄。

调用片段：mapUpdateMarkerIcon({owner:"my-page", mapId:"my-map", id:"填创建返回的id", icon:{"path":"/static/icon_annotation.png","width":30,"height":42}})

mapUpdateMarkerText

更新标记标题/说明；已打开的信息窗会刷新。

mapUpdateMarkerText(option : MapUpdateMarkerTextOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

前置：先 mapAddMarkerWithIcon 保存对应 id；同一 mapId，不混用句柄。

调用片段：mapUpdateMarkerText({owner:"my-page", mapId:"my-map", id:"填创建返回的id", title:"自定义标记", snippet:"点击标记查看信息"})

mapShowInfoWindow

打开某个普通标记的信息窗。

mapShowInfoWindow(option : MapShowInfoWindowOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

前置：先 mapAddMarkerWithIcon 保存对应 id；同一 mapId，不混用句柄。

调用片段：mapShowInfoWindow({owner:"my-page", mapId:"my-map", id:"填创建返回的id"})

mapHideInfoWindow

关闭某个普通标记的信息窗。

mapHideInfoWindow(option : MapHideInfoWindowOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

前置：先 mapAddMarkerWithIcon 保存对应 id；同一 mapId，不混用句柄。

调用片段：mapHideInfoWindow({owner:"my-page", mapId:"my-map", id:"填创建返回的id"})

mapInfoWindowStyle

自定义原生信息窗文字和背景；不是把uvue子元素塞进地图。

mapInfoWindowStyle(option : MapInfoWindowStyleOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：mapInfoWindowStyle({owner:"my-page", mapId:"my-map", enabled:true, fontSize:16, textColor:"#FFFFFF", backgroundColor:"#2069C0"})

mapAddPolyline

按数组顺序连接各点，绘制折线。

mapAddPolyline(option : MapAddPolylineOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = {id:string}。保存此id用于修改/删除；清空地图或组件卸载后失效；无独立完成事件。

调用片段：mapAddPolyline({owner:"my-page", mapId:"my-map", points:points, color:"#2678FF", width:8})

mapAddPolygon

绘制闭合多边形，SDK自动连接末尾与起点。

mapAddPolygon(option : MapAddPolygonOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = {id:string}。保存此id用于修改/删除；清空地图或组件卸载后失效；无独立完成事件。

调用片段：mapAddPolygon({owner:"my-page", mapId:"my-map", points:points, fill:"#553399FF", stroke:"#2678FF", width:8})

mapAddCircle

绘制以指定位置为圆心的圆。

mapAddCircle(option : MapAddCircleOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = {id:string}。保存此id用于修改/删除；清空地图或组件卸载后失效；无独立完成事件。

调用片段：mapAddCircle({owner:"my-page", mapId:"my-map", latitude:30.2741, longitude:120.1551, radius:200, fill:"#553399FF", stroke:"#2678FF"})

mapAddModel

绘制三角网格3D模型；示例是一座金字塔，纹理由icon给出。

mapAddModel(option : MapAddModelOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = {id:string}。保存此id用于修改/删除；清空地图或组件卸载后失效；无独立完成事件。

调用片段：mapAddModel({owner:"my-page", mapId:"my-map", latitude:30.2741, longitude:120.1551, vertices:[-1,0,-1,0,2,0,1,0,-1,1,0,-1,0,2,0,1,0,1,1,0,1,0,2,0,-1,0,1,-1,0,1,0,2,0,-1,0,-1], textureCoordinates:[0,0,0.5,1,1,0,0,0,0.5,1,1,0,0,0,0.5,1,1,0,0,0,0.5,1,1,0], icon:{"path":"/static/logo.png","width":64,"height":64}, length:100, angle:0})

mapAddMassPoints

兼容海量点接口，可传入自定义图标；动态换图标请用mapAddMassPointLayer。

mapAddMassPoints(option : MapAddMassPointsOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = {id:string}。保存此id用于修改/删除；清空地图或组件卸载后失效；无独立完成事件。

调用片段：mapAddMassPoints({owner:"my-page", mapId:"my-map", points:points, icon:{"path":"/static/logo.png","width":64,"height":64}})

mapAddMassPointLayer

批量绘制海量点并返回稳定句柄；同层共用一张图标。

mapAddMassPointLayer(option : MapAddMassPointLayerOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = {id:string}。保存此id用于修改/删除；清空地图或组件卸载后失效；无独立完成事件。

调用片段：mapAddMassPointLayer({owner:"my-page", mapId:"my-map", points:points, icon:{"path":"/static/logo.png","width":64,"height":64}, anchorU:0.5, anchorV:0.5})

massUpdateIcon

批量替换整层海量点的图标，保留原数据。

massUpdateIcon(option : MassUpdateIconOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

前置：先 mapAddMassPointLayer 保存对应 id；同一 mapId，不混用句柄。

调用片段：massUpdateIcon({owner:"my-page", mapId:"my-map", id:"填创建返回的id", icon:{"path":"/static/logo.png","width":64,"height":64}})

massUpdatePoints

替换海量点坐标数组。

massUpdatePoints(option : MassUpdatePointsOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

前置：先 mapAddMassPointLayer 保存对应 id；同一 mapId，不混用句柄。

调用片段：massUpdatePoints({owner:"my-page", mapId:"my-map", id:"填创建返回的id", points:points})

massSetVisible

临时显示/隐藏海量点图层。

massSetVisible(option : MassSetVisibleOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

前置：先 mapAddMassPointLayer 保存对应 id；同一 mapId，不混用句柄。

调用片段：massSetVisible({owner:"my-page", mapId:"my-map", id:"填创建返回的id", visible:true})

massSetAnchor

动态调整图标锚点。

massSetAnchor(option : MassSetAnchorOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

前置：先 mapAddMassPointLayer 保存对应 id；同一 mapId，不混用句柄。

调用片段：massSetAnchor({owner:"my-page", mapId:"my-map", id:"填创建返回的id", anchorU:0.5, anchorV:0.5})

massRemove

移除海量点图层，此id立即失效。

massRemove(option : MassRemoveOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

前置：先 mapAddMassPointLayer 保存对应 id；同一 mapId，不混用句柄。

调用片段：massRemove({owner:"my-page", mapId:"my-map", id:"填创建返回的id"})

mapSmoothMove

沿轨迹自动平滑移动，可在开始前指定自定义图标。

mapSmoothMove(option : MapSmoothMoveOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = {id:string}。保存此id用于修改/删除；清空地图或组件卸载后失效；无独立完成事件。

调用片段：mapSmoothMove({owner:"my-page", mapId:"my-map", points:points, duration:20, icon:{"path":"/static/car.png","width":48,"height":48}})

smoothUpdateIcon

移动中换图标，不重新开始轨迹。

smoothUpdateIcon(option : SmoothUpdateIconOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

前置：先 mapSmoothMove 保存对应 id；同一 mapId，不混用句柄。

调用片段：smoothUpdateIcon({owner:"my-page", mapId:"my-map", id:"填创建返回的id", icon:{"path":"/static/car.png","width":48,"height":48}})

smoothPause

暂停移动，保留当前位置。

smoothPause(option : SmoothPauseOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

前置：先 mapSmoothMove 保存对应 id；同一 mapId，不混用句柄。

调用片段：smoothPause({owner:"my-page", mapId:"my-map", id:"填创建返回的id"})

smoothResume

继续移动。

smoothResume(option : SmoothResumeOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

前置：先 mapSmoothMove 保存对应 id；同一 mapId，不混用句柄。

调用片段：smoothResume({owner:"my-page", mapId:"my-map", id:"填创建返回的id"})

mapStopSmoothMoves

停止并销毁本地图的全部平滑移动对象，旧移动id失效。

mapStopSmoothMoves(option : MapStopSmoothMovesOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：mapStopSmoothMoves({owner:"my-page", mapId:"my-map"})

mapRemove

删除普通覆盖物或旧海量点；可管理扩展图层，移动标记请用mapStopSmoothMoves。

mapRemove(option : MapRemoveOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = boolean：找到并删除为true，否则false；无独立完成事件。

前置：先 mapAddPolyline 保存对应 id；同一 mapId，不混用句柄。

调用片段：mapRemove({owner:"my-page", mapId:"my-map", id:"填创建返回的id"})

mapClear

清空本地图所有覆盖物和移动对象，不销毁底图。

mapClear(option : MapClearOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：mapClear({owner:"my-page", mapId:"my-map"})

mapAddTile

绘制本地PNG瓦片；当前UTS封装使用同一张图片重复铺瓦片，不提供网络URL模板协议。

mapAddTile(option : MapAddTileOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = {id:string}。保存此id用于修改/删除；清空地图或组件卸载后失效；无独立完成事件。

调用片段：mapAddTile({owner:"my-page", mapId:"my-map", path:"$tilePath", size:256, minZoom:14, maxZoom:20, zIndex:1})

mapAddGround

在指定地点覆盖一张图片，宽度按地理米而不是屏幕像素计算。

mapAddGround(option : MapAddGroundOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = {id:string}。保存此id用于修改/删除；清空地图或组件卸载后失效；无独立完成事件。

调用片段：mapAddGround({owner:"my-page", mapId:"my-map", latitude:30.2741, longitude:120.1551, icon:{"path":"/static/logo.png","width":64,"height":64}, width:200})

mapAddText

添加原生文字覆盖物。

mapAddText(option : MapAddTextOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = {id:string}。保存此id用于修改/删除；清空地图或组件卸载后失效；无独立完成事件。

调用片段：mapAddText({owner:"my-page", mapId:"my-map", latitude:30.2741, longitude:120.1551, text:"自定义地图文字", fontSize:30, color:"#2678FF", backgroundColor:"#00FFFFFF"})

mapAddArc

按起点、弧中点、终点绘制弧线，points必须恰好3点。

mapAddArc(option : MapAddArcOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = {id:string}。保存此id用于修改/删除；清空地图或组件卸载后失效；无独立完成事件。

调用片段：mapAddArc({owner:"my-page", mapId:"my-map", points:points, color:"#2678FF", width:8})

点聚合接口

mapAddClusterLayer

创建独立点聚合图层；随地图缩放自动合并/拆分，不改变已有普通标记。

mapAddClusterLayer(option : MapAddClusterLayerOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = {id:string,total:number}。保存id用于更新、显隐、分页读取和移除；mapClear/组件卸载后失效；聚合持续事件见点聚合说明，修改函数不替换创建监听。

调用片段：mapAddClusterLayer({owner:"my-page", mapId:"my-map", points:clusterPoints, radius:80, minClusterSize:2, maxZoom:19, color:"#2678FF", icon:{"path":"/static/icon_annotation.png","width":30,"height":42}, zoomOnClick:true, visible:true})

clusterUpdatePoints

整体替换聚合点数据；保留图层id与样式，传[]只清空本层。

clusterUpdatePoints(option : ClusterUpdatePointsOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；聚合持续事件见点聚合说明，修改函数不替换创建监听。

前置：先 mapAddClusterLayer 保存对应 id；同一 mapId，不混用句柄。

调用片段：clusterUpdatePoints({owner:"my-page", mapId:"my-map", id:"填创建返回的id", points:clusterPoints})

clusterUpdateStyle

调整网格、最小数量、展开级别、聚合颜色和单点图标。

clusterUpdateStyle(option : ClusterUpdateStyleOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；聚合持续事件见点聚合说明，修改函数不替换创建监听。

前置：先 mapAddClusterLayer 保存对应 id；同一 mapId，不混用句柄。

调用片段：clusterUpdateStyle({owner:"my-page", mapId:"my-map", id:"填创建返回的id", radius:80, minClusterSize:2, maxZoom:19, color:"#2678FF", icon:{"path":"/static/icon_annotation.png","width":30,"height":42}, zoomOnClick:true})

clusterSetVisible

显示/隐藏本聚合层，隐藏时保留数据但移除本层原生标记。

clusterSetVisible(option : ClusterSetVisibleOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；聚合持续事件见点聚合说明，修改函数不替换创建监听。

前置：先 mapAddClusterLayer 保存对应 id；同一 mapId，不混用句柄。

调用片段：clusterSetVisible({owner:"my-page", mapId:"my-map", id:"填创建返回的id", visible:true})

clusterGetItems

分页读取本层原始点数据；用于按业务id查找点击项目，不返回SDK对象。

clusterGetItems(option : ClusterGetItemsOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = {id:string,total:number,offset:number,items:ClusterPoint[]}。读取立即返回，不等待异步事件；无独立完成事件。

前置：先 mapAddClusterLayer 保存对应 id；同一 mapId，不混用句柄。

调用片段：clusterGetItems({owner:"my-page", mapId:"my-map", id:"填创建返回的id", offset:0, limit:100})

clusterRemove

移除本聚合层及标记；不影响普通标记或其他聚合层。

clusterRemove(option : ClusterRemoveOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；聚合持续事件见点聚合说明，修改函数不替换创建监听。

前置：先 mapAddClusterLayer 保存对应 id；同一 mapId，不混用句柄。

调用片段：clusterRemove({owner:"my-page", mapId:"my-map", id:"填创建返回的id"})

热力图与扩展图层

heatmapAdd

按坐标密度渲染热力图；点太少不会形成明显热区，先把镜头移到数据范围。

heatmapAdd(option : HeatmapAddOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = {id:string}。保存此id用于修改/删除；清空地图或组件卸载后失效；无独立完成事件。

调用片段：heatmapAdd({owner:"my-page", mapId:"my-map", points:points, radius:40, opacity:0.85})

heatmapUpdateStyle

动态改变渐变色与不透明度，内部换图层但插件id保持稳定。

heatmapUpdateStyle(option : HeatmapUpdateStyleOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = {id:string}。保存此id用于修改/删除；清空地图或组件卸载后失效；无独立完成事件。

前置：先 heatmapAdd 保存对应 id；同一 mapId，不混用句柄。

调用片段：heatmapUpdateStyle({owner:"my-page", mapId:"my-map", id:"填创建返回的id", colors:["#0000FF","#FF00FF","#FF0000"], stops:[0,0.5,1], opacity:0.85})

heatmapUpdatePoints

替换热力点集，保留当前渐变与不透明度。

heatmapUpdatePoints(option : HeatmapUpdatePointsOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = {id:string}。保存此id用于修改/删除；清空地图或组件卸载后失效；无独立完成事件。

前置：先 heatmapAdd 保存对应 id；同一 mapId，不混用句柄。

调用片段：heatmapUpdatePoints({owner:"my-page", mapId:"my-map", id:"填创建返回的id", points:points})

heatmapSetVisible

显示/隐藏已有热力图，不删除数据。

heatmapSetVisible(option : HeatmapSetVisibleOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

前置：先 heatmapAdd 保存对应 id；同一 mapId，不混用句柄。

调用片段：heatmapSetVisible({owner:"my-page", mapId:"my-map", id:"填创建返回的id", visible:true})

heatmapRemove

移除指定热力图。

heatmapRemove(option : HeatmapRemoveOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = boolean：成功移除为true；无独立完成事件。

前置：先 heatmapAdd 保存对应 id；同一 mapId，不混用句柄。

调用片段：heatmapRemove({owner:"my-page", mapId:"my-map", id:"填创建返回的id"})

heatmapClear

仅清除全部热力图，不清其他标记和瓦片。

heatmapClear(option : HeatmapClearOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：heatmapClear({owner:"my-page", mapId:"my-map"})

mapCustomStyle

启用账户下的地图自定义样式；关闭时无须styleId。

mapCustomStyle(option : MapCustomStyleOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：mapCustomStyle({owner:"my-page", mapId:"my-map", enabled:false, styleId:""})

offlineCities

读取可下载城市目录；此操作本身不下载地图包。

offlineCities(option : OfflineCitiesOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；onEvent → offlineCities（items 城市数组）。

调用片段：offlineCities({owner:"my-page", mapId:"my-map", onEvent:handleEvent})

offlineDownloadCity

显式下载城市离线地图，会消耗流量/磁盘；示例有确认提示。

offlineDownloadCity(option : OfflineDownloadCityOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

返回：dataJson = null；onEvent → offlineProgress（city、status、percent）；iOS 可能为 offline（info、status）。

调用片段：offlineDownloadCity({owner:"my-page", mapId:"my-map", city:"杭州", onEvent:handleEvent})

offlinePause

暂停正在进行的离线下载。

offlinePause(option : OfflinePauseOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：offlinePause({owner:"my-page", mapId:"my-map"})

mapExtrasDestroy

释放热力/离线控制器；普通标记保留，通常仅组件卸载时使用。

mapExtrasDestroy(option : MapExtrasDestroyOptions) : AmapResult；公共参数：owner、mapId、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：mapExtrasDestroy({owner:"my-page", mapId:"my-map"})

坐标工具与轨迹纠偏

convertCoordinate

把其他坐标系转成地图GCJ-02；已是GCJ-02不要再次转换。

convertCoordinate(option : ConvertCoordinateOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = {latitude:number,longitude:number}：转换后的GCJ-02坐标；无独立完成事件。

调用片段：convertCoordinate({owner:"my-page", latitude:30.2741, longitude:120.1551, source:"GPS"})

calculateDistance

计算两点直线距离，不是驾车道路里程。

calculateDistance(option : CalculateDistanceOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = number：米；无独立完成事件。

调用片段：calculateDistance({owner:"my-page", fromLatitude:30.2741, fromLongitude:120.1551, toLatitude:30.298, toLongitude:120.178})

calculateArea

计算多边形地理面积，至少3点。

calculateArea(option : CalculateAreaOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = number：平方米，除以1000000得到平方公里；无独立完成事件。

调用片段：calculateArea({owner:"my-page", points:points})

traceCorrect

把带时间/速度的原始轨迹提交高德轨迹纠偏；与猎鹰云端历史查询不同。

traceCorrect(option : TraceCorrectOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；onEvent → traceProcessing / traceFinished / traceFailed，最终 points 才是纠偏结果。

调用片段：traceCorrect({owner:"my-page", lineId:1, points:tracePoints, type:1, onEvent:handleEvent})

traceDestroy

终止纠偏客户端并丢弃迟到结果。

traceDestroy(option : TraceDestroyOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：traceDestroy({owner:"my-page"})

validateCoordinate

仅校验经纬度范围，不进行坐标转换。

validateCoordinate(option : ValidateCoordinateOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：validateCoordinate({owner:"my-page", latitude:30.2741, longitude:120.1551})

parsePoints

验证非空坐标数组并解析；UTS返回普通点数组，不返回原生LatLng。

parsePoints(option : ParsePointsOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = Point[]：验证后的坐标；无独立完成事件。

调用片段：parsePoints({owner:"my-page", points:points})

getMapTypeCode

把底图名称转换为SDK数字常量。

getMapTypeCode(option : GetMapTypeCodeOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = number：SDK地图类型常量；无独立完成事件。

调用片段：getMapTypeCode({owner:"my-page", name:"normal"})

validateMapType

验证数字底图类型是否在本模块支持范围。

validateMapType(option : ValidateMapTypeOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：validateMapType({owner:"my-page", type:1})

validateBlueDot

仅验证蓝点模式与间隔，不开始定位。

validateBlueDot(option : ValidateBlueDotOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：validateBlueDot({owner:"my-page", mode:1, interval:2000})

findFloorPosition

把真实楼层编号转换为数组下标；用于理解地下楼层不是负数组下标。

findFloorPosition(option : FindFloorPositionOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = number：从0开始的数组下标。找不到返回非0错误，而不是-1成功；无独立完成事件。

调用片段：findFloorPosition({owner:"my-page", floorIndices:[-2,-1,1,2], floorIndex:1})

validateAnchor

验证图标锚点是否在0..1范围。

validateAnchor(option : ValidateAnchorOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：validateAnchor({owner:"my-page", anchorU:0.5, anchorV:0.5})

validateHeatmapStyle

只校验热力样式，不创建图层。

validateHeatmapStyle(option : ValidateHeatmapStyleOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：validateHeatmapStyle({owner:"my-page", colors:["#0000FF","#FF00FF","#FF0000"], stops:[0,0.5,1], radius:40, opacity:0.85})

定位与后台定位

locationStart

单次或连续页面定位；同一个owner重复调用会替换之前的定位。

locationStart(option : LocationStartOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；onEvent → location；once=false 持续，code=0 才读取坐标。

调用片段：locationStart({owner:"my-page", once:true, interval:2000, needAddress:true, mode:1, onEvent:handleEvent})

locationStop

停止本owner页面定位，不结束后台服务。

locationStop(option : LocationStopOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：locationStop({owner:"my-page"})

locationDestroy

停止并释放本owner的页面定位客户端。

locationDestroy(option : LocationDestroyOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：locationDestroy({owner:"my-page"})

locationStartBackground

从可见页面启动独立前台定位服务；出现常驻通知，不保证强杀后保活。

locationStartBackground(option : LocationStartBackgroundOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；onEvent → 持续 location；结束必须 locationStopBackground。

调用片段：locationStartBackground({owner:"my-page", interval:2000, needAddress:true, mode:1, onEvent:handleEvent})

locationListenBackground

重新进入页面时订阅已经运行的后台定位；不会自动启动服务。

locationListenBackground(option : LocationListenBackgroundOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；onEvent → 已运行后台任务的 location；本方法不启动定位。

调用片段：locationListenBackground({owner:"my-page", onEvent:handleEvent})

locationStopBackground

明确停止后台定位服务，并解除后台事件监听。

locationStopBackground(option : LocationStopBackgroundOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：locationStopBackground({owner:"my-page"})

地点与地址查询

searchPoi

关键词搜索POI（地点）。

searchPoi(option : SearchPoiOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；onEvent → poi：{items:Poi[],pageCount:number}。

调用片段：searchPoi({owner:"my-page", keyword:"西湖", city:"杭州", type:"", page:1, size:20, onEvent:handleEvent})

searchNearby

按中心点查附近地点。

searchNearby(option : SearchNearbyOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；onEvent → poi，结构同 searchPoi。

调用片段：searchNearby({owner:"my-page", keyword:"西湖", latitude:30.2741, longitude:120.1551, radius:200, onEvent:handleEvent})

searchPoiDetail

用POI唯一ID精确查询详情。

searchPoiDetail(option : SearchPoiDetailOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；onEvent → poiDetail：Poi 或 null。

调用片段：searchPoiDetail({owner:"my-page", id:"填当前建筑poiId", onEvent:handleEvent})

searchGeocode

把文字地址转成经纬度。

searchGeocode(option : SearchGeocodeOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；onEvent → geocode：候选地址数组。

调用片段：searchGeocode({owner:"my-page", address:"杭州市西湖区黄龙体育中心", city:"杭州", onEvent:handleEvent})

searchReverseGeocode

把经纬度转成详细地址。

searchReverseGeocode(option : SearchReverseGeocodeOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；onEvent → reverseGeocode：地址对象及 pois。

调用片段：searchReverseGeocode({owner:"my-page", latitude:30.2741, longitude:120.1551, radius:200, onEvent:handleEvent})

searchBusLine

按线路名称查询公交路线和站点。

searchBusLine(option : SearchBusLineOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；onEvent → busLine：线路数组。

调用片段：searchBusLine({owner:"my-page", keyword:"7路", city:"杭州", onEvent:handleEvent})

searchBusStation

查询公交车站。

searchBusStation(option : SearchBusStationOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；onEvent → busStation：站点数组。

调用片段：searchBusStation({owner:"my-page", keyword:"城站火车站", city:"杭州", onEvent:handleEvent})

searchDistrict

查询行政区和可选边界。

searchDistrict(option : SearchDistrictOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；onEvent → district：行政区数组，含递归 children 与边界字符串。

调用片段：searchDistrict({owner:"my-page", keyword:"杭州市", boundaries:true, onEvent:handleEvent})

searchTips

输入关键词获取搜索联想。

searchTips(option : SearchTipsOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；onEvent → tips：输入提示数组；id/position 可能为空。

调用片段：searchTips({owner:"my-page", keyword:"西湖", city:"杭州", onEvent:handleEvent})

searchWeather

查询城市实况天气。

searchWeather(option : SearchWeatherOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；onEvent → weather：天气对象，部分数字字段为字符串。

调用片段：searchWeather({owner:"my-page", city:"杭州", onEvent:handleEvent})

searchDestroy

释放当前页面的查询控制器，丢弃未完成请求的迟到结果。

searchDestroy(option : SearchDestroyOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：searchDestroy({owner:"my-page"})

出行路线规划

routeCalculate

五种出行方式的路线查询，不启动GPS导航，也不会自动绘线。

routeCalculate(option : RouteCalculateOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；onEvent → route：{mode,paths}，距离米、耗时秒；公交按 segments 分段。

调用片段：routeCalculate({owner:"my-page", mode:"drive", fromLatitude:30.2741, fromLongitude:120.1551, toLatitude:30.298, toLongitude:120.178, city:"杭州", strategy:0, onEvent:handleEvent})

routeFutureDrive

按未来出发时刻查询驾车路线。

routeFutureDrive(option : RouteFutureDriveOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；onEvent → route，mode=futureDrive；当前 Android 不返回 duration。

调用片段：routeFutureDrive({owner:"my-page", fromLatitude:30.2741, fromLongitude:120.1551, toLatitude:30.298, toLongitude:120.178, firstTime:Math.floor(Date.now()/1000)+3600, intervalSeconds:600, count:3, onEvent:handleEvent})

routeDestroy

释放路线查询控制器，丢弃迟到结果。

routeDestroy(option : RouteDestroyOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：routeDestroy({owner:"my-page"})

地理围栏

fenceConfigure

配置全局围栏并注册事件监听；随后添加定义并start。

fenceConfigure(option : FenceConfigureOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；统一 fence 回调；按 eventType 区分 created / statusChanged / 控制事件。

调用片段：fenceConfigure({owner:"my-page", background:false, onEvent:handleEvent})

fenceAdd

添加圆/多边形/关键词POI/周边POI/行政区围栏定义。

fenceAdd(option : FenceAddOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null，先 configure → start → add，再等 created；统一 fence 回调；按 eventType 区分 created / statusChanged / 控制事件。

调用片段：fenceAdd({owner:"my-page", definition:{"type":"circle","customId":"demo-circle","latitude":30.2741,"longitude":120.1551,"radius":200}, onEvent:handleEvent})

fenceStart

开始监控并提交待创建的围栏。

fenceStart(option : FenceStartOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = boolean：请求被接受；真实创建结果继续看fence事件；统一 fence 回调；按 eventType 区分 created / statusChanged / 控制事件。

调用片段：fenceStart({owner:"my-page", onEvent:handleEvent})

fencePause

暂停指定围栏。

fencePause(option : FencePauseOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；统一 fence 回调；按 eventType 区分 created / statusChanged / 控制事件。

调用片段：fencePause({owner:"my-page", customId:"demo-circle", onEvent:handleEvent})

fenceResume

恢复指定围栏。

fenceResume(option : FenceResumeOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；统一 fence 回调；按 eventType 区分 created / statusChanged / 控制事件。

调用片段：fenceResume({owner:"my-page", customId:"demo-circle", onEvent:handleEvent})

fenceRemove

删除指定围栏。

fenceRemove(option : FenceRemoveOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；统一 fence 回调；按 eventType 区分 created / statusChanged / 控制事件。

调用片段：fenceRemove({owner:"my-page", customId:"demo-circle", onEvent:handleEvent})

fenceRemoveAll

删除全部围栏并停止全局监控。

fenceRemoveAll(option : FenceRemoveAllOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；统一 fence 回调；按 eventType 区分 created / statusChanged / 控制事件。

调用片段：fenceRemoveAll({owner:"my-page", onEvent:handleEvent})

fenceDestroy

销毁全局围栏管理器，不是仅退出页面。

fenceDestroy(option : FenceDestroyOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；统一 fence 回调；按 eventType 区分 created / statusChanged / 控制事件。

调用片段：fenceDestroy({owner:"my-page", onEvent:handleEvent})

fenceDetach

仅取消当前页面监听，围栏仍继续运行。

fenceDetach(option : FenceDetachOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；统一 fence 回调；按 eventType 区分 created / statusChanged / 控制事件。

调用片段：fenceDetach({owner:"my-page", onEvent:handleEvent})

猎鹰轨迹

本模块仅 Android/iOS；鸿蒙猎鹰业务返回 9010001，参数校验工具仍可用。先 trackListen；不要以其他方法回调代替全局监听。

trackListen

订阅猎鹰结果；先调用一次，其他猎鹰方法的结果通过该监听返回。

trackListen(option : TrackListenOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = null，只注册监听，不立即返回轨迹；注册猎鹰持续监听，后续事件名即 callbackType。

调用片段：trackListen({owner:"my-page", onEvent:handleEvent})

trackConfigure

设置猎鹰采集/上传间隔及离线缓存，HTTPS固定开启。

trackConfigure(option : TrackConfigureOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：trackConfigure({owner:"my-page", gather:2, upload:20, cacheMB:50})

trackStart

启动猎鹰前台服务，等待服务回调后开始采集。

trackStart(option : TrackStartOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；trackListen.onEvent → onStartTrackCallback / onStartGatherCallback。

调用片段：trackStart({owner:"my-page", serviceId:0, terminalId:0, trackId:-1, onEvent:handleEvent})

trackStop

结束猎鹰采集并停止服务。

trackStop(option : TrackStopOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；trackListen.onEvent → onStopGatherCallback / onStopTrackCallback。

调用片段：trackStop({owner:"my-page"})

trackPauseGather

暂停采集，但不销毁轨迹服务。

trackPauseGather(option : TrackPauseGatherOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；trackListen.onEvent → onStopGatherCallback。

调用片段：trackPauseGather({owner:"my-page"})

trackResumeGather

恢复已经启动的服务内的采集。

trackResumeGather(option : TrackResumeGatherOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；trackListen.onEvent → onStartGatherCallback。

调用片段：trackResumeGather({owner:"my-page", onEvent:handleEvent})

trackCreateTerminal

在猎鹰服务下创建终端（会写入云端）。

trackCreateTerminal(option : TrackCreateTerminalOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；trackListen.onEvent → onCreateTerminalCallback。

调用片段：trackCreateTerminal({owner:"my-page", serviceId:0, name:"demo-terminal"})

trackFindTerminal

通过名称查询终端TID。

trackFindTerminal(option : TrackFindTerminalOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；trackListen.onEvent → onQueryTerminalCallback。

调用片段：trackFindTerminal({owner:"my-page", serviceId:0, name:"demo-terminal"})

trackCreateTrack

为终端创建一条新轨迹TRID（写入云端）。

trackCreateTrack(option : TrackCreateTrackOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；trackListen.onEvent → onAddTrackCallback。

调用片段：trackCreateTrack({owner:"my-page", serviceId:0, terminalId:0})

trackLatest

查询终端最后一个轨迹点。

trackLatest(option : TrackLatestOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；trackListen.onEvent → onLatestPointCallback。

调用片段：trackLatest({owner:"my-page", serviceId:0, terminalId:0, trackId:-1})

trackHistory

查询指定时间内历史散点。

trackHistory(option : TrackHistoryOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；trackListen.onEvent → onHistoryTrackCallback。

调用片段：trackHistory({owner:"my-page", serviceId:0, terminalId:0, startTime:Date.now()-3600000, endTime:Date.now()})

trackTracks

查询指定时间内轨迹列表/轨迹详情。

trackTracks(option : TrackTracksOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；trackListen.onEvent → onQueryTrackCallback。

调用片段：trackTracks({owner:"my-page", serviceId:0, terminalId:0, trackId:-1, startTime:Date.now()-3600000, endTime:Date.now()})

trackDistance

查询云端纠偏里程，默认correction=1、recoup=0、gap=100。

trackDistance(option : TrackDistanceOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；trackListen.onEvent → onDistanceCallback。

调用片段：trackDistance({owner:"my-page", serviceId:0, terminalId:0, trackId:-1, startTime:Date.now()-3600000, endTime:Date.now()})

trackSetLocationMode

设置猎鹰定位模式。

trackSetLocationMode(option : TrackSetLocationModeOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：trackSetLocationMode({owner:"my-page", mode:1})

trackSetId

切换正在采集的轨迹ID。

trackSetId(option : TrackSetIdOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：trackSetId({owner:"my-page", trackId:-1})

trackGetId

读取当前轨迹ID。

trackGetId(option : TrackGetIdOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = number：-1散点或正数轨迹ID；无独立完成事件。

调用片段：trackGetId({owner:"my-page"})

trackDetach

解除当前页面监听，不结束后台采集。

trackDetach(option : TrackDetachOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：trackDetach({owner:"my-page"})

validateTrackIntervals

只验证采集与上报间隔，不启动猎鹰。

validateTrackIntervals(option : ValidateTrackIntervalsOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：validateTrackIntervals({owner:"my-page", gather:2, upload:20})

trackDestroy

停止并释放全局猎鹰客户端，清除自动恢复标志。

trackDestroy(option : TrackDestroyOptions) : AmapResult；公共参数：owner、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：trackDestroy({owner:"my-page"})

trackSetProtocol

设置轨迹上传协议；对外仅允许HTTPS，拒绝明文上传位置。

trackSetProtocol(option : TrackSetProtocolOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：trackSetProtocol({owner:"my-page", protocol:1})

trackQueryDistance

高级距离查询：可指定纠偏和里程补偿参数。

trackQueryDistance(option : TrackQueryDistanceOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = null；trackListen.onEvent → onDistanceCallback。

调用片段：trackQueryDistance({owner:"my-page", serviceId:0, terminalId:0, trackId:-1, startTime:Date.now()-3600000, endTime:Date.now(), correction:1, recoup:0, gap:100})

导航参数与控制

先完成导航调用顺序；前台模拟不需定位权限，真实模式用当前位置。设置面板随平台与出行方式不同，策略见导航算路策略。

navigationCalculate

计算驾车/步行/骑行/货车专业导航路线；不会自动开始。

navigationCalculate(option : NavigationCalculateOptions) : AmapResult；公共参数：owner、navigationId、onEvent（含义）。

返回：dataJson = null；组件 → naviRouteReady 才能 start；失败 naviRouteFailed / naviInitFailed。

调用片段：navigationCalculate({owner:"my-page", navigationId:"my-navi", mode:"drive", fromLatitude:30.2741, fromLongitude:120.1551, toLatitude:30.298, toLongitude:120.178, strategy:0, simulate:true, onEvent:handleEvent})

navigationStart

算路成功后开始模拟或真实导航；模拟为默认。

navigationStart(option : NavigationStartOptions) : AmapResult；公共参数：owner、navigationId、onEvent（含义）。

返回：dataJson = boolean：SDK是否接受开始导航，不表示已到达。真实GPS应使用当前位置作为起点；组件 → naviStarted、naviInfo、naviText、arrived / emulatorFinished。

调用片段：navigationStart({owner:"my-page", navigationId:"my-navi", simulate:true, onEvent:handleEvent})

navigationEnableBackground

为导航开启前台服务；等待naviBackgroundReady后才能start。

navigationEnableBackground(option : NavigationEnableBackgroundOptions) : AmapResult；公共参数：owner、navigationId、onEvent（含义）。

返回：dataJson = null；组件 → naviBackgroundReady / naviBackgroundError；成功后还须等路线。

调用片段：navigationEnableBackground({owner:"my-page", navigationId:"my-navi", simulate:true, onEvent:handleEvent})

navigationBackgroundReady

读取导航前台服务握手是否完成。

navigationBackgroundReady(option : NavigationBackgroundReadyOptions) : AmapResult；公共参数：owner、navigationId、onEvent（含义）。

无额外业务参数。

返回：dataJson = boolean：true可按同一simulate模式启动；false继续等待；无独立完成事件。

调用片段：navigationBackgroundReady({owner:"my-page", navigationId:"my-navi"})

navigationStop

主动停止导航、播报和前台服务。

navigationStop(option : NavigationStopOptions) : AmapResult；公共参数：owner、navigationId、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：navigationStop({owner:"my-page", navigationId:"my-navi"})

navigationPause

暂停导航引擎，不等同于页面onHide。

navigationPause(option : NavigationPauseOptions) : AmapResult；公共参数：owner、navigationId、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：navigationPause({owner:"my-page", navigationId:"my-navi"})

navigationResume

恢复被暂停的导航引擎。

navigationResume(option : NavigationResumeOptions) : AmapResult；公共参数：owner、navigationId、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：navigationResume({owner:"my-page", navigationId:"my-navi"})

navigationInnerVoice

切换SDK内置TTS开关。

navigationInnerVoice(option : NavigationInnerVoiceOptions) : AmapResult；公共参数：owner、navigationId、onEvent（含义）。

返回：dataJson = null；无独立完成事件。

调用片段：navigationInnerVoice({owner:"my-page", navigationId:"my-navi", enabled:true})

navigationSpeak

请求SDK朗读自定义文字。

navigationSpeak(option : NavigationSpeakOptions) : AmapResult；公共参数：owner、navigationId、onEvent（含义）。

返回：dataJson = boolean，SDK 是否接受播报，不代表已实际发声；组件 → ttsPlayStart / ttsPlayEnd（Android 基准，其他端不保证等价）。

调用片段：navigationSpeak({owner:"my-page", navigationId:"my-navi", text:"前方路口请注意安全", force:false, onEvent:handleEvent})

navigationStopSpeak

停止当前语音播报。

navigationStopSpeak(option : NavigationStopSpeakOptions) : AmapResult；公共参数：owner、navigationId、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：navigationStopSpeak({owner:"my-page", navigationId:"my-navi"})

navigationViewResume

恢复导航画面，不重新启动引擎。

navigationViewResume(option : NavigationViewResumeOptions) : AmapResult；公共参数：owner、navigationId、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：navigationViewResume({owner:"my-page", navigationId:"my-navi"})

navigationViewPause

后台时暂停画面；保留引擎和前台服务以继续TTS。

navigationViewPause(option : NavigationViewPauseOptions) : AmapResult；公共参数：owner、navigationId、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：navigationViewPause({owner:"my-page", navigationId:"my-navi"})

navigationSaveState

调用SDK保存临时View状态，返回键名，不暴露Bundle。

navigationSaveState(option : NavigationSaveStateOptions) : AmapResult；公共参数：owner、navigationId、onEvent（含义）。

无额外业务参数。

返回：dataJson = {keys:string[]}；无独立完成事件。

调用片段：navigationSaveState({owner:"my-page", navigationId:"my-navi"})

navigationCarInfo

验证/构建货车参数对象，传入后还需navigationCalculate使用。

navigationCarInfo(option : NavigationCarInfoOptions) : AmapResult；公共参数：owner、onEvent（含义）。

返回：dataJson = UTSJSONObject：输入的货车配置；车牌/米/吨等含义见货车章节；无独立完成事件。

调用片段：navigationCarInfo({owner:"my-page"})

navigationDestroy

销毁导航，停止TTS和前台服务，释放进程单例；由组件卸载调用。

navigationDestroy(option : NavigationDestroyOptions) : AmapResult；公共参数：owner、navigationId、onEvent（含义）。

无额外业务参数。

返回：dataJson = null；无独立完成事件。

调用片段：navigationDestroy({owner:"my-page", navigationId:"my-navi"})

坐标与嵌套参数

所有坐标默认为高德 GCJ-02，经纬度单位为度；GPS/WGS84 先按需 convertCoordinate，已是 GCJ-02 不重复转换。时间通常是 Unix 毫秒，仅 routeFutureDrive.firstTime 是秒。颜色支持 #RRGGBB / #AARRGGBB，AA 在前，00 透明、FF 不透明，不是网页的末尾透明度。

Point 与 TracePoint

Point[] 是对象数组，不是经纬度字符串；线/移动至少 2 点，多边形至少 3 点，弧线恰好 3 点。纠偏片段中的 tracePoints 可按下例定义，生产使用真实采样点：

import { TracePoint } from '@/uni_modules/yt-amapkit'
const tracePoints: TracePoint[] = [
  { latitude: 30.2741, longitude: 120.1551, speed: 20, bearing: 45, time: Date.now() - 10000 },
  { latitude: 30.2745, longitude: 120.1555, speed: 20, bearing: 45, time: Date.now() }
]

IconOptions：动态图标

例如 icon:{path:'/static/car.png',width:48,height:48}。普通标记、平滑移动、海量点可动态换图；海量点同层共用图标，异图需分层。示例的自定义标记用 icon_annotation.png，小车用 car.png，海量点用 logo.png；需要把对应文件放入自己的项目。

地图蓝点模式

interval 为定位间隔，不是模式编号。iOS 无法逐一对应八种旋转细节，见平台差异。

围栏 definition 五种格式

以上字段 latitude/longitude/radius/size/aroundRadius 为 number，points 为 Point[]，其余为 string。customId 是同业务内唯一的非空编号，暂停/恢复/删除使用它，不是标记句柄。poiType 默认空表示不筛选；Android 原生 size 默认 10、aroundRadius 默认 3000 米，实际数量与支持范围受服务限制。

圆形例：definition:{type:'circle',customId:'office',latitude:30.2741,longitude:120.1551,radius:200}。同一回调 configure → start → add；created 才是创建结果，statusChanged 才是进出变化，detach 不停止监控。

货车参数不可混用

路线查询与专业导航的 truck 字段不同；以下 Android 默认只是演示兜底，生产必须填写真实车辆信息，不能用来替代道路标志或驾驶判断。

routeCalculate 货车模式通用 strategy=0 会映射原生货车避堵，其余货车策略限定 1～9；导航 strategy 是下方另一套常量，不能混用。

导航算路策略（驾车 / 货车）

把下面的数字传给 strategy；它是导航 SDK 的策略，不是 routeCalculate 的搜索策略。省略仍为 0，保持兼容；想使用智能推荐时明确传 10。

这是偏好，不保证当地一定有满足全部条件的道路；多路线策略也不保证返回多条路线。货车还受尺寸、载重、限行与 SDK 服务能力影响，须同时传真实 truck 参数。步行 / 骑行走对应 SDK 算路接口，不使用这些驾车偏好。原有其他合法 SDK 策略值仍可手填，示例不会强制改写。

示例操作：导航参数页选择出行方式、中文策略 → 配置起终点 / 货车参数 → 点“模拟导航”“真实导航”或“真实后台导航” → 进入纯全屏导航页 → 等组件和路线就绪后自动开始。三个入口自动设置模拟/后台模式，不需要再点执行；其他功能按钮点击即调用，长按才编辑参数。真实模式只在配置页保留一次安全确认，取消不申请定位；确认后由插件申请权限、获取当前位置并重算，不会拿原模拟起点直接启动 GPS。全屏页不再叠加左右工具条，使用 SDK 自带退出/设置入口；修改策略请退出回配置页。

导航设置与算路是两回事：驾车 / 货车使用各端 SDK 自带的“更多 / 设置”面板（iOS 需 YTAmapKit 1.0.4 及新基座，鸿蒙需更新插件并重制运行包）。iOS 已补齐 2D/3D 视角、日夜模式、智能缩放、全程路况与播报设置回调，通过 naviSettingsChanged 上报生效值。实际设置项随端和出行方式不同，不保证与 Android 每个控件相同；步行 / 骑行不承诺驾车设置面板。策略在配置页设置，默认设置面板不私自改变策略。iOS / 鸿蒙不再叠加旧的仅有语音开关弹窗。

官方说明：iOS 设置面板配置、鸿蒙设置按钮开关。

点聚合说明

Android、iOS、HarmonyOS 使用同一套插件内网格聚合逻辑，标记由各端原生地图绘制，不引入网页地图。聚合算法本身复用已有标记接口；iOS 当前依赖 YTAmapKit 1.0.6（含触摸/气泡修复与图标缓存），需重做基座，Android 图标逻辑尺寸修复需包含新 AAR，鸿蒙需重新生成运行包。示例入口为首页“点聚合”，页面 pages/index/cluster.uvue，全屏地图、中文按钮、选项式写法，默认演示 306 个虚拟点。

聚合调用顺序

真实隐私同意并初始化 → 标准组件 @ready → mapMoveCamera 设置业务区域 → mapAddClusterLayer → 保存立即返回的 dataJson.id → 按同一 mapId、图层 id 更新/显隐/读取/移除。点聚合不主动申请定位，也不自动把地图移到所有数据的位置。

缩小地图将同一网格内多个点合并，放大后自动拆分；点击一组默认在原生点击处理结束后收起组气泡、居中并放大 2 级，避免气泡自动移镜头和聚合缩放同时执行。zoomOnClick:false 可关闭自动放大并保留信息窗；仍会收到点击事件。单点正常显示信息窗，iOS 点击空白处可关闭。调用 clusterUpdatePoints 时相同业务点应沿用自己的 id，不能把普通原生标记的编号填进来。

ClusterPoint 数据结构

图层 id、业务点 id、内部原生 Marker id 是不同的编号。聚合层不能传给 mapRemove 或 massRemove，应使用 clusterRemove。普通标记也不会自动加入聚合，须把其业务数据传给创建/更新聚合接口。

接口片段中的 clusterPoints 可按下例定义（所有点字段见上表）：

import { ClusterPoint } from '@/uni_modules/yt-amapkit'
const clusterPoints: ClusterPoint[] = [
  { id: 'shop-1', latitude: 30.2741, longitude: 120.1551, title: '门店一' },
  { id: 'shop-2', latitude: 30.2742, longitude: 120.1552, title: '门店二' }
]

参数与更新规则

• radius 是世界墨卡托网格边长（以 256 像素瓦片计算的缩放单位），20～200，默认 80；不是米，也不是“任何两点距离小于这个值一定合并”。网格边界两侧的点可能分属两组；倾斜地图时不保证图标绝不重叠。
• minClusterSize 默认 2。未达到该数量时各点单独显示；maxZoom 默认 19，达到该级别后全部拆成单点。坐标完全相同的多个点即便拆分仍会重叠，本版本不做蛛网展开。
• color 只修改聚合数量圆点，格式 #RRGGBB；聚合数量圆点为40逻辑像素（iOS pt / Android dp / Harmony vp），三端按屏幕密度适配。icon 是拆分后单点共用图标，宽高也用逻辑尺寸，支持项目本地静态图片。内置聚合图标对较大数量使用“百/千”量级提示；标题和事件的 count 始终是精确数量。
• clusterUpdateStyle 仅修改明确传入的字段；省略保留旧值，包括 zoomOnClick:false。更新数据和样式失败时保留原图层，不误删普通标记。
• clusterUpdatePoints({points:[]}) 清空点但保留图层；clusterSetVisible({visible:false}) 隐藏但保留数据；clusterRemove 删除图层并使旧 id 失效。
• mapClear 会清空聚合层，组件卸载/地图销毁会释放全部聚合数据和延时任务；releaseOwner 清理同 owner 创建的聚合层，不影响其他 owner 的图层。

聚合事件与返回值

创建时可选传入 onEvent，或者统一使用地图组件的 @event。两种入口均会接收聚合事件，不要同时处理两份相同事件。示例只在组件处理持续事件。后续更新函数自己的 onEvent 不会替换创建时的持续监听；更新函数的同步 AmapResult 表示本次是否成功。

itemIds 最多返回前 100 个业务编号，truncated:true 表示还有更多。原始数据请保存在自己的业务数组，或用 clusterGetItems 按 offset、limit 分页读取整层数据；不是按某个临时聚合组分页。该读取立即返回 {id,total,offset,items}，无需等待事件。

性能与边界

每层最多 2000 点；更大数据建议按视野/城市/业务分页，或者使用海量点图层（海量点本身不聚合）。仅在镜头停止后合并刷新（120ms 防抖），不在拖动帧中重建。分组使用整数缩放级别，平移、同一整数级别内的小数缩放及隐藏层不重新计算或发送重复的 clusterRendered；越过 maxZoom 时仍会拆分，数据/样式更新立即生效。分组未变化的标记复用。高缩放下全部拆分仍会创建较多普通标记，应按真实设备性能控制数据量。聚合计算使用纬度夹到墨卡托极限的投影、周期经度处理，绘制仍用原始合法坐标。

返回值字段词典

以下以当前 Android 归一化输出为基准，可选字段可能缺失、为 null 或空数组；跨端扩展字段见平台差异，不猜测 SDK 私有数据。

2. 通用坐标、时间、颜色

3. 地图与覆盖物事件

动态标记、海量点、移动图标的添加结果均为{id}。海量点一层共用一张图标；热力换色/换点后插件id不变；mapClear/mapDestroy后原句柄失效。InfoWindow当前为原生文本视图的颜色、字号和标题内容定制，不是任意uvue组件插槽。

4. 定位

locationStart与locationStartBackground均通过 event='location' 回调。

code=8且message含INVALID_USER_SCODE通常是Key绑定的包名、签名SHA1与实际APK不一致。初始化成功不代表定位鉴权成功。

5. POI、地址、公交与行政区查询

Poi结构

searchPoi/searchNearby返回 event='poi'，数据为 {items:Poi[],pageCount:number}；pageCount是页数，不是当前页数或总条数。searchPoiDetail返回 event='poiDetail'，数据为一个Poi或null。

行政区boundaries每条为 经度,纬度;经度,纬度;...，可能有多个区域，不是Point[]。公交线路distance保留SDK原值，当前桥接不换算，不能和路线distance米数直接相加。

6. 路线与纠偏

routeCalculate返回事件route：mode出行方式；paths候选方案数组，不保证一定有方案。

routeFutureDrive也返回route，但mode='futureDrive'，每个path只有distance、trafficLights交通信号灯数量、points。当前门面未返回未来路线duration/具体出发时刻，不要自己猜字段。

traceCorrect事件：traceProcessing为分段结果（lineId本次编号、segmentIndex分段编号、points分段坐标）；traceFinished为最终结果（lineId、points、distance纠偏距离米、waitingTime等待时长秒）；traceFailed失败。输入TracePoint.speed用公里每小时，time用毫秒。

7. 猎鹰轨迹

先 trackListen({onEvent:...})，再调用创建/查询/采集方法；其他方法自己的onEvent不取代这个监听。SID是服务编号、TID是终端编号、TRID是轨迹编号，都不是地图Key。

所有猎鹰dataJson都有callbackType事件名、isSuccess是否成功、errorCode原始SDK码、errorMsg原始错误说明。外层event就是callbackType，外层code成功统一为0。失败或无结果时额外字段可能没有，禁止取默认0当有效坐标。

历史点结构：lat/lng经纬度、time点上传时间毫秒、locatetime定位时间毫秒、height海拔米、accuracy精度米、direction方向角。无有效TrackPoint时可能返回空对象；纠偏后的点可能不含有效方向。当前门面不承诺返回未输出的速度、自定义属性或总分页数据。

8. 围栏

监听从fenceConfigure.onEvent注册，外层event='fence'；dataJson.eventType区分创建和状态。customId是你传入的业务编号，fenceId是SDK内部围栏编号，不要互换。

9. 导航与TTS

navigationSpeak返回boolean只表示SDK是否接受请求，不能用作“用户确实听到了声音”的证明。后台导航仅在页面组件仍存活、应用进程存活、前台服务就绪时工作；返回退出导航页会销毁组件并停止播报。

常见问题与解决方法

定位、导航等业务失败时，保存同步结果和后续事件的 event/code/message/dataJson，并注明平台；先解决首次失败，不用空坐标、默认 0 或旧 id 继续操作。

高德SDK官方错误码

SDK 报错时，先确认是哪个功能、在哪个平台运行，再点击对应官方文档查看含义和排查方法。以下入口标明了适用平台；同一个数字在不同 SDK、不同平台中可能含义不同，不能把某一端的表当作三端通用表。其他平台请从高德官网切换至对应平台、对应 SDK 的错误码文档。

排查时按下面的顺序读取返回值：

1. 同时记录运行平台、SDK 版本，以及该次同步返回和后续回调的 event/code/message/dataJson，先区分请求已受理、业务成功和失败事件。
2. 如果是插件自定义的 9010001～9010004，先按上方插件错误说明和常见问题与解决方法处理，例如组件未就绪、用户拒绝权限或缺少资源，不要直接套用高德错误码。
3. 如果是 SDK 原始错误，按本次功能和平台查上表；某些原始码在外层 code，猎鹰还保留在 dataJson.errorCode，详细原因可能在 message、errorMsg 或离线事件的 info 中。不是所有回调都包含这些字段。
4. SDK 原始码非 0 不一定表示失败。例如搜索原始成功码 1000 会被插件归一为外层 code=0，猎鹰也有非 0 的成功或状态码；应结合插件事件、外层 code 与适用的 isSuccess 判断，不要只判断 dataJson.errorCode!=0。同步 code=0 仍不代表后续定位、上传或算路已经完成。

必须了解的平台差异

• iOS 定位是 CoreLocation 融合定位，不能精确复制 Android 的“强制 GPS/仅网络”模式。定位 mode=3 降低期望精度；其他模式请求高精度。locationType=0, provider=core_location，不虚构 Android 来源整数。interval 为回调节流目标，不是系统硬性采样周期。
• iOS mapLowMemory 没有公开的同等 SDK 入口，明确返回9010001，内存警告由SDK处理，不用删除磁盘缓存来冒充内存回收。
• 鸿蒙 mapLowMemory、navigationViewPause/Resume 同样返回9010001；导航视图生命周期由 ArkUI 管理。导航引擎的 navigationPause/Resume 可调用，不能混同视图生命周期。
• iOS 蓝点 0/1 按不跟随/首次居中处理，2/6 使用跟随，3 使用方向跟随；4/5/7 不移动镜头。iOS SDK 不存在 Android 八种模式逐一对应的旋转细节，interval 不能强制底层蓝点定位间隔。
• iOS trackSetLocationMode 返回9010001；trackSetProtocol 只允许 HTTPS=1，拒绝 HTTP，避免以明文上传位置。其他猎鹰查询与采集入口已接参考管理器。
• 猎鹰间隔按 Android 的采集1～60秒、上报5～50倍校验；iOS SDK 还要求上报周期为采集周期的整数倍，无法满足时明确拒绝。iOS 本地缓存最低50MB（与Android可设1MB不同）。
• 本地PNG瓦片两端保持与Android相同的重复铺图语义及minZoom/maxZoom，不把path改成网络模板；iOS瓦片叠放按SDK添加顺序，不能逐一对应Android的任意zIndex值。
• 鸿蒙官方高斯热力瓦片半径支持10～50像素；超过50明确报参数错误，不悄悄截断或把普通热力替换成蜂巢图。Android/iOS仍使用各自支持范围。
• iOS 三角网格使用 GLES2/3，不能同时把 MAMapView.metalEnabled 改成 true。着色器/纹理失败会发 modelError；真实地形倾斜视角、遮挡、纹理方向还需真机验收，不承诺未经测试的视觉效果。
• InfoWindow 是原生气泡/ArkUI文字视图，不是任意 uvue 子组件树；点击以 infoWindowClick 返回。海量点每层共享一个图标，异图标需要分层。
• 部分高级返回（离线城市、离线下载状态、saveState、未来算路、围栏原始扩展、猎鹰SDK扩展字段）有平台差异，不要把 SDK 私有字段当成跨端契约。核心定位/坐标、POI、室内楼层、普通路线等已做业务字段归一化。
• iOS/鸿蒙 naviText 是导航文本事件，不是音频已实际出声的证明。当前未保证 Android ttsPlayStart/ttsPlayEnd 的跨端等价回调；真机需验证真实播报与音频打断恢复。
• 导航引擎单例；开启后台只准备能力，必须等 naviRouteReady 与 naviBackgroundReady 后另调用 navigationStart。真实GPS必须由用户明确选择，不能算路成功后自动启动。
• 不要在 onHide 调用导航 stop/destroy，否则后台 TTS 也会停止。关闭页面卸载组件会销毁导航。独立后台定位/围栏/猎鹰需要业务明确 stop；releaseOwner 只解绑页面监听。
• “后台持续”不等于永久保活。强杀、撤权、省电、系统资源回收均可能终止采集/播报。iOS Always 应在前台授权之后单独申请；鸿蒙本插件使用前台位置授权与 LOCATION 长时任务，不强制要求“始终允许”。