跳到主要内容
版本：v4

@capacitor/google-maps

在 Capacitor 中使用 Google 地图

安装​

npm install @capacitor/google-maps
npx cap sync

API 密钥​

要在任何平台上使用 Google Maps SDK，都需要关联到已启用计费账户的 API 密钥。这些密钥可以从 Google Cloud Console 获取。Android、iOS 和 JavaScript 这三个平台都需要此步骤。关于如何获取这些 API 密钥的更多信息，可以在每个平台的 Google Maps 文档 中找到。

iOS​

Google Maps SDK 支持通过 enableCurrentLocation(bool) 显示用户的当前位置。要使用此功能，Apple 要求在 Info.plist 中指定隐私描述：

  • NSLocationAlwaysUsageDescription (隐私 - 始终使用位置)
  • NSLocationWhenInUseUsageDescription (隐私 - 使用时使用位置)

请阅读 iOS 指南 中的 配置 Info.plist 部分，了解更多关于在 Xcode 中设置 iOS 权限的信息。

目前，Google Maps SDK 不支持在使用新款 M1 芯片的 Macbook 上使用模拟器运行。这是一个 已知且已被确认的问题，需要 Google 方面提供修复。如果您正在使用 M1 Macbook 进行开发，仍然支持在物理设备上构建和运行，这也是推荐的做法。

Android​

适用于 Android 的 Google Maps SDK 要求您将 API 密钥添加到项目中的 AndroidManifest.xml 文件。

<meta-data android:name="com.google.android.geo.API_KEY" android:value="YOUR_API_KEY_HERE"/>

为了使用某些位置功能，SDK 还要求将以下权限添加到您的 AndroidManifest.xml：

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

变量​

此插件将使用以下项目变量（在您应用的 variables.gradle 文件中定义）：

  • $googleMapsPlayServicesVersion：com.google.android.gms:play-services-maps 版本（默认：18.0.2）
  • $googleMapsUtilsVersion：com.google.maps.android:android-maps-utils 版本（默认：2.3.0）
  • $googleMapsKtxVersion：com.google.maps.android:maps-ktx 版本（默认：3.4.0）
  • $googleMapsUtilsKtxVersion：com.google.maps.android:maps-utils-ktx 版本（默认：3.4.0）
  • $kotlinxCoroutinesVersion：org.jetbrains.kotlinx:kotlinx-coroutines-android 和 org.jetbrains.kotlinx:kotlinx-coroutines-core 版本（默认：1.6.3）
  • $androidxCoreKTXVersion：androidx.core:core-ktx 版本（默认：1.8.0）
  • $kotlin_version：org.jetbrains.kotlin:kotlin-stdlib-jdk7 版本（默认：1.7.0）

使用​

Google Maps Capacitor 插件附带了一个 Web 组件，必须在您的应用程序中使用它来渲染地图，因为它使我们能够在 iOS 上更有效地嵌入原生视图。该插件会自动注册此 Web 组件供您的应用程序使用。

对于 Angular 用户，您会收到一个错误警告，提示 Angular 编译器不知道此 Web 组件。这可以通过修改声明组件的模块以允许自定义 Web 组件来解决。

import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})

在您的 HTML 中包含此组件，并为其分配一个 ID，以便稍后轻松查询该元素引用。

<capacitor-google-map id="map"></capacitor-google-map>

在 Android 上，地图是在整个 WebView 下方渲染的，并利用此组件在滚动事件期间管理其定位。这意味着作为开发者，您必须确保 WebView 从上到下的所有层都是透明的。在典型的 Ionic 应用中，这需要为 IonContent 和根 HTML 标签等元素设置透明属性，以确保地图可见。如果您在 Android 上看不到地图，这应该是您首先检查的地方。

在 iOS 上，我们将地图直接渲染到 WebView 中，因此不需要相同的透明效果。我们仍在研究 Android 上的替代方法，并希望在未来的更新中更好地解决这个问题。

Google Map 元素本身没有样式，因此您应该为其设置样式以适配页面布局。由于我们正在向此插槽渲染视图，该元素本身没有宽度或高度，所以请务必显式设置这些属性。

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

接下来，我们应该创建地图引用。这需要从 Capacitor 插件导入 GoogleMap 类并调用 create 方法，同时传入所需的参数。

import { GoogleMap } from '@capacitor/google-maps';

const apiKey = 'YOUR_API_KEY_HERE';

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

const newMap = await GoogleMap.create({
  id: 'my-map', // 此地图实例的唯一标识符
  element: mapRef, // 对 capacitor-google-map 元素的引用
  apiKey: apiKey, // 您的 Google Maps API 密钥
  config: {
    center: {
      // 地图初始渲染的位置
      lat: 33.6,
      lng: -117.9,
    },
    zoom: 8, // 地图初始渲染的缩放级别
  },
});

