Indicatori

Gli indicatori identificano le posizioni sulla mappa. L'indicatore predefinito utilizza un'icona standard, comune all'aspetto di Google Maps. È possibile modificare il colore, l'immagine o il punto di ancoraggio dell'icona tramite l'API. Gli indicatori sono oggetti di tipo Marker e vengono aggiunti alla mappa con il metodo GoogleMap.addMarker(markerOptions).

Gli indicatori sono progettati per essere interattivi. Per impostazione predefinita, ricevono eventi click e vengono spesso utilizzati con i listener di eventi per visualizzare le finestre informative. Se imposti la proprietà draggable di un indicatore su true, l'utente può modificarne la posizione. Tieni premuto a lungo per attivare la possibilità di spostare l'indicatore.

Per impostazione predefinita, quando un utente tocca un indicatore, la barra degli strumenti della mappa viene visualizzata in basso a destra, consentendo all'utente di accedere rapidamente all'app mobile Google Maps. Puoi disattivare la barra degli strumenti. Per ulteriori informazioni, consulta la guida ai controlli.

Aggiungi un indicatore

L'esempio seguente mostra come aggiungere un indicatore a una mappa. L'indicatore viene creato alle coordinate -33.852,151.211 (Sydney, Australia) e visualizza la stringa "Indicatore a Sydney" in una finestra informativa quando viene fatto clic.

// Add a marker in Sydney, Australia,
// and move the map's camera to the same location.
val sydney = LatLng(-33.852, 151.211)
val marker = map.addMarker(
    MarkerOptions()
        .position(sydney)
        .title("Marker in Sydney")
)
marker?.let {
    val position = it.position
    val title = it.title
    val snippet = it.snippet
    val isDraggable = it.isDraggable
    val isFlat = it.isFlat
    val isVisible = it.isVisible
    val alpha = it.alpha
    val rotation = it.rotation
    val zIndex = it.zIndex
}
map.moveCamera(CameraUpdateFactory.newLatLng(sydney))

      

// Add a marker in Sydney, Australia,
// and move the map's camera to the same location.
LatLng sydney = new LatLng(-33.852, 151.211);
Marker marker = map.addMarker(new MarkerOptions()
    .position(sydney)
    .title("Marker in Sydney"));
map.moveCamera(CameraUpdateFactory.newLatLng(sydney));

      

Visualizza informazioni aggiuntive su un indicatore

Un requisito comune è mostrare informazioni aggiuntive su un luogo o una posizione quando l'utente tocca un indicatore sulla mappa. Consulta la guida alle finestre informative.

Associa i dati a un indicatore

Puoi archiviare un oggetto dati arbitrario con un indicatore utilizzando Marker.setTag() e recuperare l'oggetto dati utilizzando Marker.getTag(). L'esempio seguente mostra come contare il numero di volte in cui è stato fatto clic su un indicatore utilizzando i tag:

val PERTH = LatLng(-31.952854, 115.857342)
val SYDNEY = LatLng(-33.87365, 151.20689)
val BRISBANE = LatLng(-27.47093, 153.0235)

val markerPerth = map.addMarker(
    MarkerOptions()
        .position(PERTH)
        .title("Perth")
)
markerPerth?.tag = 0

val markerSydney = map.addMarker(
    MarkerOptions()
        .position(SYDNEY)
        .title("Sydney")
)
markerSydney?.tag = 0

val markerBrisbane = map.addMarker(
    MarkerOptions()
        .position(BRISBANE)
        .title("Brisbane")
)
markerBrisbane?.tag = 0

// Set a listener for marker click.
map.setOnMarkerClickListener { marker ->
    // Retrieve the data from the marker.
    val clickCount = marker.tag as? Int

    // Check if a click count was set, then display the click count.
    clickCount?.let {
        val newClickCount = it + 1
        marker.tag = newClickCount
        Toast.makeText(
            context,
            "${marker.title} has been clicked $newClickCount times.",
            Toast.LENGTH_SHORT
        ).show()
    }

    // Return false to indicate default behavior.
    false
}

      

