Overlay del suolo

Seleziona la piattaforma: Android iOS JavaScript

Gli overlay del suolo sono overlay immagine collegati alle coordinate di latitudine/longitudine, quindi si spostano quando trascini o ingrandisci la mappa.

Esempi di codice

Il repository ApiDemos su GitHub include un esempio che mostra i overlay del terreno:

• GroundOverlayDemoActivity - Java: funzionalità e listener di overlay del terreno in Java
• GroundOverlayDemoActivity - Kotlin: funzionalità e listener di ground overlay in Kotlin

Introduzione

Un overlay del terreno è un'immagine fissata a una mappa. A differenza dei marker, gli overlay del terreno sono orientati rispetto alla superficie della Terra anziché allo schermo, quindi la rotazione, l'inclinazione o lo zoom della mappa cambieranno l'orientamento dell'immagine. Le sovrapposizioni al suolo sono utili quando vuoi fissare una singola immagine in un'area della mappa. Se vuoi aggiungere immagini estese che coprono gran parte della mappa, ti consigliamo di utilizzare un overlay di riquadri.

Aggiungi un overlay

Per aggiungere un GroundOverlay, crea un oggetto GroundOverlayOptions che definisca sia un'immagine sia una posizione. Se vuoi, puoi 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 un secondo momento.

Nota: quando l'immagine viene aggiunta alla mappa, viene convertita in un'immagine con lati che sono potenze di due. Puoi evitare questa conversione utilizzando un'immagine originale con dimensioni che sono potenze di due, ad esempio 128 x 512 o 1024 x 1024.

Procedura passo passo:

1. Crea un'istanza di un nuovo oggetto GroundOverlayOptions
2. Specifica l'immagine come BitmapDescriptor.
3. 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)
4. Imposta le proprietà facoltative, ad esempio transparency, in base alle tue esigenze.
5. Chiama GoogleMap.addGroundOverlay() per aggiungere l'immagine alla mappa.

L'esempio seguente mostra come aggiungere un overlay del terreno 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 del terreno dopo averlo aggiunto alla mappa, assicurati di conservare 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);

      

Rimuovi un overlay

Puoi rimuovere un overlay del terreno con il metodo GroundOverlay.remove().

Kotlin

imageOverlay?.remove()

      

Java

imageOverlay.remove();

      

Modifica un overlay

Puoi modificare l'immagine di overlay del terreno dopo averla aggiunta alla mappa con il metodo GroundOverlay.setImage(BitmapDescriptor).

Kotlin

// 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.

Posiziona un overlay del terreno

Esistono due modi per specificare la posizione dell'overlay del terreno:

• Utilizzando un LatLng per centrare l'overlay e le dimensioni in metri per specificare le dimensioni dell'immagine.
• Utilizzando un LatLngBounds per specificare gli angoli nord-est e sud-ovest dell'immagine.

Devi specificare la posizione dell'overlay del terreno prima di aggiungerlo alla mappa.

Utilizza la posizione per posizionare un'immagine

Quando aggiungi l'immagine, specifichi un LatLng a cui verrà fissata l'ancora e la larghezza dell'overlay (in metri). Il valore predefinito di anchor è il centro dell'immagine. Se vuoi, puoi fornire l'altezza dell'overlay (in metri). Se non fornisci l'altezza dell'overlay, questa verrà calcolata automaticamente per preservare le proporzioni dell'immagine.

Il codice seguente posiziona un'immagine nella posizione 40.714086, -74.228697 con una larghezza di 8,6 km e un'altezza di 6,5 km. 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

Fornisci un LatLngBounds che contiene l'immagine. LatLngBounds imposta gli angoli nord-est e sud-ovest dell'immagine. Quando l'immagine viene disegnata sulla mappa, viene ruotata per adattarsi ai limiti. Se i limiti non corrispondono alle proporzioni originali, l'immagine verrà distorta.

Il codice seguente posiziona un'immagine sulla mappa con l'angolo sud-ovest associato a 40.712216,-74.22655 e l'angolo nord-est associato 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);

      

Associa i dati a un overlay del terreno

Puoi chiamare GroundOverlay.setTag() per archiviare un oggetto dati arbitrario con una sovrapposizione al suolo e recuperarlo utilizzando GroundOverlay.getTag().

Il seguente esempio di codice memorizza una descrizione di stringa con un overlay del terreno:

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");

      

Ecco alcuni esempi di scenari in cui è utile archiviare e recuperare i dati con overlay sul terreno:

• La tua app potrebbe supportare diversi overlay del terreno e potresti volerli trattare in modo diverso quando l'utente li seleziona.
• Potresti interfacciarti con un sistema che ha 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 dell'overlay.

Gestisci gli eventi di overlay del terreno

Per impostazione predefinita, gli overlay del terreno non sono cliccabili. Puoi attivare e disattivare la cliccabilità chiamando GroundOverlay.setClickable(boolean).

Utilizza un OnGroundOverlayClickListener per ascoltare gli eventi di clic su un overlay del terreno cliccabile. Per impostare questo listener sulla mappa, chiama GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener). Quando un utente fa clic su un overlay del terreno, riceverai un callback onGroundOverlayClick(GroundOverlay).

Nota: se più overlay o forme (indicatori, polilinee, poligoni, cerchi e/o overlay del terreno) sono sovrapposti, l'evento di clic viene applicato prima al cluster di indicatori, poi viene attivato per altri overlay o forme cliccabili in base ai relativi valori z-index. Per ogni clic viene attivato al massimo un evento. In altre parole, il clic non viene trasmesso agli overlay o alle forme con valori di indice z inferiori. Scopri di più su z-index degli indicatori ed eventi di clic.