至此，您的地图应该在应用程序中创建完成。使用返回的地图引用，您可以通过多种方式轻松与地图交互，这里展示了其中几种。

const newMap = await GoogleMap.create({...});

// 向地图添加标记
const markerId = await newMap.addMarker({
  coordinate: {
    lat: 33.6,
    lng: -117.9
  }
});

// 以编程方式移动地图
await newMap.setCamera({
  coordinate: {
    lat: 33.6,
    lng: -117.9
  }
});

// 启用标记聚类
await newMap.enableClustering();

// 处理标记点击事件
await newMap.setOnMarkerClickListener((event) => {...});

// 清理地图引用
await newMap.destroy();

完整示例​

Angular​

import { GoogleMap } from '@capacitor/google-maps';

@Component({
  template: `
    <capacitor-google-map #map></capacitor-google-map>
    <button (click)="createMap()">创建地图</button>
  `,
  styles: [
    `
      capacitor-google-map {
        display: inline-block;
        width: 275px;
        height: 400px;
      }
    `,
  ],
})
export class MyMap {
  @ViewChild('map')
  mapRef: ElementRef<HTMLElement>;
  newMap: GoogleMap;

  async createMap() {
    this.newMap = await GoogleMap.create({
      id: 'my-cool-map',
      element: this.mapRef.nativeElement,
      apiKey: environment.apiKey,
      config: {
        center: {
          lat: 33.6,
          lng: -117.9,
        },
        zoom: 8,
      },
    });
  }
}
```### React

```jsx
import { GoogleMap } from '@capacitor/google-maps';
import { useRef } from 'react';

const MyMap: React.FC = () => {
  const mapRef = useRef<HTMLElement>();
  let newMap: GoogleMap;

  async function createMap() {
    if (!mapRef.current) return;

    newMap = await GoogleMap.create({
      id: 'my-cool-map',
      element: mapRef.current,
      apiKey: process.env.REACT_APP_YOUR_API_KEY_HERE,
      config: {
        center: {
          lat: 33.6,
          lng: -117.9
        },
        zoom: 8
      }
    })
  }

  return (
    <div className="component-wrapper">
      <capacitor-google-map ref={mapRef} style={{
        display: 'inline-block',
        width: 275,
        height: 400
      }}></capacitor-google-map>

      <button onClick={createMap}>创建地图</button>
    </div>
  )
}

export default MyMap;

JavaScript​

<capacitor-google-map id="map"></capacitor-google-map>
<button onclick="createMap()">创建地图</button>

<style>
  capacitor-google-map {
    display: inline-block;
    width: 275px;
    height: 400px;
  }
</style>

<script>
  import { GoogleMap } from '@capacitor/google-maps';

  const createMap = async () => {
    const mapRef = document.getElementById('map');

    const newMap = await GoogleMap.create({
      id: 'my-map', // 此地图实例的唯一标识符
      element: mapRef, // 对 capacitor-google-map 元素的引用
      apiKey: 'YOUR_API_KEY_HERE', // 你的 Google Maps API 密钥
      config: {
        center: {
          // 地图初始渲染的位置
          lat: 33.6,
          lng: -117.9,
        },
        zoom: 8, // 地图初始渲染的缩放级别
      },
    });
  };
</script>

API​

create(...)​

create(options: CreateMapArgs, callback?: MapListenerCallback<MapReadyCallbackData> | undefined) => Promise<GoogleMap>
参数类型
options
CreateMapArgs
callback
MapListenerCallback<MapReadyCallbackData>

返回值: Promise<GoogleMap>

enableClustering(...)​

enableClustering(minClusterSize?: number | undefined) => Promise<void>
参数类型描述
minClusterSizenumber可以聚合在一起的标记的最小数量。默认为 4 个标记。

disableClustering()​

disableClustering() => Promise<void>

addMarker(...)​

addMarker(marker: Marker) => Promise<string>
参数类型
marker
Marker

返回值: Promise<string>

addMarkers(...)​

addMarkers(markers: Marker[]) => Promise<string[]>
参数类型
markersMarker[]

返回值: Promise<string[]>

removeMarker(...)​

removeMarker(id: string) => Promise<void>
参数类型
idstring

removeMarkers(...)​

removeMarkers(ids: string[]) => Promise<void>
参数类型
idsstring[]

destroy()​

destroy() => Promise<void>

setCamera(...)​

setCamera(config: CameraConfig) => Promise<void>
参数类型
config
CameraConfig

getMapType()​

getMapType() => Promise<MapType>

获取当前地图类型

