Primeros pasos

Instalar

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

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

Luego usa el siguiente prompt:

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

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

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

Requiere Capacitor 8+. La versión major del plugin sigue a Capacitor (paquete v8).

Importar

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

Inicio rápido

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

Errores comunes

• Configura las keys de Google Maps API en Android y web.
• Llama a updateLayout cuando el contenedor cambie de tamaño.
• Destruye los maps al salir de las pantallas.

Configuración de la plataforma

Plataforma	Motor de mapas	clave de API
iOS	Apple MapKit	No es necesario para el mapa
Android	Google Maps SDK	GOOGLE_MAPS_API_KEY en el manifiesto de la app
Web	API de Google Maps JavaScript	apiKey y opcionalmente config.mapId en create

• Configurar iOS para los strings de uso de MapKit y ubicación.
• Configuración de Android para la clave SDK API de Google Maps.

Mapa embebido

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.

Mapa de fondo (toBack) con overlay HTML

Configurar toBack: true para que MapKit o Google Maps se renderice detrás de una WebView transparente de Capacitor. Los toques en las áreas transparentes pasan al mapa (pellizcar, rotar, inclinar, desplazar). Las regiones que deben recibir toques necesitan data-map-overlay para que el CSS del README les dé pointer-events: auto.

Cuando toBack es true, element es opcional en CreateMapArgs (el plugin usa por defecto document.body). Cuando toBack es false, pasa element como en el ejemplo integrado de arriba. updateLayout, show, y hide están en NativeMap en las fuentes actuales del plugin (ver la sección de 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 raíz con la clase map-overlay-root y data-native-map-overlay-root. Pon data-map-overlay en cada región del HUD que deba recibir taps (por ejemplo un header o footer wrapper). Los botones y enlaces dentro de esa región funcionan porque el padre tiene 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>

Añade las reglas de transparencia de página y pointer-event del 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() y hide() para alternar el mapa nativo sin destruirlo. Llama a updateLayout cuando cambie el viewport o los safe-area insets.