Indicatori

Seleziona la piattaforma: Android iOS JavaScript

Gli indicatori segnalano singole posizioni sulla mappa. Puoi personalizzare gli indicatori modificando il colore predefinito o sostituendo la relativa icona con un'immagine personalizzata. Le finestre informative possono fornire ulteriore contesto a un indicatore.

Esempi di codice

Il repository ApiDemos su GitHub include un esempio che illustra varie funzionalità degli indicatori:

Kotlin

Java

Introduzione

Gli indicatori identificano le località 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. Ricevono eventi click per impostazione predefinita e vengono spesso utilizzati con listener di eventi per visualizzare finestre informative. L'impostazione della proprietà draggable di un indicatore su true consente all'utente di modificare la posizione dell'indicatore. Premi a lungo per attivare la possibilità di spostare l'indicatore.

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

Guida introduttiva agli indicatori

Questa puntata di Maps Live spiega le nozioni di base per aggiungere indicatori alla mappa utilizzando Maps SDK for Android.

Aggiungi un marcatore

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

Kotlin



override fun onMapReady(googleMap: GoogleMap) {
    // Add a marker in Sydney, Australia,
    // and move the map's camera to the same location.
    val sydney = LatLng(-33.852, 151.211)
    googleMap.addMarker(
        MarkerOptions()
            .position(sydney)
            .title("Marker in Sydney")
    )
    googleMap.moveCamera(CameraUpdateFactory.newLatLng(sydney))
}

Java


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

Mostra informazioni aggiuntive su un indicatore

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

Associare dati a un indicatore

Puoi memorizzare 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:

Kotlin



/**
 * A demo class that stores and retrieves data objects with each marker.
 */
class MarkerDemoActivity : AppCompatActivity(),
    OnMarkerClickListener, OnMapReadyCallback {
    private val PERTH = LatLng(-31.952854, 115.857342)
    private val SYDNEY = LatLng(-33.87365, 151.20689)
    private val BRISBANE = LatLng(-27.47093, 153.0235)

    private var markerPerth: Marker? = null
    private var markerSydney: Marker? = null
    private var markerBrisbane: Marker? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_markers)
        val mapFragment =
            supportFragmentManager.findFragmentById(R.id.map) as SupportMapFragment?
        mapFragment!!.getMapAsync(this)
    }

    /** Called when the map is ready.  */
    override fun onMapReady(map: GoogleMap) {
        // Add some markers to the map, and add a data object to each marker.
        markerPerth = map.addMarker(
            MarkerOptions()
                .position(PERTH)
                .title("Perth")
        )
        markerPerth?.tag = 0
        markerSydney = map.addMarker(
            MarkerOptions()
                .position(SYDNEY)
                .title("Sydney")
        )
        markerSydney?.tag = 0
        markerBrisbane = map.addMarker(
            MarkerOptions()
                .position(BRISBANE)
                .title("Brisbane")
        )
        markerBrisbane?.tag = 0

        // Set a listener for marker click.
        map.setOnMarkerClickListener(this)
    }

    /** Called when the user clicks a marker.  */
    override fun onMarkerClick(marker: Marker): Boolean {

        // 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(
                this,
                "${marker.title} has been clicked $newClickCount times.",
                Toast.LENGTH_SHORT
            ).show()
        }

        // Return false to indicate that we have not consumed the event and that we wish
        // for the default behavior to occur (which is for the camera to move such that the
        // marker is centered and for the marker's info window to open, if it has one).
        return false
    }
}

Java


/**
 * A demo class that stores and retrieves data objects with each marker.
 */
