更新记录

0.1.0（2026-09-06）

初始化

平台兼容性

uni-app(4.57)

uni-app x(4.73)

其他

XTF 高德地图原生组件

xtf-amapview 是一个适用于 uni-app x 的高德原生地图组件，提供地图展示、相机控制、标记与图形覆盖物、定位、搜索、路线规划、轨迹、计算、截图和离线地图能力。

重要说明

• 插件 id 与组件名称为 xtf-amapview，原生实现集成高德 AMap SDK，必须申请并配置高德各平台 Key。
• iOS 采用高德官方轻量版地图 SDK（Map3D-Lite）。说明：
  • 轻量版 iOS SDK 仅支持地图展示、相机、标注、覆盖物（点/线/面/圆）、定位、手势等基础能力。
  • 搜索、路线规划、逆地理编码、热力图、点聚合、海量点、轨迹纠偏、截图、坐标换算、离线地图等能力在 iOS 上不支持，调用会触发 featureunavailable 事件（相应接口保留，便于跨端一致调用）。
  • iOS 标准（完整）版插件：https://ext.dcloud.net.cn/plugin?name=xtf-gaodemapview。如需标准版的 POI 搜索、路线规划等完整能力，请使用该标准版插件。
• 支持 Android、iOS 和 Harmony。Harmony 当前仅验证地图展示、相机、交通、定位、总手势、UI 控件、覆盖物（点/线/面/圆、热力图、海量点、平滑移动）、缩放/边界、自定义样式、天气；搜索、路线、截图、坐标转换、离线地图等能力会触发 featureunavailable 事件。
• 标准 uni-app x 页面使用 <xtf-amapview>；nvue 兼容页面使用 <xtf-amapview-nvue>。
• 经纬度数组一律按 [latitude, longitude, latitude, longitude] 成对传入，坐标系参数可选 gcj02、wgs84、bd09。
• 搜索、路线、截图、计算、离线地图等异步调用不返回 Promise，结果由对应组件事件返回。

安装

将本插件放入项目的 uni_modules/xtf-amapview 目录。组件符合 easycom 目录约定，标准 uvue 页面无需手工注册。

最低版本要求：HBuilderX 5.24.0，uni-app x 4.61.0。

配置 Key

在应用启动阶段调用 setAMapKeys。参数顺序固定为 Android、iOS、Harmony 的高德 Key，三个参数均为字符串；暂不使用的平台传空字符串。

// App.uvue
<script setup lang="uts">
import { setAMapKeys, setAMapTerrainEnabled } from "@/uni_modules/xtf-amapview/common/amap-settings.uts"

onLaunch(() => {
  setAMapKeys(
    "YOUR_ANDROID_AMAP_KEY",
    "YOUR_IOS_AMAP_KEY",
    "YOUR_HARMONY_AMAP_KEY"
  )

  // 可选：是否启用地形图层，默认 false。
  setAMapTerrainEnabled(false)
})
</script>

Android、iOS、Harmony 的签名、包名和高德控制台 Key 白名单需要正确匹配。Harmony 已声明网络与定位权限；Android 和 iOS 仍需按应用自身的隐私合规要求配置定位用途说明与权限。

标准 uvue 快速开始

ref 使用 ComponentPublicInstance，通过 $callMethod 调用暴露方法。地图创建完成后才调用方法，因此应从 ready 回调开始操作。

<template>
  <view class="page">
    <xtf-amapview
      ref="mapRef"
      class="map"
      :camera-latitude="39.90923"
      :camera-longitude="116.397428"
      :camera-zoom="13"
      :my-location-enabled="true"
      @ready="onReady"
      @mapclick="onMapClick"
      @locationchange="onLocationChange"
      @featureunavailable="onUnavailable"
    ></xtf-amapview>
  </view>
</template>

<script setup lang="uts">
type MapDetail = UTSJSONObject

const mapRef = ref<ComponentPublicInstance | null>(null)

function onReady(event: UniNativeViewEvent): void {
  mapRef.value?.$callMethod("addMarker", "tiananmen", 39.90923, 116.397428, "天安门", "地图已就绪", false)
}

function onMapClick(event: UniNativeViewEvent): void {
  const detail = event.detail as MapDetail
  console.log(detail["latitude"] as number, detail["longitude"] as number)
}

function onLocationChange(event: UniNativeViewEvent): void {
  console.log(event.detail["accuracy"] as number)
}

function onUnavailable(event: UniNativeViewEvent): void {
  console.warn(event.detail["feature"] as string, event.detail["message"] as string)
}
</script>

<style>
.page {
  flex: 1;
  display: flex;
  flex-direction: column;
}

.map {
  flex: 1;
  width: 100%;
}
</style>

nvue 快速开始

nvue 使用独立组件名 <xtf-amapview-nvue>。它使用 Options API，公开方法通过 $refs.map 调用。nvue 的属性类公开方法均为 apply*，其余方法名称与 uvue 一致。

