@snewbie/capacitor-amap v0.0.10

@snewbie/capacitor-amap

参考 Capacitor Community Google Maps 实现方式完成使用 高德开放平台 Android 地图 SDK 开发的 Capacitor 插件（短期内仅维护安卓端）。

Install

npm install @snewbie/capacitor-amap
npx cap sync

API Keys

要在安卓平台上使用高德地图 SDK，需要申请一个 API Key。请参考 高德地图 SDK 文档 。

Android（详细配置说明请参考 高德地图 SDK 文档）

Android 版高德地图 SDK 要求您将 API 密钥添加到项目中的 AndroidManifest.xml 文件中。

<meta-data android:name="com.amap.api.v2.apikey" android:value="请输入您的用户 Key"/>

要使用某些功能，还需要将以下权限添加到项目中的 AndroidManifest.xml 文件中：

<?xml version='1.0' encoding='utf-8'?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
  <application>
      <meta-data android:name="com.amap.api.v2.apikey" android:value="请输入您的用户 Key"/>
      <!-- 若使用到了定位能力则需要在此声明，并且需要在项目中引入：implementation 'com.amap.api:3dmap:latest.integration' -->
      <service android:name="com.amap.api.location.APSService" />
  </application>
  <!--允许访问网络，必选权限-->
  <uses-permission android:name="android.permission.INTERNET" />  

  <!--允许获取粗略位置，若用GPS实现定位小蓝点功能则必选-->
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> 

  <!--允许获取网络状态，用于网络定位，若无gps但仍需实现定位小蓝点功能则此权限必选-->
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />    

  <!--允许获取wifi网络信息，用于网络定位，若无gps但仍需实现定位小蓝点功能则此权限必选-->
  <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> 

  <!--允许获取wifi状态改变，用于网络定位，若无gps但仍需实现定位小蓝点功能则此权限必选-->
  <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" /> 

  <!--允许写入扩展存储，用于数据缓存，若无此权限则写到私有目录-->
  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> 

  <!--允许写设备缓存，用于问题排查-->
  <uses-permission android:name="android.permission.WRITE_SETTINGS" />  

  <!--允许读设备等信息，用于问题排查-->
  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" /> 
</manifest>

Usage

在 Android 上，地图在整个网络视图下呈现，并使用该组件在滚动事件期间管理其位置。这意味着，作为开发人员，您必须确保 Web 视图在所有层到最底层都是透明的。在典型的 Ionic 应用程序中，这意味着对 IonContent 和根 HTML 标记等元素设置透明度，以确保它可以被看到。如果你在 Android 上看不到你的地图，这应该是你检查的第一件事。

高德地图元素本身没有样式，所以你应该根据页面结构的布局对其进行样式设置。因为我们将视图渲染到这个槽中，所以元素本身没有宽度或高度，所以一定要明确设置这些宽度或高度。

<div id="map" class="capacitor-map"></div>

.capacitor-map {
  display: inline-block;
  width: 275px;
  height: 400px;
}

接下来，我们应该创建地图引用。这是通过从 Capacitor 插件导入 AMap 类并调用 create 方法，然后传入所需的参数来完成的。

import { AMap } from '@snewbie/capacitor-amap';

const mapRef = document.getElementById('map');

const newMap = await AMap.create({
  id: 'my-map', // Unique identifier for this map instance
  element: mapRef, // reference to the capacitor-amap element
  config: {

  }
});

完整示例

Vue

<template>
    <div id="map" ref="mapRef" :style="{ display: 'inline-block', width: '275px', height: '400px' }"></div>
</template>

<script setup lang="ts">
import { onIonViewWillEnter, onIonViewWillLeave } from '@ionic/vue';
import { onMounted, onUnmounted, ref } from 'vue';
import { AMap } from '@snewbie/capacitor-amap';

const mapRef = ref<HTMLElement | null>(null)
let newMap: Amap;

onMounted(async () => {
    if (!mapRef.value) { return; }

    newMap = await AMap.create({
        id: 'main',
        element: mapRef.value, 
        config: {
          
        }
    });
});

onIonViewWillEnter(async () => {
  newMap?.show()
  newMap?.enableTouch()
})

onIonViewWillLeave(async () => {
  newMap?.hide()
  newMap?.disableTouch()
})