public class MarkerDemoActivity extends AppCompatActivity implements
    GoogleMap.OnMarkerClickListener,
    OnMapReadyCallback {

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

    private Marker markerPerth;
    private Marker markerSydney;
    private Marker markerBrisbane;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_markers);
        SupportMapFragment mapFragment =
            (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /** Called when the map is ready. */
    @Override
    public void onMapReady(GoogleMap map) {
        // Add some markers to the map, and add a data object to each marker.
        markerPerth = map.addMarker(new MarkerOptions()
            .position(PERTH)
            .title("Perth"));
        markerPerth.setTag(0);

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

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

        // Set a listener for marker click.
        map.setOnMarkerClickListener(this);
    }

    /** Called when the user clicks a marker. */
    @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(this,
                marker.getTitle() +
                    " has been clicked " + clickCount + " times.",
                Toast.LENGTH_SHORT).show();
        }

        // Return false to indicate that we have not consumed the event and that we wish
        // for the default behavior to occur (which is for the camera to move such that the
        // marker is centered and for the marker's info window to open, if it has one).
        return false;
    }
}

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

  • La tua app può adattarsi a diversi tipi di indicatori e vuoi trattare questi indicatori in modo diverso quando l'utente li fa clic. A questo scopo, puoi memorizzare un 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 nel 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 una volta aggiunto alla mappa purché la sua proprietà draggable sia impostata su true. Premi a lungo l'indicatore per attivare il trascinamento. Quando togli il dito dallo schermo, l'indicatore rimane in questa posizione.

Per impostazione predefinita, gli indicatori non possono essere trascinati. Devi impostare esplicitamente l'indicatore da trascinare con MarkerOptions.draggable(boolean) prima di aggiungerlo alla mappa o con Marker.setDraggable(boolean) dopo essere stato aggiunto alla mappa. Puoi rimanere in ascolto degli eventi di trascinamento sull'indicatore, come descritto nella sezione Eventi di trascinamento dell'indicatore.

Lo snippet riportato di seguito aggiunge un indicatore trascinabile a Perth, in Australia.

Kotlin



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

Java


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

Personalizza un indicatore

Questo video mostra come utilizzare gli indicatori per visualizzare i luoghi 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 valore LatLng per la posizione dell'indicatore sulla mappa. Questa è l'unica proprietà obbligatoria per un oggetto Marker.
Ancora
Il punto dell'immagine che verrà posizionato nella posizione LatLng dell'indicatore. Per impostazione predefinita, si trova al centro della parte inferiore dell'immagine.
Alpha
Imposta l'opacità dell'indicatore. Il valore predefinito è 1,0.
Titolo
Una stringa che viene 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 indicatore predefinita.
Trascinabile
Imposta l'opzione su true se vuoi consentire all'utente di spostare l'indicatore. Il valore predefinito è false.
Visibile
Impostato su false per rendere invisibile l'indicatore. Il valore predefinito è true.
Orientamento piatto o cartellone
Per impostazione predefinita, gli indicatori utilizzano un orientamento per il cartellone, il che significa che sono disegnati orientati rispetto allo schermo del dispositivo anziché rispetto alla superficie della mappa. La rotazione, l'inclinazione o lo zoom della mappa non modifica l'orientamento dell'indicatore. Puoi impostare l'orientamento di un indicatore in modo che sia allineato alla terra. Gli indicatori piatti ruotano quando la mappa viene ruotata, mentre cambiano la prospettiva quando la mappa è inclinata. Come per gli indicatori di un cartellone, 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 di un indicatore piatto è allineato a nord. Quando l'indicatore non è piatto, la posizione predefinita è rivolta verso l'alto e la rotazione è tale che l'indicatore sia sempre rivolto verso la fotocamera.

Lo snippet riportato di seguito crea un semplice indicatore con l'icona predefinita.

Kotlin



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

Java


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 predefinito passando un oggetto BitmapDescriptor al metodo icon(). Puoi utilizzare un insieme di colori predefiniti nell'oggetto BitmapDescriptorFactory oppure impostare un colore personalizzato dell'indicatore con il metodo BitmapDescriptorFactory.defaultMarker(float hue). La tonalità è un valore compreso tra 0 e 360, che rappresenta i punti su una ruota dei colori.

Kotlin



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

Java


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(). Alpha deve essere specificato come numero in virgola mobile compreso tra 0,0 e 1,0, dove 0 è completamente trasparente e 1 è completamente opaco.

Kotlin



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

Java


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

Personalizzare l'immagine dell'indicatore

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

fromAsset(String assetName)
Crea un indicatore personalizzato utilizzando il nome di un'immagine bitmap nella directory degli asset.
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 situato nella memoria interna.
fromPath(String absolutePath)
Crea un indicatore personalizzato da un percorso file assoluto di un'immagine bitmap.
fromResource(int resourceId)
Crea un indicatore personalizzato utilizzando l'ID risorsa di un'immagine bitmap.

