Overlay al suolo

Seleziona la piattaforma: Android iOS JavaScript

Gli overlay al suolo sono overlay immagine collegati 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 del terreno:

• GroundOverlayDemoActivity - Java: funzionalità di overlay e ascoltatori di terra in Java
• GroundOverlayDemoActivity - Kotlin: funzionalità di sovrapposizione del suolo e ascoltatori in Kotlin

Introduzione

Un overlay del suolo è un'immagine fissa su una mappa. A differenza degli indicatori, le sovrapposizioni al suolo sono orientate verso la superficie terrestre anziché lo schermo, pertanto la rotazione, l'inclinazione o lo zoom della mappa modificano l'orientamento dell'immagine. Gli overlay al suolo sono utili quando vuoi correggere una singola immagine in un'area della mappa. Se vuoi aggiungere immagini estese che coprano un'ampia parte della mappa, ti consigliamo di utilizzare un overlay riquadro.

Aggiungere un overlay

Per aggiungere un elemento GroundOverlay, crea un oggetto GroundOverlayOptions che definisca sia un'immagine sia una posizione. Facoltativamente, puoi specificare impostazioni aggiuntive che influiranno sul posizionamento dell'immagine sulla mappa. Una volta definite 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 due lati. Puoi evitare questa conversione utilizzando un'immagine originale con dimensioni che corrispondono a due potenze, ad esempio 128 x 512 o 1024 x 1024.

Passo passo:

1. Crea l'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, come preferisci.
5. Chiama GoogleMap.addGroundOverlay() per aggiungere l'immagine alla mappa.

L'esempio seguente mostra come aggiungere un overlay del suolo 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 un overlay del 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.

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 un overlay

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

Java

imageOverlay.remove();

      

Kotlin

imageOverlay?.remove()

      

Modificare un overlay

Puoi modificare l'immagine overlay del suolo dopo che è stata 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 delle stesse dimensioni.

Posizionamento di una sovrapposizione del suolo

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

• Utilizzare LatLng per centrare l'overlay e le dimensioni in metri per specificare la dimensione dell'immagine.
• Utilizzare 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.

Utilizza la posizione per posizionare un'immagine

Quando aggiungi l'immagine, specifichi un LatLng a cui sarà fisso l'ancoraggio e la larghezza dell'overlay (in metri). Per impostazione predefinita, anchor si trova al centro dell'immagine. Se vuoi, 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 posiziona un'immagine nella posizione 40.714086, -74.228697, larga 8,6 km e alta 6,5 km. 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)

      

Utilizza i limiti LatLng 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 limiti. Se i limiti non corrispondono alle proporzioni originali, l'immagine verrà distorta.

Il codice riportato di seguito posiziona un'immagine sulla mappa con l'angolo sud-ovest collegato a 40.712216,-74.22655 e l'angolo nord-est associato 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 i dati a una sovrapposizione 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 archivia una descrizione della stringa con un overlay 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 in cui è utile archiviare e recuperare dati con overlay al suolo:

• La tua app può offrire diversi overlay del suolo e vuoi trattarli in modo diverso quando l'utente fa clic su di essi.
• Potresti interfacciarti con un sistema dotato 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 al suolo

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

Usa una 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, ricevi un callback onGroundOverlayClick(GroundOverlay).

Nota: se più overlay o forme (indicatori, polilinee, poligoni, cerchi e/o overlay al suolo) sono sovrapposti, l'evento clic viene fatto scorrere prima nel gruppo di indicatori, quindi viene attivato per altri overlay o forme cliccabili in base ai relativi 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 più bassi. Scopri di più sugli eventi z-index e sugli eventi di clic dell'indicatore.