Boden-Overlays sind Bild-Overlays, die an Breiten- und Längengrad gebunden sind, sodass sie sich beim Ziehen und Zoomen der Karte mitbewegen.
Codebeispiele
Das ApiDemos-Repository auf GitHub enthält ein Beispiel für Boden-Overlays:
- GroundOverlayDemoActivity – Java: Boden-Overlay-Funktionen und ‑Listener in Java
- GroundOverlayDemoActivity – Kotlin: Boden-Overlay-Funktionen und ‑Listener in Kotlin
Einführung
Ein Boden-Overlay ist ein Bild, das auf einer Karte fixiert ist. Im Unterschied zu Markierungen sind Boden-Overlays auf die Erdoberfläche und nicht auf den Bildschirm ausgerichtet. Deshalb wirkt sich das Drehen, Neigen oder Zoomen der Karte auf die Ausrichtung des Bilds aus. Mit Boden-Overlays kann ein einzelnes Bild an einem Punkt der Karte fixiert werden. Wenn du umfangreiches Bildmaterial hinzufügen möchtest, das einen großen Teil der Karte abdeckt, solltest du es mit einem Kachel-Overlay versuchen.
Overlay hinzufügen
Um ein GroundOverlay
hinzuzufügen, erstellst du ein GroundOverlayOptions
-Objekt, das sowohl ein Bild als auch eine Position definiert. Du kannst außerdem zusätzliche Einstellungen angeben, die die Positionierung des Bilds auf der Karte beeinflussen. Nachdem du die erforderlichen Optionen definiert hast, übergibst du das Objekt an die GoogleMap.addGroundOverlay()
-Methode, um das Bild der Karte hinzuzufügen. Über die addGroundOverlay()
-Methode wird ein GroundOverlay
-Objekt zurückgegeben. Ein Verweis auf dieses Objekt sollte beibehalten werden, falls du es später ändern möchtest.
Schritte:
- Instanziiere ein neues
GroundOverlayOptions
-Objekt. - Gib das Bild als
BitmapDescriptor
an. - Lege die Position des Bilds mithilfe einer der verfügbaren Methoden fest:
position(LatLng location, float width, float height)
position(LatLng location, float width)
positionFromBounds(LatLngBounds bounds)
- Lege bei Bedarf optionale Eigenschaften wie z. B.
transparency
fest. - Rufe
GoogleMap.addGroundOverlay()
auf, um das Bild zur Karte hinzuzufügen.
Im folgenden Beispiel siehst du, wie ein Boden-Overlay einem vorhandenen GoogleMap
-Objekt hinzugefügt wird:
Java
LatLng newarkLatLng = new LatLng(40.714086, -74.228697); GroundOverlayOptions newarkMap = new GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) .position(newarkLatLng, 8600f, 6500f); map.addGroundOverlay(newarkMap);
Kotlin
val newarkLatLng = LatLng(40.714086, -74.228697) val newarkMap = GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) .position(newarkLatLng, 8600f, 6500f) map.addGroundOverlay(newarkMap)
Wenn du ein Boden-Overlay ändern oder entfernen möchtest, nachdem du es der Karte hinzugefügt hast, muss das Objekt GroundOverlay
beibehalten werden. Du kannst das Overlay später über dieses Objekt ändern.
Java
// Add an overlay to the map, retaining a handle to the GroundOverlay object. GroundOverlay imageOverlay = map.addGroundOverlay(newarkMap);
Kotlin
// Add an overlay to the map, retaining a handle to the GroundOverlay object. val imageOverlay = map.addGroundOverlay(newarkMap)
Overlay entfernen
Du kannst ein Boden-Overlay mit der Methode GroundOverlay.remove()
entfernen.
Java
imageOverlay.remove();
Kotlin
imageOverlay?.remove()
Overlay ändern
Du kannst das Boden-Overlay-Bild ändern, nachdem es der Karte mit der Methode GroundOverlay.setImage(BitmapDescriptor)
hinzugefügt wurde.
Java
// Update the GroundOverlay with a new image of the same dimension imageOverlay.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922));
Kotlin
// Update the GroundOverlay with a new image of the same dimension // Update the GroundOverlay with a new image of the same dimension imageOverlay?.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
Bei der Methode setImage()
wird das vorhandene Bild durch ein anderes Bild derselben Größe ersetzt.
Boden-Overlay positionieren
Es gibt zwei Möglichkeiten, um Boden-Overlays zu positionieren.
- Du kannst
LatLng
verwenden, um das Overlay zu zentrieren, und Abmessungen in Metern anführen, um die Bildgröße anzugeben. - Verwende
LatLngBounds
, um die Nordost- und Südwestecke des Bilds anzugeben.
Du musst die Position des Boden-Overlays angeben, bevor du es der Karte hinzufügst.
Bild mithilfe eines Standorts positionieren
Beim Hinzufügen des Bilds gibst du einen LatLng-Wert zum Fixieren des Ankers sowie die Breite des Overlays in Metern an. Die Position anchor
befindet sich standardmäßig in der Mitte des Bilds. Optional kannst du die Höhe des Overlays (in Metern) angeben. Wenn du die Höhe des Overlays nicht angibst, wird sie automatisch unter Beibehaltung des Seitenverhältnisses des Bilds berechnet.
Durch den unten stehenden Code wird an der Position 40.714086, -74.228697
ein Bild platziert, das 8,6 km breit und 6,5 km hoch ist. Das Bild wird unten links verankert.
Java
GroundOverlayOptions newarkMap = new GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) .anchor(0, 1) .position(new LatLng(40.714086, -74.228697), 8600f, 6500f);
Kotlin
val newarkMap = GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) .anchor(0f, 1f) .position(LatLng(40.714086, -74.228697), 8600f, 6500f)
Bild mit „LatLngBounds“ positionieren
Du stellst ein LatLngBounds
bereit, das das Bild enthält. Über LatLngBounds
werden die Nordost- und die Südwestecke des Bilds festgelegt. Beim Zeichnen des Bilds auf der Karte wird es so gedreht, dass es in die Begrenzungen passt. Wenn die Begrenzungen nicht dem ursprünglichen Seitenverhältnis entsprechen, wird das Bild verzerrt dargestellt.
Durch den unten stehenden Code wird auf der Karte ein Bild platziert, dessen Südwest- und Nordostecke sich bei 40.712216,-74.22655
bzw. 40.773941, -74.12544
befinden.
Java
LatLngBounds newarkBounds = new LatLngBounds( new LatLng(40.712216, -74.22655), // South west corner new LatLng(40.773941, -74.12544)); // North east corner GroundOverlayOptions newarkMap = new GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) .positionFromBounds(newarkBounds);
Kotlin
val newarkBounds = LatLngBounds( LatLng(40.712216, -74.22655), // South west corner LatLng(40.773941, -74.12544) // North east corner ) val newarkMap = GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) .positionFromBounds(newarkBounds)
Daten mit einem Boden-Overlay verknüpfen
Du kannst GroundOverlay.setTag()
aufrufen, um ein beliebiges Datenobjekt mit einem Boden-Overlay zu speichern, und das Datenobjekt mit GroundOverlay.getTag()
abrufen.
Im folgenden Codebeispiel wird eine Stringbeschreibung mit einem Boden-Overlay gespeichert:
Java
GroundOverlay sydneyGroundOverlay = map.addGroundOverlay(new GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge)) .position(new LatLng(-33.873, 151.206), 100) .clickable(true)); sydneyGroundOverlay.setTag("Sydney");
Kotlin
val sydneyGroundOverlay = map.addGroundOverlay( GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge)) .position(LatLng(-33.873, 151.206), 100f) .clickable(true) ) sydneyGroundOverlay?.tag = "Sydney"
Nachfolgend sind einige Beispiele für Szenarien aufgeführt, in denen es nützlich ist, Daten mit Boden-Overlays zu speichern und abzurufen:
- Deine App deckt möglicherweise verschiedene Boden-Overlays ab, die unterschiedlich behandelt werden sollen, wenn der Nutzer darauf klickt.
- Du verfügst möglicherweise über eine Schnittstelle mit einem System, in dem es eindeutige Datensatzbezeichner gibt, wobei die Overlays spezifische Datensätze in diesem System darstellen.
- Mithilfe von Overlay-Daten kann eine Priorität angegeben werden, um den Z-Index für das Overlay zu ermitteln.
Boden-Overlay-Ereignisse verarbeiten
Boden-Overlays sind standardmäßig nicht anklickbar. Das kann durch Aufrufen von GroundOverlay.setClickable(boolean)
aktiviert oder deaktiviert werden.
Mithilfe von OnGroundOverlayClickListener
kannst du Klickereignisse auf ein anklickbares Boden-Overlay erfassen. Rufe GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener)
auf, um diesen Listener auf der Karte festzulegen.
Wenn ein Nutzer auf ein Boden-Overlay klickt, erhältst du eine onGroundOverlayClick(GroundOverlay)
-Callback.