Lo snippet riportato di seguito crea un indicatore con un'icona personalizzata.

Kotlin



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

Java


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

In genere le icone degli indicatori vengono disegnate rispetto allo schermo; la rotazione, l'inclinazione o lo zoom della mappa non cambiano l'orientamento dell'indicatore. Puoi impostare l'orientamento di un indicatore in modo che sia allineato alla terra. Gli indicatori orientati in questo modo ruoteranno quando la mappa viene ruotata e cambieranno la prospettiva quando la mappa è inclinata. Gli indicatori piatti manterranno le loro dimensioni se aumenti o diminuisci lo zoom della mappa.

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

Kotlin



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

Java


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

Ruotare un indicatore

Puoi ruotare un indicatore intorno al suo punto di ancoraggio con Marker.setRotation(). La rotazione viene misurata in gradi in senso orario rispetto alla posizione predefinita. Quando l'indicatore è piatto sulla mappa, la posizione predefinita è Nord. Quando l'indicatore non è piatto, la posizione predefinita è rivolta 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 centro anziché alla base.

Kotlin



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

Java


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 indicatore

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

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

Kotlin



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

Java


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 puoi modificarlo chiamando Marker.setZIndex().

Gli indicatori sono sempre disegnati sopra livelli dei riquadri e altri overlay diversi dagli indicatori (overlay del suolo, polilinee, poligoni e altre forme) a prescindere dallo z-index degli altri overlay. Gli indicatori sono considerati effettivamente in un gruppo z-index separato rispetto ad altri overlay.

Leggi di seguito l'effetto dello z-index sugli eventi di clic.

Gestisci eventi indicatore

L'API di Google Maps ti consente di ascoltare e rispondere agli eventi indicatore. Per ascoltare questi eventi, devi impostare il listener corrispondente nell'oggetto GoogleMap a cui appartengono gli indicatori. Quando l'evento si verifica su uno degli indicatori sulla mappa, il callback del listener viene richiamato 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

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 trasferito come argomento. Questo metodo restituisce un valore booleano che indica se hai usufruito dell'evento (ovvero se vuoi eliminare il comportamento predefinito). Se restituisce false, verrà applicato il comportamento predefinito in aggiunta al comportamento personalizzato. Il comportamento predefinito per un evento di clic su un indicatore è mostrare la relativa finestra informativa (se disponibile) e spostare la videocamera in modo che l'indicatore sia centrato sulla mappa.

Effetto dello z-index sugli eventi di clic:

  • Quando un utente fa clic su un gruppo di indicatori, viene attivato l'evento di clic 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 z-index più bassi.
  • Se fai clic su un cluster di indicatori, i clic successivi vengono eseguiti ciclicamente nel cluster, selezionandoli uno alla volta. L'ordine del ciclo dà prima la priorità a z-index e poi la vicinanza al punto di clic.
  • Se l'utente fa clic fuori dalla vicinanza del cluster, l'API ricalcola il cluster e reimposta lo stato del ciclo di clic in modo che ripartisca dall'inizio.
  • L'evento di clic passa da gruppi di indicatori ad altre forme e overlay prima di riavviare il ciclo.
  • Gli indicatori sono considerati effettivamente in un gruppo z-index separato rispetto ad altri overlay o forme (polilinee, poligoni, cerchi e/o overlay al suolo), indipendentemente dallo z-index degli altri overlay. Se più indicatori, forme o overlay sono sovrapposti, l'evento di clic viene prima fatto scorrere nel cluster di indicatori e poi attivato per altre forme o overlay cliccabili, in base ai relativi valori z-index.

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 premere a lungo sull'indicatore. Quando l'utente toglie il dito dallo schermo, l'indicatore rimane in quella posizione. Quando un indicatore viene trascinato, onMarkerDragStart(Marker) viene chiamato inizialmente. Mentre l'indicatore viene trascinato, onMarkerDrag(Marker) viene chiamato costantemente. Al termine del trascinamento, viene chiamato onMarkerDragEnd(Marker). Puoi ottenere la posizione dell'indicatore in qualsiasi momento chiamando Marker.getPosition().