Wenn Sie ein Google Maps-Alternativ-Capacitor benötigen, haben Sie drei realistische Wege: den offiziellen } @capacitor/google-maps plugin and work around its limits, render the map inside the WebView with a JavaScript library such as MapLibre GL JS or Leaflet, or use a native map plugin built on another SDK. Capgo does not ship its own map rendering plugin, so this guide compares the options neutrally, and shows the Capgo plugins that work well next to any map: navigation handoff, geocoding and background location.
Warum entwickler über @capacitor/google-maps hinaus schauen
The official plugin (version 8 for Capacitor 8) embeds the native Google Maps SDK on iOS and Android and the Google Maps JavaScript API on the web. It works, but these points come up again and again.
Ein Google Cloud-Konto mit Abrechnungsfunktion auf jedem Plattform
The plugin needs API keys tied to a Google Cloud account with billing enabled, on Android, iOS and web. Google’s pricing for native mobile map loads is generous, but you still have to set up billing, restrict keys per platform, and watch quotas. Web map loads and services such as Places and Directions are billed by usage after free caps. Check the current Google Maps Platform pricing page before you commit, as the model changed in 2025.
Auf Android wird die Karte hinter dem WebView gezeichnet
On iOS wird die Kartenansicht in die WebView-Skrollansicht platziert. Auf Android wird sie unter der gesamten WebView gerendert und das Plugin schiebt sie, um sie der folgenden <capacitor-google-map> Jeder übergeordnete Layer muss transparent sein:
/* Required on Android with @capacitor/google-maps */
html,
body,
ion-content,
ion-content::part(background) {
background: transparent !important;
--background: transparent;
}Dies ist die Nummer eins der häufigsten Probleme: "Meine Karte ist leer". Es macht auch die Anpassung von benutzerdefinierten Überlagerungen, Modalen und Seitenwechseln schwieriger, da Ihre HTML auf einem nativen View liegt.
Markers können hinzugefügt und entfernt werden, nicht aktualisiert.
Die API hat addMarker, addMarkers, removeMarker und removeMarkers, aber kein updateMarkerEin lebendiger Fahrzeugstandort bedeutet, dass auf jedem Update entfernt und hinzugefügt wird, was flackern und Brückenaufrufe kosten kann.
Beschränkte Stil- und Funktionen auf nativem
Einige Optionen sind nur im Web verfügbar, zum Beispiel mapId zum Cloud-basierten Styling und region und language. Sie erhalten Marker, Clustering, Polylinien, Polygone, Kreise, Tile Overlay, Kamera-Steuerung und Klick-Listener. Wenn Sie Datengetriebene Stilisierung, Heatmaps oder 3D-Gebäude auf allen Plattformen in gleichem Maße benötigen, werden Sie an Grenzen stoßen.
Die Optionen im Überblick
| Option | Rendern | API-Schlüssel erforderlich | Tile-Quelle | Best für |
|---|---|---|---|---|
@capacitor/google-maps |
Natives SDK (Android, iOS), JS auf Web | Ja, Abrechnung aktiviert | Apps, die Google-Daten und native Leistung benötigen | |
| MapLibre GL JS | WebGL in der WebView | Abhängig vom Tile-Provider | Jeder Vektor-Tiles-Quelle, selbst gehostet möglich | Benutzerdefinierte gestaltete Karten, offline-artig, ohne Verkäuferbindung |
| Leaflet | DOM und Canvas in der WebView | Abhängig vom Tile-Provider | Raster-Tiles (OSM-basiert oder andere) | Einfache Karten, kleiner Bundle, viele Plugins |
| Google Maps JS API in der WebView | Google's JS-Renderer | Ja | Ähnlicher Google-Look auf allen Plattformen, vollständige JS-Funktionsumfang | |
| Native MapLibre- oder Mapbox-Plugins | Native SDK | Hängt davon ab | Jedweder / Mapbox | Schwerer Datenverkehr, lange Sitzungen, native Gesten |
Es gibt keinen einzigartigen Sieger. Die richtige Wahl hängt von der Datenmenge, den Stilbedürfnissen und dem Maß ab, auf das Sie sich auf einen Händler verlassen möchten.
Option 1: MapLibre GL JS im WebView
MapLibre GL JS ist die Open-Source-Fork von Mapbox GL JS v1. Es renderet Vektortiles mit WebGL und läuft gut in WKWebView und dem Android-System-WebView. Es ist die flexibelste Option, wenn Sie nicht Googles Daten benötigen.
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-Layer, datengetriebene Stilung und Routenlinien sind erste Klasse:
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 },
});
});Dinge zu beachten:
- Sie benötigen eine Tile-Quelle. Optionen umfassen kommerzielle Vektortile-Hosts oder die Selbstverwaltung von Tiles, die aus OpenStreetMap-Daten generiert werden. Die öffentlichen OpenStreetMap-Tile-Server haben eine Nutzungsrichtlinie, die nicht das Schalten von starkem App-Verkehr zulässt.
- Zeigen Sie immer die Attributierung an, die Ihr Tile-Anbieter erfordert.
- Da es sich um eine einfache Webanwendung code, funktioniert der gleiche Map in einer Browser-Vorschau, was die Entwicklung beschleunigt.
Option 2: Leaflet
Leaflet ist klein und reif. Es ist ein guter Anbieter für Karten mit wenigen hundert Markern, Raster-Tiles und einfachen Interaktionen.
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');In verbundenen Apps brechen die Standardmarker-Icon-Pfade von Leaflet oft. Importieren Sie die Icon-Bilder und setzen Sie L.Icon.Default Option 3: Google Maps JavaScript __CAPGO_KEEP_0__ in der WebView L.divIcon.
Option 3: Google Maps JavaScript API in the WebView
If you need Google’s data and look, but want the map to behave like any other HTML element, load the Maps JavaScript API in the WebView instead of the native SDK. You lose some native smoothness, and every map load is a billable web load, but you get the full JS API: cloud styling with map IDs, advanced markers, data layers.
Beschränken Sie die Web-Schlüssel durch HTTP-Referenz. Auf iOS dient Capacitor die App aus. capacitor://localhost von Standard aus und auf Android von https://localhostFügen Sie diese Ursprünge den Schlüsselbeschränkungen hinzu und testen Sie beide.
Option 4: Native Plugins auf anderen SDKs
Es gibt in der Community native Wrapper um MapLibre Native oder die Mapbox SDKs. Sie bieten native Gesten und Leistung mit jeder Tile-Quelle. Bevor Sie eine auswählen, überprüfen Sie, ob sie Capacitor 8 unterstützt, eine aktuelle Version hat, Swift Package Manager auf iOS unterstützt (die Standard für neue Capacitor 8 iOS-Projekte) und die Overlay-Typen abdeckt, die Sie benötigen. Native Map-Plugins teilen die gleiche Layering-Abwägung wie der offizielle Plugin: Die Karte ist ein natives View, und Ihre HTML muss um es herum angeordnet werden.
Behalten Sie @capacitor/google-maps bei
- Sie benötigen Googles Basis-Karte, Orte und Straßenansichten.
- Ihre Karte ist ein Vollbild-View und nicht ein kleiner Karten-Card innerhalb eines scrollbaren Inhalts.
- Sie können sich mit Entfernen und Hinzufügen für bewegliche Markierungen oder seltenen Positionen aktualisieren.
Wenn Sie es behalten, setzen Sie die Transparenz-CSS oben, geben Sie dem <capacitor-google-map> Wenn Sie die Seite verlassen, und setzen Sie destroy() Wenn Sie die Seite verlassen, in skipLibCheck: true in tsconfig.json Wenn Sie die Seite verlassen, in
Wenn Sie die Seite verlassen, in
Was immer die Karte rendern, diese Capgo-Plugins decken die native Teile ab, die eine WebView-Karte alleine nicht ausführen kann.
Übergabe der Routenplanung Schritt für Schritt
Die Erstellung von Routenplanung ist ein eigenes Projekt. Die meisten Apps öffnen stattdessen die bevorzugte Navigation der Benutzer. @capgo/capacitor-launch-navigator unterstützt Apple Maps, Google Maps, Waze und viele andere:
import { LaunchNavigator, TransportMode } from '@capgo/capacitor-launch-navigator';
await LaunchNavigator.navigate({
destination: [48.8584, 2.2945], // [lat, lng]
options: { transportMode: TransportMode.DRIVING },
});Geokodierung ohne Webdienst
@capgo/capacitor-nativegeocoder verwendet die Plattform-Geokodierer auf iOS und Android, die auf dem Gerät keinen Google-Schlüssel benötigen:
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);Auf der Web-Seite verwendet der Plugin Google’s API und benötigt die apiKey Option.
Anzeige der Position des Benutzers, auch im Hintergrund
Für einen Vordergrund „blauen Punkt“ @capacitor/geolocation reicht es aus. Um weiterhin zu tracken, während die App im Hintergrund ist, oder um Ereignisse auszulösen, wenn Benutzer Orte betreten, verwenden Sie @capgo/background-geolocationund übergeben Sie Punkte an die gewählte Karte.
Fehlerbehebung bei Kartenproblemen in Capacitor
Leerer Karte auf Android mit dem offiziellen Plugin. Die Transparenz fehlt bei einem übergeordneten Element. Inspektion mit Chrome DevTools über chrome://inspect und suchen Sie nach einem Hintergrundfarb zwischen <html> und der Kartenkomponente.
Die Kartenkomponente hat keine Höhe. Die Kartencontainer haben keine intrinsic Größe. Setzen Sie eine explizite Höhe oder verwenden Sie eine flexible Layout mit einer fixierten Elternhöhe.
Die WebGL-Karte ist auf Android unscharf oder langsam. Überprüfen Sie, ob die System-WebView auf dem Gerät aktuell ist, reduzieren Sie die Anzahl der Layer und vermeiden Sie es, die Karte auf jedem Routenwechsel neu zu erstellen. Erstellen Sie sie einmal und verwenden Sie sie erneut.
Die Tiles laden nicht in Release-Builds. Überprüfen Sie Ihre Content-Security-Policy und Netzwerk-Sicherheitskonfiguration und stellen Sie sicher, dass der Tile-Host über HTTPS ist.
Die Karte bricht nachdem Sie die Tile-Style-URL geändert haben. Stile und Tile-URLs sind nur JavaScript-Konfiguration. Sie können die Anbieter für bestehende Benutzer wechseln Capgo Live-Updates, ohne eine App-Store-Veröffentlichung, solange keine native code Änderungen vorgenommen werden
Wie man entscheidet
- Braucht man Google-Daten und native Leistung auf einem vollbildschirmigen Map: behalten Sie
@capacitor/google-maps. - Braucht man benutzerdefinierte Stile, keine Google-Billing und eine Map, die wie HTML verhält: MapLibre GL JS
- Braucht man eine einfache Map mit einigen Markern: Leaflet
- Braucht man Googles Aussehen in einer scrollenden Layout: Google Maps JS API im WebView
Welchen Sie auch immer wählen, testen Sie es auf einem geringbeschleunigten Android-Gerät frühzeitig. Für mehr native Bausteine, durchsuchen Sie das Capgo Plugin-Verzeichnis.
