Gli indicatori indicano le singole località sulla mappa. Puoi personalizzare i tuoi indicatori modificando il colore predefinito o sostituendo l'icona dell'indicatore con un'immagine personalizzata. Le finestre informative possono fornire un contesto aggiuntivo a un indicatore.
Esempi di codice
Il repository ApiDemos su GitHub include un esempio che dimostra varie funzionalità degli indicatori:
Java
- MapWithMarker: una mappa semplice con un indicatore. Consulta il tutorial sull'aggiunta di una mappa con un indicatore.
- MarkerDemoActivity: utilizzo degli indicatori su una mappa, tra cui opzioni e ascoltatori
Kotlin
- MapWithMarker: una mappa semplice con un indicatore. Guarda il tutorial sull'aggiunta di una mappa con un indicatore-kt.
- MarkerDemoActivity: utilizzo degli indicatori su una mappa, tra cui opzioni e ascoltatori
Introduzione
Gli indicatori identificano le posizioni sulla mappa. L'indicatore predefinito utilizza un'icona
standard, comune all'aspetto di Google Maps. È possibile cambiare 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 gli eventi click per impostazione predefinita e sono spesso utilizzati con i listener di eventi per aprire 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, la barra degli strumenti della mappa viene visualizzata in basso a destra nella mappa, permettendo all'utente di accedere rapidamente all'app Google Maps per dispositivi mobili. Puoi disattivare la barra degli strumenti. Per scoprire di più, consulta la guida ai controlli.
Introduzione agli indicatori
Questa puntata di Maps Live illustra i concetti di base dell'aggiunta di indicatori alla mappa utilizzando l'SDK Maps per Android.
Aggiungi un marcatore
L'esempio seguente mostra come aggiungere un indicatore a una mappa. L'indicatore viene creato alle coordinate -33.852,151.211 (Sydney, Australia) e, quando viene fatto clic, viene mostrata la stringa "Marker in Sydney" in una finestra informativa.
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));
}
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))
}
Visualizzare ulteriori informazioni 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 i 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 conteggiare il numero di clic su un indicatore utilizzando i tag:
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;
}
}
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
}
}
Di seguito sono riportati alcuni esempi di scenari utili per archiviare e recuperare i dati con gli indicatori:
- L'app potrebbe ospitare diversi tipi di indicatori e vuoi gestirli in modo diverso quando l'utente fa clic. Per farlo, puoi memorizzare un
Stringcon un indicatore che ne indica il tipo. - Potresti trovare l'interfaccia con un sistema dotato di identificatori univoci, in cui gli indicatori rappresentano record specifici nel sistema.
- I dati degli indicatori possono indicare una priorità da utilizzare quando si decide lo z-index di un indicatore.
Crea un indicatore trascinabile
Puoi riposizionare un indicatore dopo averlo aggiunto alla mappa, purché la proprietà draggable sia impostata su true. Premi a lungo l'indicatore per abilitare
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 sia possibile trascinarlo con MarkerOptions.draggable(boolean) prima di aggiungerlo alla mappa oppure Marker.setDraggable(boolean) dopo averlo aggiunto alla mappa.
Puoi ascoltare gli eventi di trascinamento sull'indicatore, come descritto in Eventi di trascinamento
degli indicatori.
Lo snippet riportato di seguito aggiunge un indicatore trascinabile a Perth, in Australia.
Java
final LatLng perthLocation = new LatLng(-31.90, 115.86);
Marker perth = map.addMarker(
new MarkerOptions()
.position(perthLocation)
.draggable(true));
Kotlin
val perthLocation = LatLng(-31.90, 115.86)
val perth = map.addMarker(
MarkerOptions()
.position(perthLocation)
.draggable(true)
)
Personalizzare un indicatore
Questo video mostra come utilizzare gli indicatori per visualizzare le posizioni su una mappa.
Gli indicatori possono definire un'immagine personalizzata da visualizzare 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 (obbligatorio)
- Il valore
LatLngdella posizione dell'indicatore sulla mappa. Questa è l'unica proprietà obbligatoria per un oggettoMarker. - Ancora
- Il punto sull'immagine che verrà posizionato nella posizione dell'indicatore LatLng. L'impostazione predefinita è il 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'indicatore.
- Snippet
- Testo aggiuntivo che viene visualizzato sotto il titolo.
- Icona
- Una bitmap visualizzata al posto dell'immagine indicatore predefinita.
- Trascinabile
- Imposta su
truese vuoi consentire agli utenti di spostare l'indicatore. Il valore predefinito èfalse. - Visibile
- Imposta
falseper rendere invisibile l'indicatore. Il valore predefinito ètrue. - Orientamento piatto o cartellone
- Per impostazione predefinita, gli indicatori utilizzano un orientamento del cartellone pubblicitario, ovvero sono disegnati rispetto allo schermo del dispositivo anziché alla superficie della mappa. 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 contro la terra. Gli indicatori piatti ruotano quando la mappa viene ruotata e cambiano la prospettiva quando la mappa è inclinata. Come per i cartelloni pubblicitari, gli indicatori piatti mantengono le proprie dimensioni quando viene aumentato o diminuito lo zoom della mappa.
- Rotazione
- L'orientamento dell'indicatore, espresso in gradi in senso orario. Se l'indicatore è fisso, la posizione predefinita cambia. La posizione predefinita di un indicatore piatto è allineata 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 di seguito crea un semplice indicatore con l'icona predefinita.
Java
final LatLng melbourneLocation = new LatLng(-37.813, 144.962);
Marker melbourne = map.addMarker(
new MarkerOptions()
.position(melbourneLocation));
Kotlin
val melbourneLocation = LatLng(-37.813, 144.962)
val melbourne = map.addMarker(
MarkerOptions()
.position(melbourneLocation)
)
Personalizza il colore dell'indicatore
È possibile personalizzare il colore dell'immagine indicatore predefinita passando un oggetto BitmapDescriptor al metodo icon(). Puoi utilizzare un insieme di colori predefiniti nell'oggetto BitmapDescriptorFactory o impostare un colore dell'indicatore personalizzato con il metodo BitmapDescriptorFactory.defaultMarker(float hue). Il colore è un valore compreso tra 0 e 360, che rappresenta i punti su una ruota dei colori.
Java
final LatLng melbourneLocation = new LatLng(-37.813, 144.962);
Marker melbourne = map.addMarker(
new MarkerOptions()
.position(melbourneLocation)
.icon(BitmapDescriptorFactory.defaultMarker(BitmapDescriptorFactory.HUE_AZURE)));
Kotlin
val melbourneLocation = LatLng(-37.813, 144.962)
val melbourne = map.addMarker(
MarkerOptions()
.position(melbourneLocation)
.icon(BitmapDescriptorFactory.defaultMarker(BitmapDescriptorFactory.HUE_AZURE))
)
Personalizzare l'opacità dell'indicatore
Puoi controllare l'opacità di un indicatore con il metodo MarkerOptions.alpha(). Il valore alfa deve essere specificato come numero in virgola mobile compreso tra 0,0 e 1,0, dove 0 è completamente trasparente e 1 è completamente opaco.
Java
final LatLng melbourneLocation = new LatLng(-37.813, 144.962);
Marker melbourne = map.addMarker(new MarkerOptions()
.position(melbourneLocation)
.alpha(0.7f));
Kotlin
val melbourneLocation = LatLng(-37.813, 144.962)
val melbourne = map.addMarker(
MarkerOptions()
.position(melbourneLocation)
.alpha(0.7f)
)
Personalizzare l'immagine dell'indicatore
Puoi sostituire l'immagine dell'indicatore predefinita con un'immagine personalizzata, spesso chiamata icona. Le icone personalizzate vengono sempre impostate come BitmapDescriptor e vengono definite utilizzando uno dei metodi della classe BitmapDescriptorFactory.
fromAsset(String assetName)- Crea un indicatore personalizzato usando il nome di un'immagine Bitmap nella directory degli asset.
fromBitmap(Bitmap image)- Crea un indicatore personalizzato a partire da un'immagine Bitmap.
fromFile(String fileName)- Crea un'icona personalizzata usando il nome di un file immagine Bitmap situato nella memoria interna.
fromPath(String absolutePath)- Crea un indicatore personalizzato a partire da un percorso file assoluto di un'immagine Bitmap.
fromResource(int resourceId)- Crea un indicatore personalizzato usando l'ID risorsa di un'immagine Bitmap.
Lo snippet di seguito crea un indicatore con un'icona personalizzata.
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)));
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))
)
Appiattisci un indicatore
In genere le icone degli indicatori sono 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 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 proprie dimensioni quando viene aumentato o diminuito lo zoom della mappa.
Per modificare l'orientamento dell'indicatore, imposta la relativa proprietà flat su
true.
Java
final LatLng perthLocation = new LatLng(-31.90, 115.86);
Marker perth = map.addMarker(
new MarkerOptions()
.position(perthLocation)
.flat(true));
Kotlin
val perthLocation = LatLng(-31.90, 115.86)
val perth = map.addMarker(
MarkerOptions()
.position(perthLocation)
.flat(true)
)
Ruota un indicatore
Puoi ruotare un indicatore intorno al punto di ancoraggio con il
Marker.Metodo setRotation(). La rotazione viene misurata in gradi in senso orario dalla 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 ruota intorno al centro anziché sulla base.
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));
Kotlin
val perthLocation = LatLng(-31.90, 115.86)
val perth = map.addMarker(
MarkerOptions()
.position(perthLocation)
.anchor(0.5f, 0.5f)
.rotation(90.0f)
)
Z-index indicatore
Lo z-index specifica l'ordine di stack di questo indicatore, rispetto agli altri indicatori sulla mappa. Un indicatore con un indice z elevato viene disegnato sopra un indicatore con indici z
inferiori. Il valore predefinito di z-index è 0.
Imposta lo z-index sull'oggetto opzioni dell'indicatore chiamando
MarkerOptions.zIndex(), come mostrato nel seguente snippet di codice:
Java
map.addMarker(new MarkerOptions()
.position(new LatLng(10, 10))
.title("Marker z1")
.zIndex(1.0f));
Kotlin
map.addMarker(
MarkerOptions()
.position(LatLng(10.0, 10.0))
.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 tracciati sopra 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 considerati effettivamente in un gruppo z-index separato rispetto agli altri overlay.
Scopri di più sull'effetto dello z-index sugli eventi di clic più avanti.
Gestire gli eventi indicatore
L'API di Google Maps ti consente di ascoltare gli eventi e rispondervi. 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, il callback dell'ascoltatore viene richiamato con l'oggetto Marker corrispondente trasmesso 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 relativi ai clic sul contrassegno
- Eventi di trascinamento
- Eventi di clic nella finestra informativa
Eventi di clic dell'indicatore
Puoi utilizzare un OnMarkerClickListener per ascoltare gli eventi 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 trasmesso come argomento. Questo metodo restituisce un valore booleano che indica se hai utilizzato l'evento (ovvero vuoi eliminare il comportamento predefinito). Se restituisce false, il comportamento predefinito verrà aggiunto al comportamento personalizzato. Il comportamento predefinito per un evento relativo ai clic su un indicatore è mostrare la relativa 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 il valore di z-index più elevato.
- Viene attivato al massimo un evento per clic. In altre parole, il clic non viene trasmesso agli indicatori o ad altri overlay con valori z-index inferiori.
- Fare clic su un cluster di indicatori fa sì che i clic successivi passino in un secondo momento nel cluster, selezionandoli uno alla volta. L'ordine del ciclo assegna prima la priorità a z-index, poi la vicinanza 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 l'avvio inizi dall'inizio.
- L'evento di clic rientra nei 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 overlay a terra), indipendentemente dallo z-index degli altri overlay. Se più indicatori, overlay o forme sono sovrapposti uno sopra l'altro, l'evento di clic viene fatto scorrere attraverso il cluster di indicatori, quindi attivati per altri overlay o forme cliccabili, in base ai loro valori z-index.
Eventi di trascinamento degli indicatori
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, l'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 richiamato costantemente. Al termine del trascinamento
onMarkerDragEnd(Marker) viene richiamato. Puoi ottenere l'indicatore in qualsiasi momento
chiamando Marker.getPosition().