final LatLng PERTH = new LatLng(-31.952854, 115.857342);
final LatLng SYDNEY = new LatLng(-33.87365, 151.20689);
final LatLng BRISBANE = new LatLng(-27.47093, 153.0235);

Marker markerPerth = map.addMarker(new MarkerOptions()
    .position(PERTH)
    .title("Perth"));
markerPerth.setTag(0);

Marker markerSydney = map.addMarker(new MarkerOptions()
    .position(SYDNEY)
    .title("Sydney"));
markerSydney.setTag(0);

Marker markerBrisbane = map.addMarker(new MarkerOptions()
    .position(BRISBANE)
    .title("Brisbane"));
markerBrisbane.setTag(0);

// Set a listener for marker click.
map.setOnMarkerClickListener(new GoogleMap.OnMarkerClickListener() {
    @Override
    public boolean onMarkerClick(final Marker marker) {
        // Retrieve the data from the marker.
        Integer clickCount = (Integer) marker.getTag();

        // Check if a click count was set, then display the click count.
        if (clickCount != null) {
            clickCount = clickCount + 1;
            marker.setTag(clickCount);
            Toast.makeText(context,
                marker.getTitle() + " has been clicked " + clickCount + " times.",
                Toast.LENGTH_SHORT).show();
        }

        // Return false to indicate default behavior should occur.
        return false;
    }
});

      

Di seguito sono riportati alcuni esempi di scenari in cui è utile archiviare e recuperare i dati con gli indicatori:

• La tua app potrebbe supportare diversi tipi di indicatori e vuoi trattarli in modo diverso quando l'utente fa clic su di essi. Per farlo, puoi archiviare una String con l'indicatore che indica il tipo.
• Potresti interfacciarti con un sistema che ha identificatori di record univoci, in cui gli indicatori rappresentano record specifici in quel sistema.
• I dati dell'indicatore possono indicare una priorità da utilizzare per decidere lo z-index di un indicatore.

Rendi trascinabile un indicatore

Puoi riposizionare un indicatore dopo averlo aggiunto alla mappa, a condizione che la proprietà draggable sia impostata su true. Tieni premuto a lungo l'indicatore per attivare il trascinamento. Quando sollevi il dito dallo schermo, l'indicatore rimane in quella posizione.

Per impostazione predefinita, gli indicatori non sono trascinabili. Devi impostare esplicitamente l'indicatore come trascinabile con MarkerOptions.draggable(boolean) prima di aggiungerlo alla mappa o Marker.setDraggable(boolean) dopo averlo aggiunto alla mappa. Puoi ascoltare gli eventi di trascinamento sull'indicatore, come descritto in Eventi di trascinamento dell'indicatore.

Lo snippet seguente aggiunge un indicatore trascinabile a Perth, in Australia.

val perthLocation = LatLng(-31.90, 115.86)
val perth = map.addMarker(
    MarkerOptions()
        .position(perthLocation)
        .draggable(true)
)
map.moveCamera(com.google.android.gms.maps.CameraUpdateFactory.newLatLngZoom(perthLocation, 10f))

      

final LatLng perthLocation = new LatLng(-31.90, 115.86);
Marker perth = map.addMarker(
    new MarkerOptions()
        .position(perthLocation)
        .draggable(true));
map.moveCamera(com.google.android.gms.maps.CameraUpdateFactory.newLatLngZoom(perthLocation, 10f));

      

Personalizza un indicatore

Questo video mostra i modi per utilizzare gli indicatori per visualizzare le posizioni su una mappa.

Gli indicatori possono definire un'immagine personalizzata da mostrare al posto dell'icona predefinita. La definizione di un'icona comporta l'impostazione di una serie di proprietà che influiscono sul comportamento visivo dell'indicatore.

Gli indicatori supportano la personalizzazione tramite le seguenti proprietà:

Posizione (obbligatoria)

Il LatLng valore per la posizione dell'indicatore sulla mappa. Questa è l'unica proprietà obbligatoria per un oggetto Marker.

Ancoraggio

Il punto dell'immagine che verrà posizionato nella posizione LatLng dell' indicatore. Per impostazione predefinita, è il punto centrale della parte inferiore dell'immagine.

Alpha

