快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-native-map` plugin in my project.

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

npm install @capgo/capacitor-native-map
npx cap sync

需要 Capacitor 8+. 插件主版本号跟随 Capacitor（package v8).

导入

import { NativeMap } from '@capgo/capacitor-native-map';

快速入门

import { NativeMap } from '@capgo/capacitor-native-map';
await NativeMap.create({ id: 'map', element: document.getElementById('map')!, config: { center: { lat: 0, lng: 0 }, zoom: 10 } });

常见坑点

• 在 Android 和 Web 端配置 Google Maps API 密钥。
• 当容器尺寸变化时，调用 updateLayout。
• 离开页面时销毁地图实例。

平台设置

平台	地图引擎	API 密钥
iOS	Apple MapKit	地图无需此配置
Android	Google Maps SDK	GOOGLE_MAPS_API_KEY 在应用清单中
Web 端	Google Maps JavaScript API	apiKey 以及（可选） config.mapId 开启 create

• iOS 配置 用于 MapKit 和位置权限描述字符串。
• Android 配置 用于 Google Maps SDK API 密钥。

内嵌地图

import { NativeMap } from '@capgo/capacitor-native-map';

const map = await NativeMap.create({
  id: 'main-map',
  element: document.getElementById('map')!,
  apiKey: 'YOUR_GOOGLE_MAPS_API_KEY',
  config: {
    center: { lat: 37.7749, lng: -122.4194 },
    zoom: 12,
  },
});

map.setOnMapClickListener((e) => console.log('click', e.latitude, e.longitude));

await map.addMarker({
  coordinate: { lat: 37.7749, lng: -122.4194 },
  title: 'San Francisco',
});

// Call destroy() when leaving the screen or unmounting your map component.

背景地图（toBack）及 HTML 覆盖层

设置 toBack: true 以便 MapKit 或 Google Maps 能够渲染 在 透明的 Capacitor WebView 之后。透明区域的触摸事件会穿透到地图（捏合、旋转、倾斜、平移）。需要接收点击的区域需要 data-map-overlay 因此 README 中的 CSS 为它们提供了 pointer-events: auto.

当 toBack 为 true, element 在 CreateMapArgs （插件默认为 document.body）。当 toBack 为 false，传入 element 如上方嵌入示例所示。 updateLayout, show，以及 hide 已启用 NativeMap 在当前插件源码中（参见 README 中的 overlay 部分).

const map = await NativeMap.create({
  id: 'overlay-map',
  toBack: true,
  apiKey: 'YOUR_GOOGLE_MAPS_API_KEY',
  config: {
    center: { lat: 37.7749, lng: -122.4194 },
    zoom: 12,
    x: 0,
    y: 0,
    width: window.innerWidth,
    height: window.innerHeight,
  },
});

await map.updateLayout({ x: 0, y: 0, width: window.innerWidth, height: window.innerHeight });
await map.hide();
await map.show();

使用带有 class 的根元素 map-overlay-root 以及 data-native-map-overlay-root。将 data-map-overlay 添加到每个应接收点击的 HUD 区域（例如 header 或 footer wrapper）。该区域内的按钮和链接之所以有效，是因为父元素具有 pointer-events: auto:

<div class="map-overlay-root" data-native-map-overlay-root>
  <header class="hud" data-map-overlay>
    <button type="button" id="recenter">Recenter</button>
  </header>
</div>

添加插件 README 中的页面透明度和 pointer-event 规则：

html.native-map-to-back,
body.native-map-to-back {
  background: transparent !important;
}

:root {
  --ion-background-color: transparent !important;
}

.map-overlay-root {
  position: fixed;
  inset: 0;
  pointer-events: none;
}

.map-overlay-root [data-map-overlay] {
  pointer-events: auto;
}

使用 show() 以及 hide() 以便在不销毁原生地图的情况下切换。调用 updateLayout 当 viewport 或 safe-area insets 发生变化时。