@snewbie/capacitor-amap

v0.0.10

Published

20 days ago

使用高德开放平台 Android 地图 SDK 开发的 Capacitor 插件（安卓端）。

Downloads

211

0High
0Medium
0Low

null_object_0000

capacitor plugin native

@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

高德地图 SDK 的 JavaScript 接口。

getFromLocation(...)

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

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

| Param | Type | | ---------- | ------------------------------------------------------------------- | | args | GetFromLocationArgs |

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

Since: 0.0.8

updatePrivacyShow(...)

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

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

| Param | Type | Description | | ---------------- | -------------------- | -------------------------- | | isContains | boolean | 隐私权政策是否包含高德开平隐私权政策 true是包含 | | isShow | boolean | 隐私权政策是否弹窗展示告知用户 true是展示 |

Since: 0.0.2

updatePrivacyAgree(...)

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

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

| Param | Type | Description | | ------------- | -------------------- | ----------------------- | | isAgree | boolean | 隐私权政策是否取得用户同意 true是用户同意 |

Since: 0.0.2

setTerrainEnable(...)

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

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

| Param | Type | Description | | --------------------- | -------------------- | --------------- | | isTerrainEnable | boolean | true为打开，默认false |

Since: 0.0.5

openOfflineMapActivity()

openOfflineMapActivity() => Promise<void>

启动离线地图组件。

Since: 0.0.7

create(...)

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

创建地图实例。

| Param | Type | Description | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------- | | options | CreateMapArgs | - 创建地图的参数。 | | callback | MapListenerCallback<MapReadyCallbackData> | |

Returns: Promise<AMap>

Since: 0.0.1

showIndoorMap(...)

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

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

| Param | Type | Description | | ------------ | -------------------- | --------------------- | | enable | boolean | true：显示室内地图；false：不显示 |

Since: 0.0.5

setMapType(...)

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

设置地图模式。

| Param | Type | | ---------- | ------------------------------------------- | | type | MapType |

Since: 0.0.5

setTrafficEnabled(...)

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

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

| Param | Type | Description | | ------------ | -------------------- | ----------- | | enable | boolean | 是否打开交通路况图层。 |

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。

| Param | Type | | ----------- | ----------------------------------------------------------- | | style | MyLocationStyle |

Since: 0.0.5

setUiSettings(...)

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

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

| Param | Type | | ---------- | ------------------------------------------------- | | args | UiSettings |

Since: 0.0.5

cameraUpdatePosition(...)

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

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

| Param | Type | Description | | ---------- | --------------------------------------------------------- | ----------- | | args | CameraPosition | 新的地图状态。 |

Since: 0.0.6

cameraZoomTo(...)

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

设置地图缩放级别。

| Param | Type | Description | | ---------- | ----------------------------------------- | ------------------------------------------------- | | zoom | Number | 地图缩放级别。地图的缩放级别一共分为 17 级，从 3 到 19。数字越大，展示的图面信息越精细。 |

Since: 0.0.6

setMapStatusLimits(...)

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

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

| Param | Type | | ---------- | ----------------------------------------------------------- | | args | MapStatusLimits |

Since: 0.0.6