Imposta l'opacità dell'indicatore. Il valore predefinito è 1.0.

Titolo

Una stringa visualizzata nella finestra informativa quando l'utente tocca l' indicatore.

Snippet

Testo aggiuntivo visualizzato sotto il titolo.

Icona

Una bitmap visualizzata al posto dell'immagine dell'indicatore predefinita.

Trascinabile

Imposta su true se vuoi consentire all'utente di spostare l'indicatore. Il valore predefinito è false.

Visibile

Imposta su false per rendere invisibile l'indicatore. Il valore predefinito è true.

Orientamento piatto o billboard

Per impostazione predefinita, gli indicatori utilizzano un orientamento billboard, il che significa che vengono disegnati orientati verso lo schermo del dispositivo anziché verso la superficie della mappa. La rotazione, l'inclinazione o lo zoom della mappa non modificano l'orientamento del indicatore. Puoi impostare l'orientamento di un indicatore in modo che sia piatto rispetto alla terra. Gli indicatori piatti ruotano quando la mappa viene ruotata e cambiano prospettiva quando la mappa viene inclinata. Come per gli indicatori billboard, gli indicatori piatti mantengono le loro dimensioni quando la mappa viene ingrandita o rimpicciolita.

Rotazione

L'orientamento dell'indicatore, specificato in gradi in senso orario. La posizione predefinita cambia se l'indicatore è piatto. La posizione predefinita per un indicatore piatto è allineata a nord. Quando l'indicatore non è piatto, la posizione predefinita è verso l'alto e la rotazione è tale che l'indicatore sia sempre rivolto verso la fotocamera.

Lo snippet seguente crea un indicatore semplice con l'icona predefinita.

val melbourneLocation = LatLng(-37.813, 144.962)
val melbourne = map.addMarker(
    MarkerOptions()
        .position(melbourneLocation)
)

      

final LatLng melbourneLocation = new LatLng(-37.813, 144.962);
Marker melbourne = map.addMarker(
    new MarkerOptions()
        .position(melbourneLocation));

      

Personalizza il colore dell'indicatore

È possibile personalizzare il colore dell'immagine dell'indicatore predefinita passando un oggetto BitmapDescriptor al metodo icon(). Puoi utilizzare un insieme di colori predefiniti nell'BitmapDescriptorFactory oggetto o impostare un colore dell'indicatore personalizzato con il BitmapDescriptorFactory.defaultMarker(float hue) metodo. La tonalità è un valore compreso tra 0 e 360, che rappresenta i punti su una ruota dei colori.

val melbourneLocation = LatLng(-37.813, 144.962)
val melbourne = map.addMarker(
    MarkerOptions()
        .position(melbourneLocation)
        .icon(BitmapDescriptorFactory.defaultMarker(BitmapDescriptorFactory.HUE_AZURE))
)

      

final LatLng melbourneLocation = new LatLng(-37.813, 144.962);
Marker melbourne = map.addMarker(
    new MarkerOptions()
        .position(melbourneLocation)
        .icon(BitmapDescriptorFactory.defaultMarker(BitmapDescriptorFactory.HUE_AZURE)));

      

Personalizza l'opacità dell'indicatore

Puoi controllare l'opacità di un indicatore con il metodo MarkerOptions.alpha(). L'alpha deve essere specificato come un valore float compreso tra 0.0 e 1.0, dove 0 è completamente trasparente e 1 è completamente opaco.

val melbourneLocation = LatLng(-37.813, 144.962)
val melbourne = map.addMarker(
    MarkerOptions()
        .position(melbourneLocation)
        .alpha(0.7f)
)

      

final LatLng melbourneLocation = new LatLng(-37.813, 144.962);
Marker melbourne = map.addMarker(new MarkerOptions()
    .position(melbourneLocation)
    .alpha(0.7f));

      

Personalizza l'immagine dell'indicatore

Puoi sostituire l'immagine dell'indicatore predefinita con un'immagine dell'indicatore personalizzata, spesso chiamata icona. Le icone personalizzate vengono sempre impostate come BitmapDescriptor e definite utilizzando uno dei metodi della BitmapDescriptorFactory classe.

