Se hai bisogno di un'alternativa a Google Maps per Capacitor, hai tre percorsi realistici: mantenere quello ufficiale @capacitor/google-maps plugin e aggirare i suoi limiti, renderizzare la mappa nella WebView con una libreria JavaScript come MapLibre GL JS o Leaflet, oppure usare un plugin mappa nativo basato su un altro SDK. Capgo non include un plugin per il rendering delle mappe, quindi questa guida confronta le opzioni in modo neutrale e mostra i plugin Capgo che funzionano bene accanto a qualsiasi mappa: handoff di navigazione, geocoding e posizione in background.
Perché gli sviluppatori guardano oltre @capacitor/google-maps
Il plugin ufficiale (versione 8 per Capacitor 8) integra il SDK nativo di Google Maps su iOS e Android e il API JavaScript di Google Maps sul web. Funziona, ma questi punti tornano fuori continuamente.
Un account Google Cloud con fatturazione attiva su ogni piattaforma
Il plugin richiede chiavi API legate a un account Google Cloud con fatturazione attiva, su Android, iOS e web. I prezzi di Google per il caricamento delle mappe native mobile sono generosi, ma devi comunque configurare la fatturazione, limitare le chiavi per piattaforma e tenere d'occhio le quote. I caricamenti web e i servizi come Places e Directions vengono fatturati a consumo dopo le soglie gratuite. Controlla la pagina dei prezzi di Google Maps Platform prima di procedere, perché il modello è cambiato nel 2025.
Su Android la mappa viene disegnata dietro la WebView
Su iOS la vista mappa è inserita nella scroll view della WebView. Su Android viene renderizzata sotto l'intera WebView e il plugin la sposta per seguire l' <capacitor-google-map> elemento. Ogni layer sopra di essa deve essere trasparente:
/* Required on Android with @capacitor/google-maps */
html,
body,
ion-content,
ion-content::part(background) {
background: transparent !important;
--background: transparent;
}Questo è il problema numero uno, il classico «la mia mappa è vuota». Rende anche più difficili overlay personalizzati, modal e transizioni di pagina, perché l'HTML sta sopra una view nativa.
I marker si possono aggiungere e rimuovere, ma non aggiornare
Il API ha addMarker, addMarkers, removeMarker e removeMarkers, ma nessun updateMarker. Una posizione veicolo in tempo reale implica rimozione e aggiunta a ogni aggiornamento, con rischio di flicker e costi in chiamate al bridge.
Stile e funzionalità limitati su native
Alcune opzioni sono solo web, ad esempio mapId per lo styling basato su cloud, e region e language. Otterrai marker, clustering, polilinee, poligoni, cerchi, tile overlay, controllo della camera e listener di click. Se hai bisogno di styling data-driven, heatmaps o edifici 3D in modo identico su tutte le piattaforme, incontrerai dei limiti.
Panoramica delle opzioni
| Opzione | Rendering | Richiede chiave API | Fonte delle tile | Ideale per |
|---|---|---|---|---|
@capacitor/google-maps |
Native SDK (Android, iOS), JS sul web | Sì, fatturazione attiva | App che vogliono dati Google e performance native | |
| MapLibre GL JS | WebGL nella WebView | Dipende dal provider di tile | Qualsiasi sorgente di vector tile, self-hosting possibile | Mappe con stile custom, quasi offline, senza vendor lock-in |
| Leaflet | DOM e canvas nella WebView | Dipende dal provider di tile | Tile raster (basati su OSM o altri) | Mappe semplici, bundle ridotto, molti plugin |
| Google Maps JS API in WebView | Renderer JS di Google | Sì | Stesso look Google su tutte le piattaforme, set completo di funzionalità JS | |
| Plugin nativi MapLibre o Mapbox | SDK nativo | Dipende | Qualsiasi / Mapbox | Dati pesanti, sessioni lunghe, gesti nativi |
Non c'è un vincitore unico. La scelta giusta dipende dal volume di dati, dalle esigenze di styling e da quanto vuoi dipendere da un singolo vendor.
Opzione 1: MapLibre GL JS nella WebView
MapLibre GL JS è il fork open source di Mapbox GL JS v1. Renderizza i vettori tile con WebGL e funziona bene in WKWebView e nel System WebView di Android. È l'opzione più flessibile se non hai bisogno dei dati di Google.
bun add maplibre-glimport maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
const map = new maplibregl.Map({
container: 'map',
style: 'https://your-tile-provider.example.com/styles/streets/style.json',
center: [2.3522, 48.8566], // [lng, lat]
zoom: 12,
});
map.addControl(new maplibregl.NavigationControl(), 'top-right');
// A marker you can move without remove/add
const courier = new maplibregl.Marker({ color: '#1d4ed8' })
.setLngLat([2.35, 48.85])
.addTo(map);
export function moveCourier(lng: number, lat: number) {
courier.setLngLat([lng, lat]);
}GeoJSON layers, data driven styling e route lines sono first class:
map.on('load', () => {
map.addSource('route', {
type: 'geojson',
data: {
type: 'Feature',
properties: {},
geometry: {
type: 'LineString',
coordinates: [
[2.3522, 48.8566],
[2.3376, 48.8606],
[2.2945, 48.8584],
],
},
},
});
map.addLayer({
id: 'route-line',
type: 'line',
source: 'route',
paint: { 'line-color': '#2563eb', 'line-width': 5 },
});
});Cose da sapere:
- Hai bisogno di una sorgente di tile. Le opzioni includono host di vettori tile commerciali o l'auto-hosting di tile generati dai dati OpenStreetMap. I server tile pubblici di OpenStreetMap hanno una policy di utilizzo che non consente un traffico pesante da app.
- Mostra sempre l'attribuzione richiesta dal tuo provider di tile.
- Poiché è semplice web code, la stessa mappa funziona in un'anteprima del browser, accelerando lo sviluppo.
Opzione 2: Leaflet
Leaflet è piccolo e maturo. È adatto per mappe con poche centinaia di marker, tile raster e interazioni semplici.
bun add leafletimport L from 'leaflet';
import 'leaflet/dist/leaflet.css';
const map = L.map('map').setView([48.8566, 2.3522], 13);
L.tileLayer('https://tiles.example.com/{z}/{x}/{y}.png', {
maxZoom: 19,
attribution: '© OpenStreetMap contributors',
}).addTo(map);
L.marker([48.8584, 2.2945]).addTo(map).bindPopup('Eiffel Tower');Nelle app bundle, i percorsi dei marker icon di default di Leaflet spesso si rompono. Importa le immagini delle icone e imposta L.Icon.Default options, oppure usa le tue L.divIcon.
Opzione 3: API JavaScript di Google Maps nella WebView
Se ti servono i dati e l'aspetto di Google, ma vuoi che la mappa si comporti come un qualsiasi altro elemento HTML, carica l'API JavaScript di Maps nella WebView invece dell'SDK nativo. Perdi un po' di fluidità nativa e ogni caricamento della mappa è un caricamento web fatturabile, ma hai a disposizione tutta l'API JS: cloud styling con map ID, marker avanzati e data layer.
Limita la web key tramite HTTP referrer. Su iOS, Capacitor serve l'app da capacitor://localhost di default, e su Android da https://localhost, quindi aggiungi questi origin alle restrizioni della key e testa entrambi.
Opzione 4: plugin nativi basati su altri SDK
Nella community esistono wrapper nativi per MapLibre Native o per gli SDK Mapbox. Offrono gesture e performance native con qualsiasi tile source. Prima di sceglierne uno, verifica che supporti Capacitor 8, che abbia un rilascio recente, che supporti Swift Package Manager su iOS (il default per i nuovi progetti iOS Capacitor 8) e che copra i tipi di overlay che ti servono. I plugin mappa nativi hanno lo stesso compromesso di layering del plugin ufficiale: la mappa è una view nativa e l'HTML va disposto attorno a essa.
Mantieni @capacitor/google-maps se
- Ti servono la mappa base, Places e i dati di Street View di Google.
- La tua mappa è una vista a schermo intero, non una piccola card dentro contenuti scrollabili.
- Puoi convivere con remove e add per spostare i marker, o aggiorni le posizioni di rado.
Se decidi di tenerlo, imposta il CSS di trasparenza qui sopra, assegna al <capacitor-google-map> elemento una dimensione esplicita, chiama destroy() quando si lascia la pagina, e imposta skipLibCheck: true nella tsconfig.json come richiesto dal README del plugin.
Plugin che funzionano bene con qualsiasi mappa
Qualunque cosa renderizzi la mappa, questi plugin Capgo coprono le parti native che una mappa in WebView non può gestire da sola.
Delega la navigazione turn-by-turn
Sviluppare la navigazione è un progetto a sé. La maggior parte delle app apre invece l'app di navigazione preferita dall'utente. @capgo/capacitor-launch-navigator supporta Apple Maps, Google Maps, Waze e molti altri:
import { LaunchNavigator, TransportMode } from '@capgo/capacitor-launch-navigator';
await LaunchNavigator.navigate({
destination: [48.8584, 2.2945], // [lat, lng]
options: { transportMode: TransportMode.DRIVING },
});Geocoding senza un web service
@capgo/capacitor-nativegeocoder usa i geocoder di piattaforma su iOS e Android, che non richiedono una chiave Google sul dispositivo:
import { NativeGeocoder } from '@capgo/capacitor-nativegeocoder';
const { addresses } = await NativeGeocoder.reverseGeocode({
latitude: 48.8584,
longitude: 2.2945,
maxResults: 1,
});
console.log(addresses[0]?.thoroughfare, addresses[0]?.locality);
const result = await NativeGeocoder.forwardGeocode({
addressString: '5 Avenue Anatole France, Paris',
maxResults: 1,
});
console.log(result.addresses[0]?.latitude, result.addresses[0]?.longitude);Sul web, il plugin usa API di Google e richiede la apiKey opzione.
Mostra la posizione dell'utente, anche in background
Per il "pallino blu" in foreground, @capacitor/geolocation è sufficiente. Per continuare a tracciare mentre l'app è in background, o per attivare eventi quando l'utente entra in un luogo, usa @capgo/background-geolocation, e passa i punti alla mappa che hai scelto.
Risolvere problemi con le mappe in Capacitor
Mappa vuota su Android con il plugin ufficiale. La trasparenza manca su un elemento genitore. Ispeziona con Chrome DevTools tramite chrome://inspect e cerca eventuali colori di sfondo tra <html> e l'elemento mappa.
L'elemento mappa ha altezza zero. I contenitori della mappa non hanno dimensioni intrinseche. Imposta un'altezza esplicita o usa un layout flex con un genitore di altezza fissa.
La mappa WebGL è sfocata o lenta su Android. Verifica che il System WebView sia aggiornato sul dispositivo, riduci il numero di layer ed evita di ricreare la mappa a ogni cambio di rotta. Creala una volta e riusala.
Le tile non si caricano nelle build di release. Controlla la Content Security Policy e la configurazione di sicurezza della rete, assicurandoti che l'host delle tile sia HTTPS.
La mappa si rompe dopo aver modificato l'URL dello stile delle tile. Gli URL di stile e tile sono solo configurazione JavaScript. Puoi cambiare provider per gli utenti esistenti con Live updates di Capgo, senza un rilascio sull'app store, purché non ci siano modifiche native a code.
Come scegliere
- Hai bisogno di dati Google e prestazioni native su una mappa a schermo intero: mantieni
@capacitor/google-maps. - Hai bisogno di stili personalizzati, nessuna fatturazione Google e una mappa che si comporti come l'HTML: MapLibre GL JS.
- Hai bisogno di una mappa semplice con pochi marker: Leaflet.
- Hai bisogno dell'aspetto Google in un layout scorrevole: Google Maps JS API nel WebView.
Qualunque tu scelga, testa presto su un dispositivo Android di fascia bassa. Per altri componenti nativi, sfoglia il directory dei plugin di Capgo.
