Indicatori

Seleziona la piattaforma: Android iOS JavaScript

Gli indicatori segnalano singole posizioni sulla mappa. Puoi personalizzare gli indicatori cambiando il colore predefinito o sostituendo l'icona dell'indicatore con una dell'immagine. Le finestre informative possono fornire ulteriore contesto a un indicatore.

Esempi di codice

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

Kotlin

• MapWithMarker: una mappa semplice con un indicatore. Consulta le tutorial sull'aggiunta di una mappa con un mark-kt.
• MarkerDemoActivity: usare gli indicatori su una mappa, incluse le opzioni e ascoltatori

Java

• MapWithMarker: una mappa semplice con un indicatore. Consulta le tutorial sull'aggiunta di una mappa con un indicatore.
• MarkerDemoActivity: usare gli indicatori su una mappa, incluse le opzioni e ascoltatori

Introduzione

Gli indicatori identificano le località sulla mappa. L'indicatore predefinito utilizza un modello 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 GoogleMap.addMarker(markerOptions).

Gli indicatori sono progettati per essere interattivi. Riceve click eventi entro il predefiniti e sono spesso utilizzati con listener di eventi per visualizzare informazioni Windows. 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, nella parte inferiore viene visualizzata la barra degli strumenti della mappa. a destra della mappa, offrendo all'utente un accesso rapido all'app mobile Google Maps. Puoi disattivare la barra degli strumenti. Per ulteriori informazioni, consulta guida ai controlli.

Guida introduttiva agli indicatori

Questo episodio di Maps Live illustra 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 è creato alle coordinate -33.852,151.211 (Sydney, Australia) e mostra stringa "Marker in Sydney" in una finestra informativa quando l'utente fa clic.

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 posizione quando l'utente tocca un indicatore sulla mappa. Consulta la guida per finestre informative.

Associare dati a un indicatore

Puoi archiviare un oggetto dati arbitrario con un indicatore utilizzando Marker.setTag() e recuperarlo utilizzando Marker.getTag(). L'esempio seguente mostra come puoi 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;
    }
}

      

Ecco alcuni esempi di scenari in cui è utile archiviare e recuperare i dati con indicatori:

• La tua app può adattarsi a diversi tipi di indicatori e vorresti trattare tutti questi indicatori in modo diverso quando l'utente fa clic su questi ultimi. A questo scopo, puoi archiviare un String con l'indicatore che indica il tipo.
• Potresti interagire con un sistema che dispone di identificatori di record univoci, dove 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 è impostata su true. Tieni premuto l'indicatore per attivare il trascinamento. Quando togli il dito dallo schermo, l'indicatore rimane in quella posizione.

Per impostazione predefinita, gli indicatori non possono essere trascinati. Devi impostare esplicitamente l'indicatore in modo che trascinabile con MarkerOptions.draggable(boolean) prima di aggiungerlo a la mappa o Marker.setDraggable(boolean) dopo che è stata aggiunta alla mappa. Puoi ascoltare gli eventi di trascinamento dell'indicatore, come descritto in 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)

La LatLng per la posizione dell'indicatore sulla mappa. Questo è l'unico campo obbligatorio per un oggetto Marker.

Ancoraggio

Il punto dell'immagine che verrà posizionato nella posizione LatLng dell'elemento indicatore. Per impostazione predefinita, il punto di riferimento è al centro 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'icona indicatore.

Snippet

Testo aggiuntivo visualizzato sotto il titolo.

Icona

Una bitmap visualizzata al posto dell'immagine indicatore predefinita.

Trascinabile

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

Visibile

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

Orientamento orizzontale o verticale

Per impostazione predefinita, gli indicatori utilizzano un orientamento per il cartellone, ovvero sono stati disegnati orientate rispetto allo schermo del dispositivo anziché alla superficie della mappa. La rotazione, l'inclinazione o lo zoom della mappa non modifica l'orientamento della mappa. indicatore. Puoi impostare l'orientamento di un indicatore in modo che sia allineato alla terra. Gli indicatori piatti ruotano quando la mappa viene ruotata e cambiano prospettiva quando la mappa viene ruotata la mappa è inclinata. Come nel caso degli indicatori di cartelloni pubblicitari, gli indicatori piatti mantengono la loro dimensione quando aumentare o diminuire lo zoom della mappa.

Rotazione

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

Lo snippet seguente crea un indicatore semplice 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 BitmapDescriptor al metodo icon(). Puoi utilizzare un insieme colori predefiniti in BitmapDescriptorFactory oppure imposta un colore di indicatore personalizzato con BitmapDescriptorFactory.defaultMarker(float hue). La tonalità è un valore 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(). Il valore alpha deve essere specificato come numero con 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 vengono 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 negli 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 che si trova 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