fromAsset(String assetName)

Crea un indicatore personalizzato utilizzando il nome di un'immagine bitmap nella directory delle risorse.

fromBitmap(Bitmap image)

Crea un indicatore personalizzato da un'immagine bitmap.

fromFile(String fileName)

Crea un'icona personalizzata utilizzando il nome di un file immagine bitmap memorizzato nella memoria interna.

fromPath(String absolutePath)

Crea un indicatore personalizzato da un percorso di file assoluto di un'immagine bitmap.

fromResource(int resourceId)

Crea un indicatore personalizzato utilizzando l'ID risorsa di un'immagine bitmap.

Lo snippet seguente crea un indicatore con un'icona personalizzata.

val melbourneLocation = LatLng(-37.813, 144.962)
val melbourne = map.addMarker(
    MarkerOptions()
        .position(melbourneLocation)
        .title("Melbourne")
        .snippet("Population: 4,137,400")
        .icon(BitmapDescriptorFactory.fromResource(R.drawable.arrow))
)

      

final LatLng melbourneLocation = new LatLng(-37.813, 144.962);
Marker melbourne = map.addMarker(
    new MarkerOptions()
        .position(melbourneLocation)
        .title("Melbourne")
        .snippet("Population: 4,137,400")
        .icon(BitmapDescriptorFactory.fromResource(R.drawable.arrow)));

      

Appiattisci un indicatore

Le icone degli indicatori vengono normalmente disegnate rispetto allo schermo; la rotazione, l'inclinazione o lo zoom della mappa non modificano l'orientamento dell'indicatore. Puoi impostare l'orientamento di un indicatore in modo che sia piatto rispetto alla terra. Gli indicatori orientati in questo modo ruotano quando la mappa viene ruotata e cambiano prospettiva quando la mappa viene inclinata. Gli indicatori piatti mantengono le loro dimensioni quando la mappa viene ingrandita o rimpicciolita.

Per modificare l'orientamento dell'indicatore, imposta la proprietà flat dell'indicatore su true.

val perthLocation = LatLng(-31.90, 115.86)
val perth = map.addMarker(
    MarkerOptions()
        .position(perthLocation)
        .flat(true)
)

      

final LatLng perthLocation = new LatLng(-31.90, 115.86);
Marker perth = map.addMarker(
    new MarkerOptions()
        .position(perthLocation)
        .flat(true));

      

Ruota un indicatore

Puoi ruotare un indicatore attorno al suo punto di ancoraggio con il metodo Marker.setRotation(). La rotazione viene misurata in gradi in senso orario dalla posizione predefinita. Quando l'indicatore è piatto sulla mappa, la posizione predefinita è a nord. Quando l'indicatore non è piatto, la posizione predefinita è verso l'alto e la rotazione è tale che l'indicatore sia sempre rivolto verso la fotocamera.

L'esempio seguente ruota l'indicatore di 90°. Se imposti il punto di ancoraggio su 0.5,0.5, l'indicatore viene ruotato attorno al suo centro anziché alla sua base.

val perthLocation = LatLng(-31.90, 115.86)
val perth = map.addMarker(
    MarkerOptions()
        .position(perthLocation)
        .anchor(0.5f, 0.5f)
        .rotation(90.0f)
)

      

final LatLng perthLocation = new LatLng(-31.90, 115.86);
Marker perth = map.addMarker(
    new MarkerOptions()
        .position(perthLocation)
        .anchor(0.5f,0.5f)
        .rotation(90.0f));

      

Z-index dell'indicatore

Lo z-index specifica l'ordine di sovrapposizione di questo indicatore rispetto ad altri indicatori sulla mappa. Un indicatore con uno z-index elevato viene disegnato sopra gli indicatori con z-index inferiori. Il valore predefinito dello z-index è 0.

Imposta lo z-index sull'oggetto delle opzioni dell'indicatore chiamando MarkerOptions.zIndex(), come mostrato nel seguente snippet di codice:

map.addMarker(
    MarkerOptions()
        .position(LatLng(10.0, 10.0))
        .title("Marker z1")
        .zIndex(1.0f)
)

      

