# @capacitor/google-maps 中文文档

规范地址：https://npmcn.com/package/%40capacitor/google-maps/

版本：8\.0\.1
npm 元数据更新时间：2026-09-28T18:17:25.570Z
中文译文更新时间：2026-11-09T02:25:27.826Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capacitor/google-maps
原文对照：https://npmcn.com/package/%40capacitor/google-maps/?lang=original
项目主页：https://github.com/ionic-team/capacitor-google-maps#readme
源码仓库：https://github.com/ionic-team/capacitor-google-maps

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：878 kB，59 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2022-04-06T22:13:06.189Z
- 最新版本发布：2026-02-11T18:41:34.957Z
- 近 30 天下载量：126324（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：443（近 12 个月 4 个）

## 中文简介

Capacitor 上的 Google 地图

## 安装

```sh
npm install @capacitor/google-maps
```

也可以使用：`pnpm add @capacitor/google-maps`、`yarn add @capacitor/google-maps`、`bun add @capacitor/google-maps`

## README

# @ capacor/ google- maps

Capacitor 上的 Google 地图

## 安装

```bash
npm install @capacitor/google-maps
npx cap sync
```

## API 密钥

要在任意平台上使用 Google Maps SDK, 与账户相关的 API 密钥 _启用计费_ 需要这样做。 这些都可以从下列来源获得: [谷歌云控台](https://console.cloud.google.com/)。所有三个平台,Android、iOS和Javascript都需要这样做。 关于获取这些 API 密钥的更多信息,请访问 [Google 地图文档](https://developers.google.com/maps/documentation/android-sdk/overview) 每个平台.

## iOS系统

Google Maps SDK 支持通过 `enableCurrentLocation(bool)`。要使用此功能,苹果公司需要指定隐私描述 `Info.plist`数字 :

-   `NSLocationWhenInUseUsageDescription` (单位:千美元)`Privacy - Location When In Use Usage Description`(中文(简体) )

阅读 [配置 `Info.plist`](https://capacitorjs.com/docs/ios/configuration#configuring-infoplist) 输入 [iOS 指南](https://capacitorjs.com/docs/ios) 在 Xcode 中设置 iOS 权限的更多信息.

### 键入符配置

你的项目也需要 `skipLibCheck` 设置为 `true` 内 `tsconfig.json`。 。 。 .

### 从旧版本迁移

> Google Maps SDK主要支持在苹果硅Macs上的模拟器上运行,但要确保您有最新版本的 [谷歌- 马普斯- iOS- Utils](https://github.com/googlemaps/google-maps-ios-utils) 已安装.

如果您为获得未发行版本添加了先前的工作环路, 您可以删除此行 `ios/App/Podfile`数字 :

```
pod 'Google-Maps-iOS-Utils', :git => 'https://github.com/googlemaps/google-maps-ios-utils.git', :commit => '637954e5bcb2a879c11a6f2cead153a6bad5339f'
```

然后运行 `pod update Google-Maps-iOS-Utils` 从 `ios/App/` 文件夹 :

```
cd ios/App
pod update Google-Maps-iOS-Utils
```

## 机器人

Android的Google Maps SDK需要您将您的API密钥添加到您的项目中的AndroidManifest.xml文件中.

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

要使用某些位置特性, SDK 需要以下权限才能添加到您的 AndroidManifest.xml 中:

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

### 变量

此插件将使用以下工程变量( 在您的应用程序中定义) `variables.gradle` 文件名 :

-   `googleMapsPlayServicesVersion`页:1 `com.google.android.gms:play-services-maps` (默认 : `19.2.0`(中文(简体) )
-   `googleMapsUtilsVersion`页:1 `com.google.maps.android:android-maps-utils` (默认 : `3.19.1`(中文(简体) )
-   `googleMapsKtxVersion`页:1 `com.google.maps.android:maps-ktx` (默认 : `5.2.1`(中文(简体) )
-   `googleMapsUtilsKtxVersion`页:1 `com.google.maps.android:maps-utils-ktx` (默认 : `5.2.1`(中文(简体) )
-   `kotlinxCoroutinesVersion`页:1 `org.jetbrains.kotlinx:kotlinx-coroutines-android` 财务报告和审定财务报表 `org.jetbrains.kotlinx:kotlinx-coroutines-core` (默认 : `1.10.2`(中文(简体) )
-   `androidxCoreKTXVersion`页:1 `androidx.core:core-ktx` (默认 : `1.17.0`(中文(简体) )
-   `kotlin_version`页:1 `org.jetbrains.kotlin:kotlin-stdlib` (默认 : `2.2.20`(中文(简体) )

## 使用量

Google Maps Capacitor 插件船, 带有网络组件, 必须用于在您的应用程序中渲染地图, 因为它使我们能够更有效地将本地视图嵌入到 iOS 上 。 插件将自动注册此网页组件供您在应用程序中使用 .

> 对于角用户,您会得到一个错误警告,这个网络组件对于角编译器来说是未知的. 通过修改宣布您组件的模块以允许自定义的网络组件来解决这个问题.
> 
> ```typescript
> import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
> 
> @NgModule({
>   schemas: [CUSTOM_ELEMENTS_SCHEMA]
> })
> ```

在您的 HTML 中包含此组件, 并指定一个ID, 以便您以后可以轻松查询该元素引用 .

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

> 在Android上,地图会在整个网页视图下渲染出,并在滚动事件期间使用此组件来管理其定位. 这意味着作为开发者,你 _必须_ 确保网页视图的透明性贯穿各层至最下层。 在一个典型的Ionic应用中,这意味着在IonContent和根 HTML标签等元素上设定透明度,以确保可以看到. 如果你在Android上看不到地图,这应该是你检查的第一件事.
> 
> 在iOS上,我们直接将地图放入网页视图,因此不需要同样的透明度效果. 我们正在调查Android的替代方法,希望在未来更新中能更好地解决这个问题.

Google Map 元素本身没有风格化,所以您应该将其风格化以适应您页面结构的布局. 因为我们把一个视图放进这个槽里, 元素本身没有宽度或高度, 所以请明确设置这些.

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

接下来,我们应该创建地图参考。 其方法是从Capacitor插件中导入GoogleMap类,并调用创建方法,并传入需要的参数.

```typescript
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', // Unique identifier for this map instance
  element: mapRef, // reference to the capacitor-google-map element
  apiKey: apiKey, // Your Google Maps API Key
  config: {
    center: {
      // The initial position to be rendered by the map
      lat: 33.6,
      lng: -117.9,
    },
    zoom: 8, // The initial zoom level to be rendered by the map
  },
});
```

此时, 您的地图应该在您的应用中创建 。 使用返回到地图的引用,您可以轻松地以多种方式与您的地图交互,其中的几个在这里显示.

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

// Add a marker to the map
const markerId = await newMap.addMarker({
  coordinate: {
    lat: 33.6,
    lng: -117.9
  }
});

// Move the map programmatically
await newMap.setCamera({
  coordinate: {
    lat: 33.6,
    lng: -117.9
  }
});

// Enable marker clustering
await newMap.enableClustering();

// Handle marker click
await newMap.setOnMarkerClickListener((event) => {...});

// Clean up map reference
await newMap.destroy();
```

## 完整示例

### 角质

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

@Component({
  template: `
    <capacitor-google-map #map></capacitor-google-map>
    <button (click)="createMap()">Create Map</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,
      },
    });
  }
}
```

### 反应

```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}>Create Map</button>
    </div>
  )
}

export default MyMap;
```

您可能需要创建一个 `*.d.ts` react 中自定义元素的文件 :

```ts
// custom-elements.d.ts

declare module "react" {
  namespace JSX {
    interface IntrinsicElements {
      "capacitor-google-map": React.DetailedHTMLProps<
        React.HTMLAttributes<HTMLElement>,
        HTMLElement
      >;
    }
  }
}

export {};
```

### 阴道

```vue
<script lang="ts" setup>
import { ref, shallowRef, useTemplateRef } from 'vue'
import { GoogleMap } from '@capacitor/google-maps'

const mapRef = useTemplateRef<HTMLElement>('mapRef')
const newMap = shallowRef<GoogleMap>()

async function createMap() {
  if (!mapRef.value) return

  newMap.value = await GoogleMap.create({
    id: 'my-cool-map',
    element: mapRef.value,
    apiKey: import.meta.env.VITE_YOUR_API_KEY_HERE,
    config: {
      center: {
        lat: 33.6,
        lng: -117.9,
      },
      zoom: 8,
    },
  })
}
</script>

<template>
  <capacitor-google-map
    ref="mapRef"
    style="display: inline-block; width: 275px; height: 400px"
  ></capacitor-google-map>
  <button @click="createMap()">Create Map</button>
</template>

```

确保您需要启用 [承认本地习惯元素](https://vuejs.org/guide/extras/web-components.html#using-custom-elements-in-vue) 喜欢

```ts
// vite.config.mts > plugins
Vue({
  template: {
    compilerOptions: {
      isCustomElement: (tag) => tag.startsWith('capacitor-')
    },
  },
}),
```

### Javascript

```html
<capacitor-google-map id="map"></capacitor-google-map>
<button onclick="createMap()">Create Map</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', // Unique identifier for this map instance
      element: mapRef, // reference to the capacitor-google-map element
      apiKey: 'YOUR_API_KEY_HERE', // Your Google Maps API Key
      config: {
        center: {
          // The initial position to be rendered by the map
          lat: 33.6,
          lng: -117.9,
        },
        zoom: 8, // The initial zoom level to be rendered by the map
      },
    });
  };