<template>
  <div class="page">
    <xtf-amapview-nvue
      ref="map"
      class="map"
      :camera-latitude="39.90923"
      :camera-longitude="116.397428"
      :camera-zoom="13"
      @ready="onReady"
      @markerclick="onMarkerClick"
      @featureunavailable="onUnavailable"
    />
  </div>
</template>

<script>
export default {
  methods: {
    onReady() {
      this.$refs.map.addMarker("tiananmen", 39.90923, 116.397428, "天安门", "nvue 示例", false)
      this.$refs.map.applyTrafficEnabled(true)
    },
    onMarkerClick(event) {
      console.log(event.detail.id)
    },
    onUnavailable(event) {
      console.warn(event.detail.feature, event.detail.message)
    }
  }
}
</script>

<style>
.page {
  flex: 1;
  flex-direction: column;
}

.map {
  flex: 1;
}
</style>

组件参数

所有参数都可在运行中通过响应式绑定更新。camera-* 更新会移动地图；其余开关同步到原生地图。

事件

事件参数在 uvue 中为 UniNativeViewEvent，从 event.detail 取值；nvue 中同样通过 event.detail 获取。errorCode 为 0 通常表示成功，具体高德错误码请以 SDK 返回为准。

方法调用约定

以下表格的 map 代号：

• uvue：mapRef.value?.$callMethod("方法名", ...参数)。
• nvue：this.$refs.map.方法名(...参数)。
• 带星号 * 的属性类方法在 nvue 应使用右侧对应的 apply* 名称；uvue 保持左侧方法名。

地图与交互方法

标记方法

图形覆盖物方法

搜索、路线与工具方法

以下方法在鸿蒙端不可用，仅 Android 与 iOS 支持；鸿蒙端调用会触发 featureunavailable。

调用下列方法后，在组件上监听表中对应事件取得异步结果。

离线地图方法

离线地图与下载功能在鸿蒙端不可用，仅 Android 与 iOS 支持；鸿蒙端调用会触发 featureunavailable。

离线地图应遵循：ready 后调用 initializeOfflineMap，收到 offlinemapready 后调用 listOfflineMapRegions，随后选择 adCode 下载。状态变化通过 offlinemapprogress 返回。

平台能力差异

搜索、路线规划、截图、坐标转换、离线地图与下载在鸿蒙端不可用，仅 Android 与 iOS 支持；鸿蒙端调用会触发 featureunavailable。

Harmony 端当前支持：地图/相机/交通/总手势/单项手势/UI 控件/定位/覆盖物、缩放范围、地图边界、自定义样式、地图文字/建筑/室内、标记（可见/锚点/透明度/贴地/旋转/图标/信息窗）、线显隐、热力图、海量点、平滑移动、天气。

建议所有页面监听 featureunavailable，并用 detail.feature 区分能力。这比按平台名称静态分支更可靠，因为它反映的是当前插件实际已验证的能力。

完整异步处理示例

<xtf-amapview
  ref="mapRef"
  class="map"
  @ready="onReady"
  @poisearch="onPoiSearch"
  @routeplan="onRoutePlan"
  @snapshot="onSnapshot"
  @featureunavailable="onUnavailable"
></xtf-amapview>

function onReady(event: UniNativeViewEvent): void {
  mapRef.value?.$callMethod("searchPoi", "天安门", "北京", 0, 10)
}

function onPoiSearch(event: UniNativeViewEvent): void {
  const pois = event.detail["pois"] as Array<UTSJSONObject>
  if (pois.length > 0) {
    const firstPoi = pois[0]
    mapRef.value?.$callMethod(
      "setCamera",
      firstPoi["latitude"] as number,
      firstPoi["longitude"] as number,
      16,
      0,
      0,
      true
    )
  }
}

function onRoutePlan(event: UniNativeViewEvent): void {
  const coordinates = event.detail["coordinates"] as Array<number>
  mapRef.value?.$callMethod("addPolylineWithId", "route", coordinates, "#1677ff", 6, false, true, true)
}

function onSnapshot(event: UniNativeViewEvent): void {
  const path = event.detail["path"] as string
  console.log("地图截图：" + path)
}

function onUnavailable(event: UniNativeViewEvent): void {
  console.warn("能力不可用：" + (event.detail["feature"] as string))
}

常见问题

地图空白或未触发 ready

确认 setAMapKeys 已在 App.uvue 的 onLaunch 中执行，平台 Key、包名、签名与高德控制台配置一致，并已重新构建原生应用。

定位没有结果

确认传入 my-location-enabled 或在 ready 后调用 setMyLocationEnabled(true)，并处理 locationerror。用户拒绝权限时组件会返回错误事件。

Harmony 收到 featureunavailable

这是已知平台能力状态。读取 event.detail.feature 后提供降级界面，或仅在 Android/iOS 使用该能力；不要假设未验证能力可用。

调用方法没有效果

确认调用发生在 ready 之后。标准 uvue 必须使用 $callMethod，nvue 必须使用 $refs.map，且 nvue 的属性类方法应使用 apply* 名称。