onUnmounted(() => {
  newMap?.destroy()
})
</script>

离线地图 UI 组件

Activity 在 SDK 内部实现，仅需要在工程 AndroidManifest.xml 中配置 site.snewbie.plugins.amap.extend.OfflineMapActivity 即可

<activity android:name="site.snewbie.plugins.amap.extend.OfflineMapActivity" 
              android:screenOrientation="portrait"  />

<script setup lang="ts">
import { AMap } from '@snewbie/capacitor-amap';

await AMap.openOfflineMapActivity();
</script>

API

• getFromLocation(...)
• updatePrivacyShow(...)
• updatePrivacyAgree(...)
• setTerrainEnable(...)
• openOfflineMapActivity()
• create(...)
• showIndoorMap(...)
• setMapType(...)
• setTrafficEnabled(...)
• destroy()
• show()
• hide()
• enableTouch()
• disableTouch()
• enableMyLocation()
• disableMyLocation()
• setMyLocationStyle(...)
• setUiSettings(...)
• cameraUpdatePosition(...)
• cameraZoomTo(...)
• setMapStatusLimits(...)
• setOnCameraChangeListener(...)
• setOnIndoorBuildingActiveListener(...)
• setOnInfoWindowClickListener(...)
• setOnMapClickListener(...)
• setOnMapLoadedListener(...)
• setOnMapLongClickListener(...)
• setOnMapTouchListener(...)
• setOnMarkerClickListener(...)
• setOnMarkerDragListener(...)
• setOnMultiPointClickListener(...)
• setOnMyLocationChangeListener(...)
• setOnPOIClickListener(...)
• setOnPolylineClickListener(...)
• Interfaces
• Type Aliases
• Enums

高德地图 SDK 的 JavaScript 接口。

getFromLocation(...)

getFromLocation(args: GetFromLocationArgs) => Promise<{ code: number; address: any; }>

逆地理编码（坐标转地址）

Returns: Promise<{ code: number; address: any; }>

Since: 0.0.8

updatePrivacyShow(...)

updatePrivacyShow(isContains: boolean, isShow: boolean) => Promise<void>

更新隐私合规状态，需要在初始化地图之前完成。

Since: 0.0.2

updatePrivacyAgree(...)

updatePrivacyAgree(isAgree: boolean) => Promise<void>

更新同意隐私状态，需要在初始化地图之前完成。

Since: 0.0.2

setTerrainEnable(...)

setTerrainEnable(isTerrainEnable: boolean) => Promise<void>

是否打开地形图, 打开地形图之后，底图会变成3D模式，添加的点线面等覆盖物也会自动带有高程。注意：需要在MapView创建之前调用。

Since: 0.0.5

openOfflineMapActivity()

openOfflineMapActivity() => Promise<void>

启动离线地图组件。

Since: 0.0.7

create(...)

create(options: CreateMapArgs, callback?: MapListenerCallback<MapReadyCallbackData> | undefined) => Promise<AMap>

创建地图实例。

Returns: Promise<AMap>

Since: 0.0.1

showIndoorMap(...)

showIndoorMap(enable: boolean) => Promise<void>

设置是否显示室内地图，默认不显示。注：如果打开了室内地图，会显示3D建筑物，即如果之前有设置不显示3D建筑物，3D建筑物也会被显示出来。

Since: 0.0.5

setMapType(...)

setMapType(type: MapType) => Promise<void>

设置地图模式。

Since: 0.0.5

setTrafficEnabled(...)

setTrafficEnabled(enable: boolean) => Promise<void>

设置是否打开交通路况图层。

Since: 0.0.5

destroy()

destroy() => Promise<void>

销毁地图实例。

Since: 0.0.1

show()

show() => Promise<void>

显示地图。

Since: 0.0.7

hide()

hide() => Promise<void>

隐藏地图。

Since: 0.0.7

enableTouch()

enableTouch() => Promise<void>

设置地图允许被触控。

Since: 0.0.1

disableTouch()

disableTouch() => Promise<void>

设置地图禁止被触控。

Since: 0.0.1

enableMyLocation()

enableMyLocation() => Promise<void>

设置启动显示定位蓝点。

Since: 0.0.5

disableMyLocation()

