Overlay al suolo

Seleziona piattaforma: Android iOS JavaScript

Gli overlay al suolo sono overlay di immagini legati alle coordinate di latitudine/longitudine, quindi si spostano quando trascini o esegui lo zoom sulla mappa.

Esempi di codice

Il repository APIDemos su GitHub include un esempio che dimostra gli overlay del terreno:

• GroundOverlayDemoActivity - Java: funzionalità e overlay degli overlay del terreno in Java
• GroundOverlayDemoActivity - Kotlin: funzionalità di overlay del terreno e ascoltatori in Kotlin

Introduzione

Un overlay del suolo è un'immagine fissata su una mappa. A differenza degli indicatori, le sovrapposizioni del terreno sono orientate verso la superficie terrestre anziché sullo 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 una zona 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 GroundOverlay, crea un oggetto GroundOverlayOptions che definisca sia un'immagine sia una posizione. Facoltativamente, puoi specificare impostazioni aggiuntive che influiscono 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, verrà convertita in un'immagine con lati di potenza pari a due. Puoi evitare questa conversione utilizzando un'immagine originale con dimensioni di due potenze, ad esempio 128 x 512 o 1024 x 1024.

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 eventuali proprietà facoltative, come transparency.
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.

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)

      

Se vuoi modificare o rimuovere una sovrapposizione del terreno dopo averla aggiunta alla mappa, assicurati di conservare l'oggetto GroundOverlay. Puoi modificare l'overlay in seguito apportando modifiche a questo oggetto.

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)

      

Rimuovere una sovrapposizione

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

Java

imageOverlay.remove();

      

Kotlin

imageOverlay?.remove()

      

Modificare un overlay

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

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

      

Il metodo setImage() sostituirà l'immagine esistente con un'altra con le stesse dimensioni.

Posiziona un overlay del suolo

Esistono due modi per specificare la posizione della sovrapposizione del terreno:

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

Devi specificare la posizione della sovrapposizione del terreno prima che venga aggiunta alla mappa.

Usa la posizione per posizionare un'immagine

Quando aggiungi l'immagine, specifica un valore LatLng a cui fissare l'ancoraggio e la larghezza dell'overlay (in metri). L'impostazione predefinita di anchor è il centro dell'immagine. Puoi eventualmente specificare l'altezza della sovrapposizione (in metri). Se non specifichi l'altezza della sovrapposizione, questa verrà calcolata automaticamente per preservare le proporzioni dell'immagine.

Il codice riportato di seguito posiziona un'immagine nella posizione 40.714086, -74.228697 che misura 8,6 km di larghezza per 6,5 km di altezza. L'immagine è ancorata in basso a sinistra.

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)

      

Utilizzare LatLngBounds per posizionare un'immagine

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

Il codice riportato di seguito posiziona un'immagine sulla mappa con l'angolo sud-ovest rivolto a 40.712216,-74.22655 e l'angolo nord-est rivolto a 40.773941, -74.12544.

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)

      

Associare dati a un overlay del suolo

Puoi chiamare GroundOverlay.setTag() per archiviare un oggetto dati arbitrario con un overlay di terra e recuperare l'oggetto dati utilizzando GroundOverlay.getTag().

L'esempio di codice riportato di seguito memorizza una stringa con una sovrapposizione al suolo:

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"

      

Di seguito sono riportati alcuni esempi di scenari utili per archiviare e recuperare i dati con overlay di terra:

• L'app può soddisfare diversi tipi di overlay del terreno e vuoi che vengano trattati in modo diverso quando l'utente fa clic su di essi.
• Potresti interfacciarti con un sistema con identificatori di record univoci, in cui gli overlay rappresentano record specifici nel sistema in questione.
• I dati in overlay possono indicare una priorità per determinare lo z-index per l'overlay.

Gestire gli eventi di overlay del suolo

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

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

Nota: se più overlay o forme (indicatori, polilinee, poligoni, cerchi e/o overlay del terreno) vengono sovrapposto uno sopra l'altro, l'evento di clic viene visualizzato prima in loop nel cluster di indicatori, poi viene attivato per altri overlay o forme cliccabili in base ai loro valori z-index. Viene attivato al massimo un evento per clic. In altre parole, il clic non viene trasmesso agli overlay o alle forme con valori z-index inferiori. Scopri di più sugli indicatori z-index e sugli eventi di clic.