Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

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

Nutze dann diesen Prompt:

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

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

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

Erfordert Capacitor 8+. Die Major-Version des Plugins folgt Capacitor (Package v8).

Importieren

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

Quickstart

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

Häufige Stolperfallen

• Konfiguriere Google Maps API Keys für Android und Web.
• Rufe updateLayout auf, wenn sich die Größe des Containers ändert.
• Maps zerstören, wenn der Screen verlassen wird.

Plattform-Setup

Plattform	Map-Engine	API Key
iOS	Apple MapKit	Nicht für die Map erforderlich
Android	Google Maps SDK	GOOGLE_MAPS_API_KEY im App-Manifest
Web	Google Maps JavaScript API	apiKey und optional config.mapId auf create

• iOS-Setup für MapKit- und Standort-Usage-Strings.
• Android-Setup für den Google Maps SDK API Key.

Eingebettete Karte

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.

Hintergrundkarte (toBack) mit HTML-Overlay

Setzen Sie toBack: true wie MapKit oder Google Maps gerendert wird, hinter einer transparenten Capacitor WebView. Berührungen auf transparenten Bereichen werden an die Map weitergegeben (Pinch, Rotate, Tilt, Pan). Bereiche, die Taps empfangen sollen, benötigen data-map-overlay damit das README CSS ihnen pointer-events: auto.

Wenn toBack ist true, element ist optional in CreateMapArgs (das Plugin nutzt standardmäßig document.body). Wenn toBack ist false, übergib element wie im eingebetteten Beispiel oben. updateLayout, show, und hide sind auf NativeMap in den aktuellen Plugin-Quellen (siehe den README-Abschnitt „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();

Verwende ein Root-Element mit der Klasse map-overlay-root und data-native-map-overlay-root. Setze data-map-overlay auf jede HUD-Region, die Taps empfangen soll (z. B. einen header oder footer Wrapper). Buttons und Links innerhalb dieser Region funktionieren, da das Parent-Element ... hat 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>

Füge die Page-Transparency- und Pointer-Event-Regeln aus dem Plugin-README hinzu:

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;
}

Nutzt show() und hide() um die native Map umzuschalten, ohne sie zu zerstören. Rufe updateLayout auf, wenn sich der Viewport oder die Safe-Area-Insets ändern.