disableMyLocation() => Promise<void>

设置隐藏定位蓝点并不进行定位。

Since: 0.0.5

setMyLocationStyle(...)

setMyLocationStyle(style: MyLocationStyle) => Promise<void>

设置定位蓝点的Style。

Since: 0.0.5

setUiSettings(...)

setUiSettings(args: UiSettings) => Promise<void>

设置地图内置UI及手势控制器。

Since: 0.0.5

cameraUpdatePosition(...)

cameraUpdatePosition(args: CameraPosition) => Promise<void>

给地图设置一个新的状态。

Since: 0.0.6

cameraZoomTo(...)

cameraZoomTo(zoom: Number) => Promise<void>

设置地图缩放级别。

Since: 0.0.6

setMapStatusLimits(...)

setMapStatusLimits(args: MapStatusLimits) => Promise<void>

设置地图显示范围，无论如何操作地图，显示区域都不能超过该矩形区域。

Since: 0.0.6

setOnCameraChangeListener(...)

setOnCameraChangeListener(callback?: MapListenerCallback<any> | undefined) => Promise<void>

设置地图状态的监听接口。

Since: 0.0.2

setOnIndoorBuildingActiveListener(...)

setOnIndoorBuildingActiveListener(callback?: MapListenerCallback<any> | undefined) => Promise<void>

设置室内地图状态监听接口。

Since: 0.0.2

setOnInfoWindowClickListener(...)

setOnInfoWindowClickListener(callback?: MapListenerCallback<any> | undefined) => Promise<void>

设置marker的信息窗口点击事件监听接口。

Since: 0.0.2

setOnMapClickListener(...)

setOnMapClickListener(callback?: MapListenerCallback<any> | undefined) => Promise<void>

设置地图点击事件监听接口。

Since: 0.0.2

setOnMapLoadedListener(...)

setOnMapLoadedListener(callback?: MapListenerCallback<any> | undefined) => Promise<void>

设置地图加载完成监听接口。

Since: 0.0.2

setOnMapLongClickListener(...)

setOnMapLongClickListener(callback?: MapListenerCallback<any> | undefined) => Promise<void>

设置地图长按事件监听接口。

Since: 0.0.2

setOnMapTouchListener(...)

setOnMapTouchListener(callback?: MapListenerCallback<any> | undefined) => Promise<void>

设置地图触摸事件监听接口。

Since: 0.0.2

setOnMarkerClickListener(...)

setOnMarkerClickListener(callback?: MapListenerCallback<any> | undefined) => Promise<void>

设置marker点击事件监听接口。

Since: 0.0.2

setOnMarkerDragListener(...)

setOnMarkerDragListener(callback?: MapListenerCallback<any> | undefined) => Promise<void>

marker拖动事件监听接口。

Since: 0.0.2

setOnMultiPointClickListener(...)

setOnMultiPointClickListener(callback?: MapListenerCallback<any> | undefined) => Promise<void>

设置海量点单击事件监听。

Since: 0..2

setOnMyLocationChangeListener(...)

setOnMyLocationChangeListener(callback?: MapListenerCallback<any> | undefined) => Promise<void>

设置用户定位信息监听接口。

Since: 0.0.2

setOnPOIClickListener(...)

setOnPOIClickListener(callback?: MapListenerCallback<any> | undefined) => Promise<void>

设置底图poi点击事件监听接口。

Since: 0.0.2

setOnPolylineClickListener(...)

setOnPolylineClickListener(callback?: MapListenerCallback<any> | undefined) => Promise<void>

设置polyline点击事件监听接口。

Since: 0.0.2

Interfaces

GetFromLocationArgs

LatLng

存储经纬度坐标值的类，单位角度。

CreateMapArgs

AMapConfig

CameraPosition

相机位置，这个类包含了所有的可视区域的位置参数。

MapReadyCallbackData

MyLocationStyle

UiSettings

地图内置UI及手势控制器。

Number

An object that represents a number of any kind. All JavaScript numbers are 64-bit floating-point numbers.

MapStatusLimits

通过指定的两个经纬度坐标（左下、右上）构建的一个矩形区域

Type Aliases

MapListenerCallback

The callback function to be called when map events are emitted.

(data: T): void

Enums

LogoPosition

MapType

MyLocationType