返回值: 

Promise<MapType>

setMapType(...)​

setMapType(mapType: MapType) => Promise<void>
参数类型
mapType
MapType

enableIndoorMaps(...)​

enableIndoorMaps(enabled: boolean) => Promise<void>
参数类型
enabledboolean

--------------------### enableTrafficLayer(...)

enableTrafficLayer(enabled: boolean) => Promise<void>
参数类型
enabledboolean

enableAccessibilityElements(...)​

enableAccessibilityElements(enabled: boolean) => Promise<void>
参数类型
enabledboolean

enableCurrentLocation(...)​

enableCurrentLocation(enabled: boolean) => Promise<void>
参数类型
enabledboolean

setPadding(...)​

setPadding(padding: MapPadding) => Promise<void>
参数类型
padding
MapPadding

setOnBoundsChangedListener(...)​

setOnBoundsChangedListener(callback?: MapListenerCallback<CameraIdleCallbackData> | undefined) => Promise<void>
参数类型
callback
MapListenerCallback<CameraIdleCallbackData>

setOnCameraIdleListener(...)​

setOnCameraIdleListener(callback?: MapListenerCallback<CameraIdleCallbackData> | undefined) => Promise<void>
参数类型
callback
MapListenerCallback<CameraIdleCallbackData>

setOnCameraMoveStartedListener(...)​

setOnCameraMoveStartedListener(callback?: MapListenerCallback<CameraMoveStartedCallbackData> | undefined) => Promise<void>
参数类型
callback
MapListenerCallback<CameraMoveStartedCallbackData>

setOnClusterClickListener(...)​

setOnClusterClickListener(callback?: MapListenerCallback<ClusterClickCallbackData> | undefined) => Promise<void>
参数类型
callback
MapListenerCallback<ClusterClickCallbackData>

setOnClusterInfoWindowClickListener(...)​

setOnClusterInfoWindowClickListener(callback?: MapListenerCallback<ClusterClickCallbackData> | undefined) => Promise<void>
参数类型
callback
MapListenerCallback<ClusterClickCallbackData>

setOnInfoWindowClickListener(...)​

setOnInfoWindowClickListener(callback?: MapListenerCallback<MarkerClickCallbackData> | undefined) => Promise<void>
参数类型
callback
MapListenerCallback<MarkerClickCallbackData>

setOnMapClickListener(...)​

setOnMapClickListener(callback?: MapListenerCallback<MapClickCallbackData> | undefined) => Promise<void>
参数类型
callback
MapListenerCallback<MapClickCallbackData>

setOnMarkerClickListener(...)​

setOnMarkerClickListener(callback?: MapListenerCallback<MarkerClickCallbackData> | undefined) => Promise<void>
参数类型
callback
MapListenerCallback<MarkerClickCallbackData>

--------------------### setOnMarkerDragStartListener(...)

setOnMarkerDragStartListener(callback?: MapListenerCallback<MarkerClickCallbackData> | undefined) => Promise<void>
参数类型
callback
MapListenerCallback<MarkerClickCallbackData>

setOnMarkerDragListener(...)​

setOnMarkerDragListener(callback?: MapListenerCallback<MarkerClickCallbackData> | undefined) => Promise<void>
参数类型
callback
MapListenerCallback<MarkerClickCallbackData>

setOnMarkerDragEndListener(...)​

setOnMarkerDragEndListener(callback?: MapListenerCallback<MarkerClickCallbackData> | undefined) => Promise<void>
参数类型
callback
MapListenerCallback<MarkerClickCallbackData>

setOnMyLocationButtonClickListener(...)​

setOnMyLocationButtonClickListener(callback?: MapListenerCallback<MyLocationButtonClickCallbackData> | undefined) => Promise<void>
参数类型
callback
MapListenerCallback<MyLocationButtonClickCallbackData>

setOnMyLocationClickListener(...)​

setOnMyLocationClickListener(callback?: MapListenerCallback<MapClickCallbackData> | undefined) => Promise<void>
参数类型
callback
MapListenerCallback<MapClickCallbackData>

接口​

CreateMapArgs​

一个接口，包含创建地图时使用的选项。

属性类型描述默认值
idstring地图实例的唯一标识符。
apiKeystringGoogle Maps SDK API 密钥。
config
GoogleMapConfig
地图的初始配置设置。
elementHTMLElement用于挂载 Google Map 视图的 DOM 元素，它决定了地图的大小和位置。
forceCreateboolean如果提供的 id 已存在对应的地图实例，是否强制销毁并重新创建它。false

在 Web 平台上，所有 JavaScript Google Maps 选项均可用，因为 GoogleMapConfig 继承了 google.maps.MapOptions。 在 iOS 和 Android 平台上，只有 GoogleMapConfig 中声明的配置选项可用。