</script>
```

## API 密码

-   [`create(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-create)
-   [`enableTouch()`](https://npmcn.com/package/%40capacitor/google-maps/#readme-enabletouch)
-   [`disableTouch()`](https://npmcn.com/package/%40capacitor/google-maps/#readme-disabletouch)
-   [`enableClustering(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-enableclustering)
-   [`disableClustering()`](https://npmcn.com/package/%40capacitor/google-maps/#readme-disableclustering)
-   [`addTileOverlay(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-addtileoverlay)
-   [`removeTileOverlay(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-removetileoverlay)
-   [`addMarker(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-addmarker)
-   [`addMarkers(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-addmarkers)
-   [`removeMarker(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-removemarker)
-   [`removeMarkers(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-removemarkers)
-   [`addPolygons(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-addpolygons)
-   [`removePolygons(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-removepolygons)
-   [`addCircles(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-addcircles)
-   [`removeCircles(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-removecircles)
-   [`addPolylines(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-addpolylines)
-   [`removePolylines(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-removepolylines)
-   [`destroy()`](https://npmcn.com/package/%40capacitor/google-maps/#readme-destroy)
-   [`setCamera(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-setcamera)
-   [`getMapType()`](https://npmcn.com/package/%40capacitor/google-maps/#readme-getmaptype)
-   [`setMapType(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-setmaptype)
-   [`enableIndoorMaps(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-enableindoormaps)
-   [`enableTrafficLayer(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-enabletrafficlayer)
-   [`enableAccessibilityElements(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-enableaccessibilityelements)
-   [`enableCurrentLocation(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-enablecurrentlocation)
-   [`setPadding(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-setpadding)
-   [`getMapBounds()`](https://npmcn.com/package/%40capacitor/google-maps/#readme-getmapbounds)
-   [`fitBounds(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-fitbounds)
-   [`setOnBoundsChangedListener(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-setonboundschangedlistener)
-   [`setOnCameraIdleListener(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-setoncameraidlelistener)
-   [`setOnCameraMoveStartedListener(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-setoncameramovestartedlistener)
-   [`setOnClusterClickListener(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-setonclusterclicklistener)
-   [`setOnClusterInfoWindowClickListener(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-setonclusterinfowindowclicklistener)
-   [`setOnInfoWindowClickListener(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-setoninfowindowclicklistener)
-   [`setOnMapClickListener(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-setonmapclicklistener)
-   [`setOnMarkerClickListener(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-setonmarkerclicklistener)
-   [`setOnPolygonClickListener(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-setonpolygonclicklistener)
-   [`setOnCircleClickListener(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-setoncircleclicklistener)
-   [`setOnPolylineClickListener(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-setonpolylineclicklistener)
-   [`setOnMarkerDragStartListener(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-setonmarkerdragstartlistener)
-   [`setOnMarkerDragListener(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-setonmarkerdraglistener)
-   [`setOnMarkerDragEndListener(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-setonmarkerdragendlistener)
-   [`setOnMyLocationButtonClickListener(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-setonmylocationbuttonclicklistener)
-   [`setOnMyLocationClickListener(...)`](https://npmcn.com/package/%40capacitor/google-maps/#readme-setonmylocationclicklistener)
-   [接口](https://npmcn.com/package/%40capacitor/google-maps/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capacitor/google-maps/#readme-type-aliases)
-   [数字](https://npmcn.com/package/%40capacitor/google-maps/#readme-enums)

### 创建(...)

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

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[CreateMapArgs](https://npmcn.com/package/%40capacitor/google-maps/#readme-createmapargs)` |
| **`callback`** | `[MapListenerCallback](https://npmcn.com/package/%40capacitor/google-maps/#readme-maplistenercallback)<[MapReadyCallbackData](https://npmcn.com/package/%40capacitor/google-maps/#readme-mapreadycallbackdata)>` |

**回返情况:** `Promise<GoogleMap>`

* * *

### 启用Touch( )

```typescript
enableTouch() => Promise<void>
```

* * *

### 禁用Touch( )

```typescript
disableTouch() => Promise<void>
```

* * *

### 启用组合(...)

```typescript
enableClustering(minClusterSize?: number | undefined) => Promise<void>
```

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`minClusterSize`** | `number` | 可组合在一起的最小标记数量. 默认为4个标记. |

* * *

### 禁用分类( C)

```typescript
disableClustering() => Promise<void>
```

* * *

### 添加 Tile 覆盖(...)

```typescript
addTileOverlay(tileOverlay: TileOverlay) => Promise<{ id: string; }>
```

| 参数 | 类型 |
| --- | --- |
| **`tileOverlay`** | `[TileOverlay](https://npmcn.com/package/%40capacitor/google-maps/#readme-tileoverlay)` |

**回返情况:** `Promise<{ id: string; }>`

* * *

### 删除 Tile 覆盖(...)

```typescript
removeTileOverlay(id: string) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`id`** | `string` |

* * *

### 添加马克(...)

```typescript
addMarker(marker: Marker) => Promise<string>
```

| 参数 | 类型 |
| --- | --- |
| **`marker`** | `[Marker](https://npmcn.com/package/%40capacitor/google-maps/#readme-marker)` |

**回返情况:** `Promise<string>`

* * *

### 添加马克(...)

```typescript
addMarkers(markers: Marker[]) => Promise<string[]>
```

| 参数 | 类型 |
| --- | --- |
| **`markers`** | `Marker[]` |

**回返情况:** `Promise<string[]>`

* * *

### 删除马克(...)

```typescript
removeMarker(id: string) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`id`** | `string` |

* * *

### 删除马克(...)

```typescript
removeMarkers(ids: string[]) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`ids`** | `string[]` |

* * *

### 添加波利贡斯(...)

```typescript
addPolygons(polygons: Polygon[]) => Promise<string[]>
```

| 参数 | 类型 |
| --- | --- |
| **`polygons`** | `Polygon[]` |

**回返情况:** `Promise<string[]>`

* * *

### 删除波利贡斯(...)

```typescript
removePolygons(ids: string[]) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`ids`** | `string[]` |

* * *

### 添加循环(...)

```typescript
addCircles(circles: Circle[]) => Promise<string[]>
```

| 参数 | 类型 |
| --- | --- |
| **`circles`** | `Circle[]` |

**回返情况:** `Promise<string[]>`

* * *

### 删除圆环(...)

```typescript
removeCircles(ids: string[]) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`ids`** | `string[]` |

* * *

### 添加 Polylines (...)

```typescript
addPolylines(polylines: Polyline[]) => Promise<string[]>
```

| 参数 | 类型 |
| --- | --- |
| **`polylines`** | `Polyline[]` |

**回返情况:** `Promise<string[]>`

* * *

### 删除 Polylines (...)

```typescript
removePolylines(ids: string[]) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`ids`** | `string[]` |

* * *

### 销毁()

```typescript
destroy() => Promise<void>
```

* * *

### 设置 Camera (...)

```typescript
setCamera(config: CameraConfig) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`config`** | `[CameraConfig](https://npmcn.com/package/%40capacitor/google-maps/#readme-cameraconfig)` |

* * *

### 获取MapType ()

```typescript
getMapType() => Promise<MapType>
```

获取当前映射类型

**回返情况:** `Promise<[MapType](https://npmcn.com/package/%40capacitor/google-maps/#readme-maptype)>`

* * *

### 设置MapType(...)

```typescript
setMapType(mapType: MapType) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`mapType`** | `[MapType](https://npmcn.com/package/%40capacitor/google-maps/#readme-maptype)` |

* * *

### 启用室内地图(...)

```typescript
enableIndoorMaps(enabled: boolean) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`enabled`** | `boolean` |

* * *

### 启用 TrafficLayer (...)

```typescript
enableTrafficLayer(enabled: boolean) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`enabled`** | `boolean` |

* * *

### 启用可获取性元素(...)

```typescript
enableAccessibilityElements(enabled: boolean) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`enabled`** | `boolean` |

* * *

### 启用当前位置(...)

```typescript
enableCurrentLocation(enabled: boolean) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`enabled`** | `boolean` |

* * *

### 设定板(...)

```typescript
setPadding(padding: MapPadding) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`padding`** | `[MapPadding](https://npmcn.com/package/%40capacitor/google-maps/#readme-mappadding)` |

* * *

### 获取地图框( )

```typescript
getMapBounds() => Promise<LatLngBounds>
```

获取地图当前取景口纬度和经度界限.

**回返情况:** `Promise<LatLngBounds>`

* * *

### 适界(...)

```typescript
fitBounds(bounds: LatLngBounds, padding?: number | undefined) => Promise<void>
```

设置地图视图端口以包含给定的界限.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`bounds`** | `LatLngBounds` | 入取地相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相. |
| **`padding`** | `number` | 以像素形式应用的可选标签 。 界限将适合被删除后留在地图上的部分. |

* * *

### 设置于 BundsChanged listener (...)

```typescript
setOnBoundsChangedListener(callback?: MapListenerCallback<CameraIdleCallbackData> | undefined) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`callback`** | `[MapListenerCallback](https://npmcn.com/package/%40capacitor/google-maps/#readme-maplistenercallback)<[CameraIdleCallbackData](https://npmcn.com/package/%40capacitor/google-maps/#readme-cameraidlecallbackdata)>` |

* * *

### 设置为 Cameraidle 聆听器(...)

```typescript
setOnCameraIdleListener(callback?: MapListenerCallback<CameraIdleCallbackData> | undefined) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`callback`** | `[MapListenerCallback](https://npmcn.com/package/%40capacitor/google-maps/#readme-maplistenercallback)<[CameraIdleCallbackData](https://npmcn.com/package/%40capacitor/google-maps/#readme-cameraidlecallbackdata)>` |

* * *

### 设置为 OnCamera Move Started listener (...)

```typescript
setOnCameraMoveStartedListener(callback?: MapListenerCallback<CameraMoveStartedCallbackData> | undefined) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`callback`** | `[MapListenerCallback](https://npmcn.com/package/%40capacitor/google-maps/#readme-maplistenercallback)<[CameraMoveStartedCallbackData](https://npmcn.com/package/%40capacitor/google-maps/#readme-cameramovestartedcallbackdata)>` |

* * *

### 设置在 ClusterClick 听器(...)

```typescript
setOnClusterClickListener(callback?: MapListenerCallback<ClusterClickCallbackData> | undefined) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`callback`** | `[MapListenerCallback](https://npmcn.com/package/%40capacitor/google-maps/#readme-maplistenercallback)<[ClusterClickCallbackData](https://npmcn.com/package/%40capacitor/google-maps/#readme-clusterclickcallbackdata)>` |

* * *

### 设置于 ClusterInfoWindowClick 听取器(...)

```typescript
setOnClusterInfoWindowClickListener(callback?: MapListenerCallback<ClusterClickCallbackData> | undefined) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`callback`** | `[MapListenerCallback](https://npmcn.com/package/%40capacitor/google-maps/#readme-maplistenercallback)<[ClusterClickCallbackData](https://npmcn.com/package/%40capacitor/google-maps/#readme-clusterclickcallbackdata)>` |

* * *

### 设置于InfoWindowClick 听器(...)

```typescript
setOnInfoWindowClickListener(callback?: MapListenerCallback<MarkerClickCallbackData> | undefined) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`callback`** | `[MapListenerCallback](https://npmcn.com/package/%40capacitor/google-maps/#readme-maplistenercallback)<[MarkerClickCallbackData](https://npmcn.com/package/%40capacitor/google-maps/#readme-markerclickcallbackdata)>` |

* * *

### 在MapClick Listener上设置(...)

```typescript
setOnMapClickListener(callback?: MapListenerCallback<MapClickCallbackData> | undefined) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`callback`** | `[MapListenerCallback](https://npmcn.com/package/%40capacitor/google-maps/#readme-maplistenercallback)<[MapClickCallbackData](https://npmcn.com/package/%40capacitor/google-maps/#readme-mapclickcallbackdata)>` |

* * *

### 设定在 MarkerClick 听取器(...)

```typescript
setOnMarkerClickListener(callback?: MapListenerCallback<MarkerClickCallbackData> | undefined) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`callback`** | `[MapListenerCallback](https://npmcn.com/package/%40capacitor/google-maps/#readme-maplistenercallback)<[MarkerClickCallbackData](https://npmcn.com/package/%40capacitor/google-maps/#readme-markerclickcallbackdata)>` |

* * *

### 仅设定为Polygon Click 听取器(...)

```typescript
setOnPolygonClickListener(callback?: MapListenerCallback<PolygonClickCallbackData> | undefined) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`callback`** | `[MapListenerCallback](https://npmcn.com/package/%40capacitor/google-maps/#readme-maplistenercallback)<[PolygonClickCallbackData](https://npmcn.com/package/%40capacitor/google-maps/#readme-polygonclickcallbackdata)>` |

* * *

### 设置在 CircleClick 听器(...)

```typescript
setOnCircleClickListener(callback?: MapListenerCallback<CircleClickCallbackData> | undefined) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`callback`** | `[MapListenerCallback](https://npmcn.com/package/%40capacitor/google-maps/#readme-maplistenercallback)<[CircleClickCallbackData](https://npmcn.com/package/%40capacitor/google-maps/#readme-circleclickcallbackdata)>` |

* * *

### 仅设置Polyline Click 听取器(...)

```typescript
setOnPolylineClickListener(callback?: MapListenerCallback<PolylineCallbackData> | undefined) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`callback`** | `[MapListenerCallback](https://npmcn.com/package/%40capacitor/google-maps/#readme-maplistenercallback)<[PolylineCallbackData](https://npmcn.com/package/%40capacitor/google-maps/#readme-polylinecallbackdata)>` |

* * *

### 设置在 MarkerDragStart 听牌(...)

```typescript
setOnMarkerDragStartListener(callback?: MapListenerCallback<MarkerClickCallbackData> | undefined) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`callback`** | `[MapListenerCallback](https://npmcn.com/package/%40capacitor/google-maps/#readme-maplistenercallback)<[MarkerClickCallbackData](https://npmcn.com/package/%40capacitor/google-maps/#readme-markerclickcallbackdata)>` |

* * *

### 设置在 MarkerDrag 听取器上(...)

```typescript
setOnMarkerDragListener(callback?: MapListenerCallback<MarkerClickCallbackData> | undefined) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`callback`** | `[MapListenerCallback](https://npmcn.com/package/%40capacitor/google-maps/#readme-maplistenercallback)<[MarkerClickCallbackData](https://npmcn.com/package/%40capacitor/google-maps/#readme-markerclickcallbackdata)>` |

* * *

### 设置于 MarkerDragEnd 听取器(...)

```typescript
setOnMarkerDragEndListener(callback?: MapListenerCallback<MarkerClickCallbackData> | undefined) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`callback`** | `[MapListenerCallback](https://npmcn.com/package/%40capacitor/google-maps/#readme-maplistenercallback)<[MarkerClickCallbackData](https://npmcn.com/package/%40capacitor/google-maps/#readme-markerclickcallbackdata)>` |

* * *

### 设置在 MyLocation ButtonClick 听器上(...)

```typescript
setOnMyLocationButtonClickListener(callback?: MapListenerCallback<MyLocationButtonClickCallbackData> | undefined) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`callback`** | `[MapListenerCallback](https://npmcn.com/package/%40capacitor/google-maps/#readme-maplistenercallback)<[MyLocationButtonClickCallbackData](https://npmcn.com/package/%40capacitor/google-maps/#readme-mylocationbuttonclickcallbackdata)>` |

* * *

### 设置于 MyLocationClick 听取器(...)

```typescript
setOnMyLocationClickListener(callback?: MapListenerCallback<MapClickCallbackData> | undefined) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`callback`** | `[MapListenerCallback](https://npmcn.com/package/%40capacitor/google-maps/#readme-maplistenercallback)<[MapClickCallbackData](https://npmcn.com/package/%40capacitor/google-maps/#readme-mapclickcallbackdata)>` |

* * *

### 接口

#### 创建MapArgs

一个包含创建地图时所使用的选项的界面 .

| Prop | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| **`id`** | `string` | 映射实例的独有标识符 . |  |
| **`apiKey`** | `string` | 谷歌地图SDK API密钥. |  |
| **`config`** | `[GoogleMapConfig](https://npmcn.com/package/%40capacitor/google-maps/#readme-googlemapconfig)` | 地图的初始配置设置 . |  |
| **`element`** | `HTMLElement` | Google地图视图将挂载的DOM元素将决定大小和定位. |  |
| **`forceCreate`** | `boolean` | 如果已存在带有所提供 id 的地图, 则销毁并重新创建地图实例 | `false` |
| **`region`** | `string` | 区域参数修改您的应用程序, 以服务不同的地图平面或偏差应用程序( 如将地理编码结果偏向区域) 。 仅可用于网络. |  |
| **`language`** | `string` | 语言参数影响控制名称,版权通知,驱动方向,控制标签,以及对服务请求的回应. 仅可用于网络. |  |

#### GoogleMapConfig 图像

对于网页,所有 Javascript Google 地图选项均可作为 GoogleMapConfig 扩展google.maps. 地图选项. 对于iOS和Android,只声明配置选项 [GoogleMapConfig 图像](https://npmcn.com/package/%40capacitor/google-maps/#readme-googlemapconfig) 备有.

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`width`** | `number` | 覆盖本地地图的宽度 . |  |  |
| **`height`** | `number` | 覆盖本地地图的高度 . |  |  |
| **`x`** | `number` | 覆盖本地地图的绝对 x 坐标位置 . |  |  |
| **`y`** | `number` | 覆盖本地地图的绝对位置 . |  |  |
| **`center`** | `[LatLng](https://npmcn.com/package/%40capacitor/google-maps/#readme-latlng)` | 摄影机指向地球的默认位置. |  |  |
| **`zoom`** | `number` | 设置地图的缩放. |  |  |
| **`androidLiteMode`** | `boolean` | 在Android上启用基于图像的lide模式. | `false` |  |
| **`devicePixelRatio`** | `number` | 覆盖本地地图的像素比 . |  |  |
| **`styles`** | `MapTypeStyle[] | null` | 适用于每个默认地图类型的样式。 请注意,对于卫星,混合和地形模式,这些样式将只适用于标签和几何. |  | 4.3.0 (单位:千美元) |
| **`mapId`** | `string` | 与特定地图样式或特征相联的地图 ID. [使用地图标识](https://developers.google.com/maps/documentation/get-map-id) 只为Web. |  | 5.4.0 (单位:千美元) |
| **`androidMapId`** | `string` | 与特定地图样式或特征相联的地图 ID. [使用地图标识](https://developers.google.com/maps/documentation/get-map-id) 只为安卓. |  | 5.4.0 (单位:千美元) |
| **`iOSMapId`** | `string` | 与特定地图样式或特征相联的地图 ID. [使用地图标识](https://developers.google.com/maps/documentation/get-map-id) 只为iOS. |  | 5.4.0 (单位:千美元) |
| **`maxZoom`** | `number | null` | 在地图上显示的最大缩放级别 。 如果省略,或设置为<code>null</code>,则取而代之的是当前地图类型的最大缩放。 有效缩放值是从零到被支持的"(a href=)"https://developers.google.com/maps/documentation/javascript/maxzoom"(最大缩放级)". |  |  |
| **`minZoom`** | `number | null` | 在地图上显示的最小缩放级别 。 如果省略,或设置为<code>null</code>,则使用当前地图类型的最小缩放。 有效缩放值是从零到被支持的"(a href=)"https://developers.google.com/maps/documentation/javascript/maxzoom"(最大缩放级)". |  |  |
| **`mapTypeId`** | `string | null` | 最初的地图TypeId. 默认为<code>ROADMAP</code>. |  |  |
| **`heading`** | `number | null` | 空中影像的航向从北方向顺时针测量 标题断到有图像的最近可用角度. |  |  |
| **`restriction`** | `MapRestriction | null` | 定义限制用户可访问的地图区域的边界。 设定时,一个用户只能在相机视图停留在边界界限内时进行平面和缩放. |  |  |

#### 连线

代表一对经纬度坐标的接口.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`lat`** | `number` | 坐标纬度,单位为度. 此值在范围 \[- 90, 90\]. |
| **`lng`** | `number` | 坐标经纬度,以度为单位. 此值在范围 \[-180, 180\]. |

#### 映射调回数据

| Prop | 类型 |
| --- | --- |
| **`mapId`** | `string` |

#### 拼图

平板覆盖是放置在您地图上的特定缩放级的图像 。 可在iOS、Android和Web上查阅

| Prop | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| **`url`** | `string` | 代表瓷砖 URL 的字符串 。 应包含 `{x}`, (中文(简体) ), `{y}` 财务报告和审定财务报表 `{z}` 因此它们可以被x,y和缩放的实际值所取代. 可在iOS、Android和Web上查阅 |  |
| **`opacity`** | `number` | 瓦片上覆的不透明,在0(完全透明)到1(包含)之间. 可在iOS、Android和Web上查阅 | `undefined` |
| **`visible`** | `boolean` | 控制此平板覆被是否可见 。 仅在Android上可用 | `undefined` |
| **`zIndex`** | `number` | 砖瓦上覆的zIndex. 可在iOS和Android上查阅 | `undefined` |

#### 标记

标记是放置在地图表面特定点上的一个图标.

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`coordinate`** | `[LatLng](https://npmcn.com/package/%40capacitor/google-maps/#readme-latlng)` | [标记](https://npmcn.com/package/%40capacitor/google-maps/#readme-marker) 职位 |  |  |
| **`opacity`** | `number` | 设置标记的不透明度,介于 0 (完全透明) 和 1 之间. | `1` |  |
| **`title`** | `string` | 标题 上下文简介. |  |  |
| **`snippet`** | `string` | 片段文本,在选中时在信息窗口的标题下显示 . |  |  |
| **`isFlat`** | `boolean` | 控制这个标记是平地对地表还是面对相机的公告牌. | `false` |  |
| **`iconUrl`** | `string` | 要渲染的标记图标的路径 。 它可以是相对于网络应用公共目录,也可以是远程标记图标的https url. **SVG不支持在本地平台上.** |  | 4.2.0 (中文(简体) ) |
| **`iconSize`** | `[Size](https://npmcn.com/package/%40capacitor/google-maps/#readme-size)` | 控制标记图像设置的缩放大小 `iconUrl`。 。 。 . |  | 4.2.0 (中文(简体) ) |
| **`iconOrigin`** | `[Point](https://npmcn.com/package/%40capacitor/google-maps/#readme-point)` | 图像在图示中的位置, 如果有的话 。 默认情况下, 来源位于图像左上角 . |  | 4.2.0 (中文(简体) ) |
| **`iconAnchor`** | `[Point](https://npmcn.com/package/%40capacitor/google-maps/#readme-point)` | 将图像与地图上标记位置对应的位置 。 默认情况下,锚地位于图像下方的中心点上. |  | 4.2.0 (中文(简体) ) |
| **`tintColor`** | `{ r: number; g: number; b: number; a: number; }` | 自定义默认标记图像的颜色。 每个值必须在0到255之间. 仅供iOS和Android使用. |  | 4.2.0 (中文(简体) ) |
| **`draggable`** | `boolean` | 控制此标记是否可以交互拖曳 | `false` |  |
| **`zIndex`** | `number` | 指定此标记的堆栈顺序,相对于地图上的其他标记。 高z指数的标记被绘制在下z指数的标记上 | `0` |  |

#### 大小

| Prop | 类型 |
| --- | --- |
| **`width`** | `number` |
| **`height`** | `number` |

#### 点

| Prop | 类型 |
| --- | --- |
| **`x`** | `number` |
| **`y`** | `number` |

#### 多边形

对于网络,所有的javascript [多边形](https://npmcn.com/package/%40capacitor/google-maps/#readme-polygon) 选项可用 多边形扩展了google.maps. 多边形选项. 对于iOS和Android,只声明配置选项 [多边形](https://npmcn.com/package/%40capacitor/google-maps/#readme-polygon) 备有.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`paths`** | `any[] | MVCArray<any>` | 指定闭环的坐标顺序 。 与多线不同,多边形可能由一个或多个路径组成. 因此,路径属性可能指定一个或多个“代码”的数组[连线](https://npmcn.com/package/%40capacitor/google-maps/#readme-latlng)</code>坐标。 路径自动关闭;不要将路径的第一个顶点重复为最后一个顶点. 简单的多边形可以使用一个“ code” 的单数组定义 [连线](https://npmcn.com/package/%40capacitor/google-maps/#readme-latlng)</code>s. (中文(简体) ). 更复杂的多边形可能指定一个数组. 任何简单的阵列都会被转换为"#MVCArray""MVCArray</a></code>s". 插入或删除<代码>[连线](https://npmcn.com/package/%40capacitor/google-maps/#readme-latlng)</code>从 <code>MVCArray </code>自动更新地图上的多边形. |
| **`strokeColor`** | `string` | 中风之色. 支持所有 CSS3 颜色,但扩展命名颜色除外. |
| **`strokeOpacity`** | `number` | 0至1.0之间的中风不透明 |
| **`strokeWeight`** | `number` | 中风宽度以像素表示. |
| **`fillColor`** | `string` | 填充颜色. 支持所有 CSS3 颜色,但扩展命名颜色除外. |
| **`fillOpacity`** | `number` | 0.0至1.0之间的填充不透明 |
| **`geodesic`** | `boolean` | 当 <code> truth </code> 时,多边形边缘被解释为大地测量,并将遵循地球的曲率。 当 <code>false </code> 时,多边形边缘在屏幕空间中作为直线提供。 请注意,大地测量多边形的外形在被拖动时可能会有变化,因为相对于地表,维度会保持不变. |
| **`clickable`** | `boolean` | 显示此“ 代码” 是否[多边形](https://npmcn.com/package/%40capacitor/google-maps/#readme-polygon)</code> 处理鼠标事件. |
| **`title`** | `string` | 标题 上下文简介. 一些覆盖,例如标记,会在地图上显示标题. 标题也是默认的可访问文本. 仅在iOS上可用. |
| **`tag`** | `string` |  |

#### 圆形

对于网络,所有的javascript [圆形](https://npmcn.com/package/%40capacitor/google-maps/#readme-circle) 选项可用 圆能延伸出google.maps. 圆可选. 对于iOS和Android,只声明配置选项 [圆形](https://npmcn.com/package/%40capacitor/google-maps/#readme-circle) 备有.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`fillColor`** | `string` | 填充颜色. 支持所有 CSS3 颜色,但扩展命名颜色除外. |
| **`fillOpacity`** | `number` | 填充不透明在0.0到1.0之间. |
| **`strokeColor`** | `string` | 中风之色. 支持所有 CSS3 颜色,但扩展命名颜色除外. |
| **`strokeWeight`** | `number` | 中风宽度以像素表示. |
| **`geodesic`** | `boolean` |  |
| **`clickable`** | `boolean` | 显示此“ 代码” 是否[圆形](https://npmcn.com/package/%40capacitor/google-maps/#readme-circle)</code> 处理鼠标事件. |
| **`title`** | `string` | 标题 上下文简介. 一些覆盖,例如标记,会在地图上显示标题. 标题也是默认的可访问文本. 仅在iOS上可用. |
| **`tag`** | `string` |  |

#### 复线

对于网络,所有的javascript [复线](https://npmcn.com/package/%40capacitor/google-maps/#readme-polyline) 选项可用 Polyline扩展了google.maps. 复行可选. 对于iOS和Android,只声明配置选项 [复线](https://npmcn.com/package/%40capacitor/google-maps/#readme-polyline) 备有.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`strokeColor`** | `string` | 中风之色. 支持所有 CSS3 颜色,但扩展命名颜色除外. |
| **`strokeOpacity`** | `number` | 中风不透明在0.0到1.0之间. |

## 常见问题

### @capacitor/google-maps 是什么？

Capacitor 上的 Google 地图

### 如何安装 @capacitor/google-maps？

在项目目录运行 npm install @capacitor/google-maps，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capacitor/google-maps 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capacitor/google-maps 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capacitor/google-maps 可以商用吗？

@capacitor/google-maps 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @capacitor/google-maps 的下载量有多少？

根据 npm 官方下载统计，@capacitor/google-maps 在 2026/10/09 – 2026/11/07 这 30 天内被下载 126,324 次，日均约 4,211 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capacitor/google-maps 还在维护吗？

最新版本 8\.0\.1 发布于 2026/02/12（8 个月前）；至今共发布 443 个版本，其中过去 12 个月发布了 4 个；首次发布于 2022/04/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。