Overlay al suolo

Seleziona piattaforma: Android iOS JavaScript

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

Esempi di codice

Il repository APIApi su GitHub include un campione che mostra gli overlay di base:

Introduzione

Un overlay del suolo è un'immagine fissata su una mappa. A differenza degli indicatori, gli overlay al suolo sono orientati verso la superficie terrestre anziché sullo 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 sulla mappa. Se vuoi aggiungere immagini di grandi dimensioni che coprono una vasta porzione della mappa, dovresti considerare un overlay di riquadro.

Aggiungere un overlay

Per aggiungere un GroundOverlay, crea un oggetto GroundOverlayOptions che definisce 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.

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. Se vuoi, puoi impostare le proprietà facoltative, ad esempio transparency.
  5. Chiama GoogleMap.addGroundOverlay() per aggiungere l'immagine alla mappa.

L'esempio seguente mostra come aggiungere un overlay di base 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 all'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 di overlay del suolo 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 immagine delle stesse dimensioni.

Posiziona un overlay del suolo

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

  • 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 dell'overlay del suolo prima di aggiungerlo alla mappa.

Utilizzare la posizione per posizionare un'immagine

Quando aggiungi l'immagine, specifica un valore LatLng su cui verrà fissato l'ancoraggio e la larghezza dell'overlay (in metri). L'impostazione predefinita di anchor è il centro dell'immagine. Se lo desideri, puoi fornire l'altezza della sovrapposizione (in metri). Se non fornisci l'altezza dell'overlay, questa verrà calcolata automaticamente per mantenere le proporzioni dell'immagine.

Il codice riportato di seguito posiziona un'immagine in posizione 40.714086, -74.228697 che è 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)

      

Utilizzare LatLngBounds per posizionare un'immagine

Fornisci una 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 limitato 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 un overlay del suolo

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

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

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 i dati con gli overlay di base:

  • L'app potrebbe supportare diversi tipi di overlay di base e vuoi che vengano trattati in modo diverso quando l'utente fa clic su di essi.
  • Potresti avere un'interfaccia con un sistema che ha identificatori di record univoci, in cui gli overlay rappresentano record specifici nel sistema.
  • 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 di base non sono selezionabili. Puoi abilitare e disabilitare la cliccabilità chiamando GroundOverlay.setClickable(boolean).

Utilizza una OnGroundOverlayClickListener per ascoltare gli eventi relativi ai clic su un overlay di terreno selezionabile. 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).