Prise en main

Installer

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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

Si vous préférez une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :

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

Nécessite une Capacitor 8+. La version majeure du plugin suit Capacitor (package v8).

Importer

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

Démarrage rapide

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

Erreurs courantes

• Configurez les clés API Google Maps sur Android et sur le web.
• Appelez updateLayout lors du redimensionnement du conteneur.
• Détruisez les cartes en quittant les écrans.

Configuration de la plateforme

Plateforme	Moteur de carte	clé API
iOS	Apple MapKit	Non requis pour la carte
Android	Google Maps SDK	GOOGLE_MAPS_API_KEY dans le manifeste de l’app
Le Web	Google Maps JavaScript API	apiKey et éventuellement config.mapId sur create

• Configuration iOS pour les chaînes d’usage de MapKit et de la localisation.
• Configuration Android pour la clé Google Maps SDK API.

Carte intégrée

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.

Carte en arrière-plan (toBack) avec overlay HTML

Définissez toBack: true afin que MapKit ou Google Maps s’affiche derrière un Capacitor WebView transparent. Les touches sur les zones transparentes sont transmises à la carte (zoom, rotation, inclinaison, déplacement). Les zones qui doivent recevoir les appuis ont besoin data-map-overlay afin que le CSS du README leur attribue pointer-events: auto.

Quand toBack est true, element est facultatif dans CreateMapArgs (le plugin utilise par défaut document.body). Quand toBack est false, passez element comme dans l'exemple intégré ci-dessus. updateLayout, show, et hide sont activés NativeMap dans les sources actuelles du plugin (voir la section overlay du 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();

Utilisez un élément racine avec la classe map-overlay-root et data-native-map-overlay-root. Placez data-map-overlay sur chaque zone du HUD qui doit recevoir les taps (par exemple un header ou footer wrapper). Les boutons et liens dans cette zone fonctionnent parce que le parent a 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>

Ajoutez les règles de transparence de page et de pointer-event du README du 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;
}

Utiliser show() et hide() pour basculer la carte native sans la détruire. Appelez updateLayout lorsque le viewport ou les insets de safe-area changent.