Le icone degli indicatori vengono generalmente disegnate rispetto allo schermo; rotazione, inclinazione o lo zoom sulla mappa non modificherà l'orientamento dell'indicatore. Puoi impostare l'orientamento di un indicatore sia allineato 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 manterranno le loro dimensioni quando la mappa sarà aumentare o diminuire lo zoom.

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 il 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 significa che la posizione predefinita è rivolta e la rotazione fa sì che l'indicatore sia sempre rivolto verso la fotocamera.

L'esempio seguente ruota l'indicatore di 90°. L'impostazione del punto di ancoraggio su 0.5,0.5 fa sì che l'indicatore venga ruotato attorno al suo centro anziché alla sua 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 in cui disporre uno sopra l'altro gli indicatori rispetto agli altri sulla mappa. Un indicatore con uno z-index alto viene disegnato sopra agli indicatori con z-indexes. Il valore predefinito dello z-index è 0.

Imposta l'indice z sull'oggetto options dell'indicatore chiamando 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 modificala chiamando il numero Marker.setZIndex().

Gli indicatori vengono sempre disegnati sopra i livelli delle tessere e altri overlay diversi dagli indicatori (overlay del terreno, polilinee, poligoni e altre forme) indipendentemente dall'indice z degli altri overlay. Gli indicatori sono considerati in una sezione gruppo z-index a confronto con altri overlay.

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

Gestisci eventi indicatore

L'API Maps ti consente di ascoltare e rispondere agli eventi degli indicatori. Per ascoltare per questi eventi, devi impostare il listener corrispondente sull'GoogleMap a cui appartengono gli indicatori. Quando l'evento si verifica in uno degli indicatori della mappa, il callback del listener verrà invocato con l'oggetto Marker corrispondente passato come parametro. Per fare un confronto 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 usare una OnMarkerClickListener per ascoltare per gli eventi di clic sull'indicatore. Per impostare questo listener sulla mappa, richiama GoogleMap.setOnMarkerClickListener(OnMarkerClickListener). Quando un utente fa clic su un indicatore, viene chiamato onMarkerClick(Marker) e l'indicatore come argomento. Questo metodo restituisce un valore booleano che indica se hai usufruito dell'evento (ovvero, vuoi eliminare il valore predefinito ). Se restituisce false, il comportamento predefinito verrà applicato in da integrare al tuo comportamento personalizzato. Comportamento predefinito per il clic su un indicatore è mostrare la relativa finestra informativa (se disponibile) e spostare fotocamera in modo che l'indicatore sia centrato sulla mappa.

Effetto dell'indice z sugli eventi di clic:

• Quando un utente fa clic su un gruppo di indicatori, viene attivato l'evento clic per l'indicatore con lo z-index più alto.
• Per ogni clic viene attivato al massimo un evento. In altre parole, il clic non è passati agli indicatori o ad altri overlay con valori z-index più bassi.
• Se si fa clic su un gruppo di indicatori, i clic successivi si scorrono nella selezionandoli uno alla volta. L'ordine delle prime priorità del ciclo z-index, quindi la vicinanza al punto di clic.
• Se l'utente fa clic al di fuori del cluster, l'API ricalcola cluster e reimposta lo stato del ciclo di clic in modo che inizi partendo da zero.
• L'evento di clic passa attraverso i cluster 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 suolo overlay), indipendentemente dallo z-index degli altri overlay. Se più gli indicatori, le forme o gli overlay sono sovrapposti, l'evento di clic viene prima fatto scorrere tra gli indicatori e poi attivato per altri Forme o overlay cliccabili, in base ai relativi valori z-index.

Eventi di trascinamento dell'indicatore

Puoi utilizzare una OnMarkerDragListener per ascoltare trascinare eventi su un indicatore. Per impostare questo listener sulla mappa, richiama GoogleMap.setOnMarkerDragListener. Per trascinare un indicatore, un utente deve premere a lungo sull'indicatore. Quando l'utente toglie il dito dallo schermo, l'indicatore rimarrà 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 chiamata la funzione onMarkerDragEnd(Marker). Puoi ottenere la posizione dell'indicatore in in qualsiasi momento chiamando il numero Marker.getPosition().

Nota: per impostazione predefinita, un indicatore non può essere trascinato. È necessario impostare esplicitamente un indicatore affinché possa essere trascinato da un utente. Questa operazione può essere eseguita in con MarkerOptions.draggable(boolean) prima di aggiungerlo alla mappa oppure Marker.setDraggable(boolean) dopo essere stato aggiunto alla mappa.