Boden-Overlays

Plattform auswählen: Android iOS JavaScript

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.

Hinweis: Wenn das Bild der Karte hinzugefügt wird, wird es in ein Bild umgewandelt, dessen Seitenlängen Potenzen von zwei sind. Du kannst diese Umwandlung vermeiden, indem du Bilder verwendest, deren Abmessungen von vornherein Potenzen von zwei sind, zum Beispiel 128 × 512 oder 1.024 × 1.024.

Schritte:

1. Instanziiere ein neues GroundOverlayOptions-Objekt.
2. Gib das Bild als BitmapDescriptor an.
3. 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)
4. Lege bei Bedarf optionale Eigenschaften wie z. B. transparency fest.
5. 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.

Hinweis: Wenn mehrere Overlays oder Formen (Markierungen, Polylinien, Polygone, Kreise und/oder Boden-Overlays) einander überlagern, wird das Klickereignis zuerst durch den Markierungscluster geleitet. Anschließend wird es nacheinander für andere anklickbare Overlays oder Formen basierend auf ihren Z-Index-Werten ausgelöst. Pro Klick wird maximal ein Ereignis ausgelöst. Das heißt, der Klick wird nicht an die Overlays oder Formen mit niedrigeren Z-Index-Werten weitergegeben. Weitere Informationen zum Z-Index von Markierungen und zu Klickereignissen