属性类型描述默认值始于
widthnumber覆盖原生地图的宽度。
heightnumber覆盖原生地图的高度。
xnumber覆盖原生地图的绝对 X 坐标位置。
ynumber覆盖原生地图的绝对 Y 坐标位置。
center
LatLng
相机默认指向的地球位置。
zoomnumber设置地图的缩放级别。
androidLiteModeboolean在 Android 上启用基于图像的轻量模式。false
devicePixelRationumber覆盖原生地图的像素比。
stylesMapTypeStyle[] | null应用于每种默认地图类型的样式。请注意，对于卫星、混合和地形模式，这些样式仅适用于标签和几何图形。4.3.0

LatLng​

一个表示纬度和经度坐标对的接口。

属性类型描述
latnumber纬度坐标，以度为单位。该值在 [-90, 90] 范围内。
lngnumber经度坐标，以度为单位。该值在 [-180, 180] 范围内。

MapReadyCallbackData​

属性类型
mapIdstring

标记点是放置在地图表面特定位置的图标。

属性类型描述默认值引入版本
coordinate
LatLng
标记点的位置
opacitynumber设置标记点的不透明度，取值范围为 0（完全透明）到 1（完全不透明）。1
titlestring标题，即叠加层的简短描述。
snippetstring片段文本，在选中标记点时显示在信息窗口的标题下方。
isFlatboolean控制此标记点是平贴于地球表面，还是作为面向相机的广告牌显示。false
iconUrlstring要渲染的标记点图标的路径。可以是相对于 Web 应用公共目录的路径，也可以是远程图标资源的 https URL。注意：SVG 格式在原生平台上不受支持。4.2.0
iconSize
Size
控制通过 iconUrl 设置的标记点图像缩放后的大小。4.2.0
iconOrigin
Point
图像在精灵图（如果存在）中的位置。默认情况下，原点位于图像的左上角。4.2.0
iconAnchor
Point
图像相对于标记点在地图上的位置的锚点位置。默认情况下，锚点位于图像底边的中心点。4.2.0
tintColor{ r: number; g: number; b: number; a: number; }自定义默认标记点图像的颜色。每个值必须在 0 到 255 之间。仅适用于 iOS 和 Android。4.2.0
draggableboolean控制此标记点是否可以通过交互拖动。false

尺寸​

属性类型
widthnumber
heightnumber

点​

点几何对象。 https://tools.ietf.org/html/rfc7946#section-3.1.2

属性类型描述
type
'Point'
指定 GeoJSON 对象的类型。
coordinates
Position

相机配置​

Google 地图相机的配置属性

属性类型描述默认值
coordinate
LatLng
相机指向的地球上的位置。
zoomnumber设置地图的缩放级别。
bearingnumber相机的方位角，以真北为基准顺时针方向的度数。0
anglenumber相机与天底（垂直向下指向地球）之间的角度（单位：度）。唯一允许的值为 0 和 45。0
animateboolean是否以动画形式过渡到新的相机属性。false
animationDurationnumber此配置选项当前未使用。

地图内边距​

用于设置视图“可见”区域的内边距控制项。

属性类型
topnumber
leftnumber
rightnumber
bottomnumber

相机空闲回调数据​

属性类型
mapIdstring
boundsLatLngBounds
bearingnumber
latitudenumber
longitudenumber
tiltnumber
zoomnumber

相机移动开始回调数据​

属性类型
mapIdstring
isGestureboolean
属性类型
mapIdstring
latitudenumber
longitudenumber
sizenumber
itemsMarkerCallbackData[]

MarkerCallbackData​

属性类型
markerIdstring
latitudenumber
longitudenumber
titlestring
snippetstring

MarkerClickCallbackData​

属性类型
mapIdstring

MapClickCallbackData​

属性类型
mapIdstring
latitudenumber
longitudenumber

MyLocationButtonClickCallbackData​

属性类型
mapIdstring

类型别名​

MapListenerCallback​

当地图事件触发时调用的回调函数。

(data: T): void

Position​

Position 是一个坐标数组。 https://tools.ietf.org/html/rfc7946#section-3.1.1 数组应包含两到三个元素。 之前的 GeoJSON 规范允许更多元素（例如，可以用来表示 M 值）， 但当前规范仅允许定义 X、Y 和（可选）Z。

number[]

枚举​

MapType​

成员值描述
Normal'Normal'基础地图。
Hybrid'Hybrid'卫星影像叠加道路和标签。
Satellite'Satellite'无标签的卫星影像。
Terrain'Terrain'地形数据。
None'None'无底图瓦片。

Contents

编辑此页