Gli overlay del suolo sono sovrapposizioni di immagini legate alle coordinate di latitudine/longitudine, che si spostano quando trascini o esegui lo zoom sulla mappa.
Esempi di codice
Il repository ApiDemos su GitHub include un esempio che mostra gli overlay a livello di terra:
- GroundOverlayDemoActivity - Java: funzionalità e ascoltatori di overlay del suolo in Java
- GroundOverlayDemoActivity - Kotlin: funzionalità di sovrapposizione del suolo e ascoltatori in Kotlin
Introduzione
Un overlay del suolo è un'immagine fissata a una mappa. A differenza degli indicatori, le sovrapposizioni del suolo sono orientate in base alla superficie terrestre anziché allo schermo, pertanto la rotazione, l'inclinazione o lo zoom della mappa cambiano l'orientamento dell'immagine. Gli overlay del suolo sono utili quando vuoi correggere una singola immagine in un'area della mappa. Se vuoi aggiungere immagini estese che coprano gran parte della mappa, ti consigliamo di utilizzare un overlay riquadro.
Aggiungere un overlay
Per aggiungere un elemento GroundOverlay
, crea un oggetto GroundOverlayOptions
che definisce sia un'immagine sia una posizione. Puoi anche specificare impostazioni aggiuntive
che influiranno sul posizionamento dell'immagine sulla mappa. Dopo aver definito le opzioni necessarie, passa l'oggetto al metodo GoogleMap.addGroundOverlay()
per aggiungere l'immagine alla mappa. Il metodo addGroundOverlay()
restituisce un oggetto GroundOverlay
. Devi conservare un riferimento a questo oggetto se vuoi modificarlo in seguito.
Procedura dettagliata:
- Crea l'istanza di un nuovo oggetto
GroundOverlayOptions
- Specifica l'immagine come
BitmapDescriptor
. - Imposta la posizione dell'immagine utilizzando uno dei metodi disponibili:
position(LatLng location, float width, float height)
position(LatLng location, float width)
positionFromBounds(LatLngBounds bounds)
- Imposta eventuali proprietà facoltative, ad esempio
transparency
, come preferisci. - Chiama
GoogleMap.addGroundOverlay()
per aggiungere l'immagine alla mappa.
L'esempio seguente mostra come aggiungere un overlay del suolo a un oggetto GoogleMap
esistente.
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)
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);
Se vuoi modificare o rimuovere un overlay al suolo dopo averlo aggiunto alla mappa, assicurati di mantenere l'oggetto GroundOverlay
. Puoi
modificare l'overlay in un secondo momento apportando modifiche a questo oggetto.
Kotlin
// Add an overlay to the map, retaining a handle to the GroundOverlay object. val imageOverlay = map.addGroundOverlay(newarkMap)
Java
// Add an overlay to the map, retaining a handle to the GroundOverlay object. GroundOverlay imageOverlay = map.addGroundOverlay(newarkMap);
Rimuovere un overlay
Puoi rimuovere un overlay del suolo con il metodo GroundOverlay.remove()
.
Kotlin
imageOverlay?.remove()
Java
imageOverlay.remove();
Modificare un overlay
Puoi modificare l'immagine overlay del suolo dopo che è stata aggiunta alla mappa con il metodo GroundOverlay.setImage(BitmapDescriptor)
.
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))
Java
// Update the GroundOverlay with a new image of the same dimension imageOverlay.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922));
Il metodo setImage()
sostituirà l'immagine esistente con un'altra immagine delle stesse dimensioni.
Posizionamento di una sovrapposizione del suolo
Esistono due modi per specificare la posizione dell'overlay del suolo:
- Utilizzare un elemento
LatLng
per centrare l'overlay e impostare le dimensioni in metri per specificare le dimensioni dell'immagine. - Utilizzo di un elemento
LatLngBounds
per specificare gli angoli nord-est e sud-ovest dell'immagine.
Devi specificare la posizione dell'overlay del suolo prima che venga aggiunto alla mappa.
Usa la posizione per posizionare un'immagine
Quando aggiungi l'immagine, specifichi un LatLng a cui fissare l'ancoraggio e la larghezza dell'overlay (in metri). Per impostazione predefinita, anchor
si trova al centro dell'immagine. Facoltativamente, puoi specificare l'altezza dell'overlay (in metri). Se
non specifichi l'altezza dell'overlay, questa verrà calcolata automaticamente per mantenere le proporzioni dell'immagine.
Il codice riportato di seguito inserisce un'immagine nella posizione 40.714086, -74.228697
di 8,6 km di larghezza per 6,5 km di altezza. L'immagine è ancorata in basso a sinistra.
Kotlin
val newarkMap = GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) .anchor(0f, 1f) .position(LatLng(40.714086, -74.228697), 8600f, 6500f)
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);
Utilizza latLngBounds per posizionare un'immagine
Devi fornire un elemento LatLngBounds
che contenga l'immagine. L'elemento
LatLngBounds
imposta gli angoli nord-est e sud-ovest dell'immagine. Quando
l'immagine viene disegnata sulla mappa, verrà ruotata per adattarla ai margini. Se i limiti non corrispondono alle proporzioni originali, l'immagine sarà inclinata.
Il codice riportato di seguito posiziona un'immagine sulla mappa con l'angolo a sud-ovest limitato a
40.712216,-74.22655
e l'angolo a nord-est limitato a
40.773941, -74.12544
.
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)
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);
Associare i dati a un overlay del suolo
Puoi chiamare GroundOverlay.setTag()
per archiviare un oggetto dati arbitrario con un overlay al suolo e recuperare l'oggetto dati utilizzando GroundOverlay.getTag()
.
Il seguente esempio di codice memorizza una descrizione della stringa con un overlay del suolo:
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"
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");
Di seguito sono riportati alcuni esempi di scenari in cui è utile archiviare e recuperare dati con gli overlay del suolo:
- La tua app può offrire diversi overlay del terreno, pertanto dovresti trattarli in modo diverso a seconda del clic dell'utente.
- Potresti interfacciarti con un sistema che dispone di identificatori di record univoci, in cui gli overlay rappresentano record specifici in quel sistema.
- I dati dell'overlay possono indicare una priorità per determinare lo z-index per l'overlay.
Gestire gli eventi in overlay del suolo
Per impostazione predefinita, non è possibile fare clic
sugli overlay al suolo. Puoi abilitare e disabilitare la cliccabilità chiamando
GroundOverlay.setClickable(boolean)
.
Utilizza un elemento OnGroundOverlayClickListener
per ascoltare gli eventi di clic su un overlay al suolo cliccabile. Per impostare questo listener sulla mappa, chiama GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener)
.
Quando un utente fa clic su un overlay del suolo, riceverai un callback onGroundOverlayClick(GroundOverlay)
.