map.addMarker(new MarkerOptions()
    .position(new LatLng(10, 10))
    .title("Marker z1")
    .zIndex(1.0f));

      

Puoi accedere allo z-index dell'indicatore chiamando Marker.getZIndex() e modificarlo chiamando Marker.setZIndex().

Gli indicatori vengono sempre disegnati sopra i livelli di riquadri e altri overlay non indicatori (overlay a terra, polilinee, poligoni e altre forme) indipendentemente dallo z-index degli altri overlay. Gli indicatori sono effettivamente considerati in un gruppo di z-index separato rispetto ad altri overlay.

Scopri di più su l'effetto dello z-index sugli eventi di clic di seguito.

Gestisci gli eventi degli indicatori

L'API di Google Maps ti consente di rimanere in ascolto e rispondere agli eventi degli indicatori. Per ascoltare questi eventi, devi impostare il listener corrispondente sull'oggetto GoogleMap a cui appartengono gli indicatori. Quando l'evento si verifica su uno degli indicatori sulla mappa, viene richiamato il callback del listener con l'oggetto Marker corrispondente passato come parametro. Per confrontare questo oggetto Marker con il tuo riferimento a un oggetto Marker, devi utilizzare equals() e non ==.

Puoi ascoltare i seguenti eventi:

• Eventi di clic sull'indicatore
• Eventi di trascinamento dell'indicatore
• Eventi di clic sulla finestra informativa

Eventi di clic sull'indicatore

Puoi utilizzare un OnMarkerClickListener per ascoltare gli eventi di clic sull'indicatore. Per impostare questo listener sulla mappa, chiama GoogleMap.setOnMarkerClickListener(OnMarkerClickListener). Quando un utente fa clic su un indicatore, viene chiamato onMarkerClick(Marker) e l'indicatore viene passato come argomento. Questo metodo restituisce un valore booleano che indica se hai utilizzato l'evento (ovvero se vuoi sopprimere il comportamento predefinito). Se restituisce false, oltre al comportamento personalizzato si verificherà anche il comportamento predefinito. Il comportamento predefinito per un evento di clic sull'indicatore è mostrare la sua finestra informativa (se disponibile) e spostare la fotocamera in modo che l'indicatore sia centrato sulla mappa.

Effetto dello z-index sugli eventi di clic:

• Quando un utente fa clic su un cluster di indicatori, l'evento di clic viene attivato per l'indicatore con lo z-index più alto.
• Viene attivato al massimo un evento per clic. In altre parole, il clic non viene passato agli indicatori o ad altri overlay con valori di z-index inferiori.
• Se fai clic su un cluster di indicatori, i clic successivi scorrono il cluster, selezionando ciascuno a turno. L'ordine del ciclo dà la priorità prima allo z-index, poi alla prossimità al punto di clic.
• Se l'utente fa clic al di fuori della prossimità del cluster, l'API ricalcola il cluster e reimposta lo stato del ciclo di clic in modo che inizi dall'inizio.
• Gli indicatori sono effettivamente considerati in un gruppo di z-index separato rispetto ad altri overlay o forme (polilinee, poligoni, cerchi e/o overlay a terra), indipendentemente dallo z-index degli altri overlay. Se più indicatori, overlay o forme sono sovrapposti l'uno all'altro, l'evento di clic viene eseguito prima nel cluster di indicatori.

Eventi di trascinamento dell'indicatore

Puoi utilizzare un OnMarkerDragListener per ascoltare gli eventi di trascinamento su un indicatore. Per impostare questo listener sulla mappa, chiama GoogleMap.setOnMarkerDragListener. Per trascinare un indicatore, un utente deve tenerlo premuto a lungo. Quando l'utente solleva il dito dallo schermo, l'indicatore rimane in quella posizione. Quando un indicatore viene trascinato, viene chiamato inizialmente onMarkerDragStart(Marker). Mentre l'indicatore viene trascinato, viene chiamato costantemente onMarkerDrag(Marker). Alla fine del trascinamento viene chiamato onMarkerDragEnd(Marker). Puoi ottenere la posizione dell'indicatore in qualsiasi momento chiamando Marker.getPosition().