Per iniziare

Installa

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

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

Poi usa il seguente prompt:

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

Se preferisci la configurazione manuale, installa il plugin eseguendo questi comandi e segui le istruzioni specifiche per piattaforma qui sotto:

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

Richiede Capacitor 8+. La versione major del plugin segue Capacitor (package v8).

Importa

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

Avvio rapido

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

Errori comuni

• Configura le chiavi API di Google Maps per Android e web.
• Chiama updateLayout quando il container viene ridimensionato.
• Distruggi le mappe quando esci dalle schermate.

Configurazione della piattaforma

Piattaforma	Motore mappe	Chiave API
iOS	Apple MapKit	Non richiesto per la mappa
Android	SDK di Google Maps	GOOGLE_MAPS_API_KEY nel manifest dell'app
Web	API di Google Maps JavaScript	apiKey e opzionalmente config.mapId su create

• Setup iOS per le stringhe di utilizzo di MapKit e della posizione.
• Configurazione Android per la chiave SDK API di Google Maps.

Mappa incorporata

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.

Mappa in background (toBack) con overlay HTML

Imposta toBack: true in modo che MapKit o Google Maps venga renderizzato dietro una WebView Capacitor trasparente. I tocchi sulle aree trasparenti passano alla mappa (pinch, rotazione, inclinazione, pan). Le regioni che devono ricevere i tap necessitano di data-map-overlay in modo che il CSS del README gli conferisca pointer-events: auto.

Quando toBack è true, element è facoltativo in CreateMapArgs (il plugin usa di default document.body). Quando toBack è false, passa element come nell'esempio incorporato sopra. updateLayout, show, e hide sono attivi NativeMap nelle sorgenti del plugin corrente (vedi la sezione overlay del README).

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();

Usa un elemento radice con la classe map-overlay-root e data-native-map-overlay-root. Metti data-map-overlay su ogni regione HUD che deve ricevere i tap (ad esempio un header oppure footer wrapper). I pulsanti e i link all'interno di quella regione funzionano perché l'elemento genitore ha 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>

Aggiungi le regole di trasparenza pagina e pointer-events dal README del plugin:

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

Usa show() e hide() per attivare/disattivare la mappa nativa senza distruggerla. Chiama updateLayout quando la viewport o gli inset della safe-area cambiano.