Le mappe in Maps SDK for Android possono essere inclinate e ruotate con semplici gesti, offrendo agli utenti la possibilità di regolare la mappa con un orientamento per loro più adatto. A qualsiasi livello di zoom, puoi eseguire una panoramica della mappa o cambiarne la prospettiva con una latenza minima grazie all'ingombro ridotto dei riquadri della mappa basata su vettori.
Esempi di codice
Il repository ApiDemos su GitHub include un esempio che dimostra le funzionalità della fotocamera:
- FotocameraDemoActivity - Kotlin: modifica della posizione della fotocamera
- FotocameraDemoActivity - Java: modifica della posizione della fotocamera
Introduzione
Come Google Maps sul web, Maps SDK for Android rappresenta la superficie del mondo (una sfera) sullo schermo del dispositivo (un piano piatto) utilizzando la proiezione di merchandising. A est e a ovest, la mappa si ripete all'infinito mentre il mondo si avvolge su se stesso. Nelle direzioni nord e sud, la mappa si limita a circa 85 gradi a nord e a 85 gradi a sud.
Nota: una proiezione di Mercatore ha una larghezza finita longitudinalmente, ma un'altezza infinita dalla latitudine. "Tagliamo" le immagini della mappa base utilizzando la proiezione di Mercator a circa +/- 85 gradi per rendere quadrata la forma della mappa risultante, consentendo una logica più semplice per la selezione dei riquadri.
Maps SDK for Android ti consente di cambiare il punto di vista dell'utente della mappa modificando la fotocamera della mappa.
Le modifiche apportate alla fotocamera non apporteranno modifiche agli indicatori, agli overlay o ad altri elementi grafici che hai aggiunto, anche se ti consigliamo di modificarli per adattarli meglio alla nuova visualizzazione.
Poiché puoi rimanere in ascolto dei gesti degli utenti sulla mappa, puoi modificare la mappa in risposta alle richieste degli utenti. Ad esempio, il metodo di callback OnMapClickListener.onMapClick()
risponde a un singolo tocco sulla mappa. Poiché il metodo riceve la latitudine e la longitudine della posizione del tocco, puoi rispondere con la panoramica o lo zoom fino a quel punto.
Sono disponibili metodi simili per rispondere ai tocchi sulla bolla di un indicatore o a un gesto di trascinamento su un indicatore.
Puoi anche ascoltare i movimenti della videocamera, in modo che l'app riceva una notifica quando la videocamera inizia a muoversi, è in movimento o si ferma. Per maggiori dettagli, consulta la guida agli eventi di cambio della videocamera.
La posizione della fotocamera
La visualizzazione mappa è modellata come una fotocamera che guarda verso il basso su un piano piatto. La posizione della fotocamera (e quindi del rendering della mappa) è specificata dalle seguenti proprietà: target (latitudine/longitudine), bearing, inclinazione e zoom.
Target (località)
L'obiettivo della fotocamera è la posizione del centro della mappa, specificata come coordinate di latitudine e longitudine.
La latitudine può essere compresa tra -85 e 85 gradi inclusi. I valori superiori o inferiori a questo intervallo verranno limitati al valore più vicino all'interno dell'intervallo. Ad esempio, se specifichi una latitudine pari a 100, il valore verrà impostato su 85. La longitudine è compresa tra -180 e 180 gradi, inclusi. I valori superiori o inferiori a questo intervallo verranno aggregati in modo che rientrino nell'intervallo (-180, 180). Ad esempio, 480, 840 e 1200 verranno tutti aggregati a 120 gradi.Orientamento (orientamento)
L'orientamento della fotocamera specifica la direzione della bussola, misurata in gradi dal nord vero, corrispondente al bordo superiore della mappa. Se tracci una linea verticale dal centro della mappa al bordo superiore della mappa, l'orientamento corrisponde all'orientamento della fotocamera (misurato in gradi) rispetto al nord vero.
Un rilevamento pari a 0 indica che la parte superiore della mappa indica il nord vero. Un valore di rilevamento 90 indica i punti superiori dei punti della mappa rivolti a est (90 gradi su un compasso). Il valore 180 indica la parte superiore dei punti della mappa a sud.
L'API di Google Maps ti consente di modificare l'orientamento di una mappa. Ad esempio, chi guida un'auto spesso gira una mappa stradale per allinearla alla direzione di marcia, mentre gli escursionisti che utilizzano una mappa e una bussola di solito la orientano in modo che una linea verticale sia rivolta a nord.
Inclinazione (angolo di visualizzazione)
L'inclinazione definisce la posizione della fotocamera su un arco direttamente rispetto alla posizione centrale della mappa, misurata in gradi dal nadir (la direzione che punta direttamente sotto la fotocamera). Il valore 0 corrisponde a una videocamera puntata in basso. Valori superiori a 0 corrispondono a una fotocamera inclinata verso l'orizzonte del numero di gradi specificato. Quando modifichi l'angolo di visualizzazione, la mappa viene mostrata in prospettiva, con gli elementi lontani che appaiono più piccoli e quelli vicini che appaiono più grandi. Le seguenti illustrazioni lo dimostrano.
Nelle immagini di seguito, l'angolo di visione è di 0 gradi. La prima immagine mostra uno schema di questo aspetto: la posizione 1 è la posizione della fotocamera, mentre la posizione 2 è la posizione corrente sulla mappa. La mappa risultante è visualizzata sotto di essa.
Nelle immagini di seguito, l'angolo di visione è di 45 gradi. Nota che la videocamera si sposta a metà lungo un arco tra l'alto (0 gradi) e il suolo (90 gradi) in posizione 3. La fotocamera punta ancora verso il punto centrale della mappa, ma l'area rappresentata dalla linea nella posizione 4 è ora visibile.
La mappa in questo screenshot è ancora centrata sullo stesso punto della mappa originale, ma nella parte superiore sono stati visualizzati altri elementi. Se aumenti l'angolo di oltre 45 gradi, gli elementi tra la fotocamera e la posizione sulla mappa appaiono proporzionalmente più grandi, mentre quelli oltre la posizione sulla mappa appaiono proporzionalmente più piccoli, producendo un effetto tridimensionale.
Zoom
Il livello di zoom della fotocamera determina la scala della mappa. A livelli di zoom più grandi è possibile visualizzare maggiori dettagli sullo schermo, mentre a livelli di zoom ridotti è possibile vedere più dettagli. A livello di zoom 0, la scala della mappa fa sì che l'intero mondo abbia una larghezza di circa 256 dp (pixel indipendenti dalla densità).
Aumentando il livello di zoom di 1, la larghezza della superficie dello schermo viene raddoppiata. Quindi, a livello di zoom N, la larghezza del mondo è di circa 256 * 2N dp. Ad esempio, a livello di zoom 2, la larghezza di tutto il mondo è di circa 1024 dp.
Il livello di zoom non deve essere un numero intero. L'intervallo di livelli di zoom consentiti dalla mappa dipende da una serie di fattori, tra cui il target, il tipo di mappa e le dimensioni dello schermo. Qualsiasi numero non compreso nell'intervallo verrà convertito nel successivo valore valido più vicino, che può essere il livello minimo o massimo di zoom. L'elenco seguente mostra il livello approssimativo di dettaglio previsto per ogni livello di zoom:
- 1: Mondo
- 5: massa continentale/continente
- 10: Città
- 15: Strade
- 20: Edifici
Spostare la fotocamera
L'API di Google Maps ti consente di cambiare la parte del mondo visibile sulla mappa. Per farlo, devi cambiare la posizione della fotocamera (anziché spostare la mappa).
Quando cambi la videocamera, puoi animare il movimento della videocamera risultante. L'animazione si interpola tra gli attributi attuali della fotocamera e i nuovi attributi della fotocamera. Puoi anche controllare la durata dell'animazione.
Per cambiare la posizione della fotocamera, devi specificare dove vuoi
spostarla utilizzando un CameraUpdate
. L'API di Google Maps
ti consente di creare molti tipi diversi di CameraUpdate
utilizzando
CameraUpdateFactory
. Sono disponibili le seguenti opzioni:
Modifica del livello di zoom e impostazione dello zoom minimo/massimo
CameraUpdateFactory.zoomIn()
e CameraUpdateFactory.zoomOut()
ti offrono un CameraUpdate
che modifica il livello di zoom di 1,0, mantenendo invariate tutte le altre proprietà.
CameraUpdateFactory.zoomTo(float)
ti offre un CameraUpdate
che modifica il livello di zoom impostandolo sul valore specificato,
mantenendo invariate tutte le altre proprietà.
CameraUpdateFactory.zoomBy(float)
e
CameraUpdateFactory.zoomBy(float, Point)
ti offrono un CameraUpdate
che aumenta (o diminuisce, se il valore è
negativo) il livello di zoom del valore specificato. Quest'ultimo fissa il punto specificato sullo schermo in modo che rimanga nella stessa posizione (latitudine/longitudine) e cambia la posizione della videocamera per ottenere questo risultato.
Potrebbe essere utile impostare un livello di zoom minimo e/o massimo preferito. Ad esempio, questo è utile per controllare l'esperienza dell'utente se la tua app mostra un'area definita intorno a un punto d'interesse o se utilizzi un overlay di riquadro personalizzato con un insieme limitato di livelli di zoom.
Kotlin
private lateinit var map: GoogleMap map.setMinZoomPreference(6.0f) map.setMaxZoomPreference(14.0f)
Java
private GoogleMap map; map.setMinZoomPreference(6.0f); map.setMaxZoomPreference(14.0f);
Tieni presente che ci sono considerazioni tecniche che potrebbero impedire all'API di consentire agli utenti di aumentare lo zoom troppo basso o troppo alto. Ad esempio, i dati satellitari o i rilievi del terreno possono avere uno zoom massimo inferiore rispetto ai riquadri della mappa base.
Modifica della posizione della fotocamera
Esistono due metodi di convenienza per le modifiche della posizione comune.
CameraUpdateFactory.newLatLng(LatLng)
fornisce un CameraUpdate
che modifica la latitudine e la longitudine della videocamera,
conservando tutte le altre proprietà.
CameraUpdateFactory.newLatLngZoom(LatLng, float)
offre un elemento CameraUpdate
che modifica la latitudine, la longitudine e lo zoom della videocamera, mantenendo tutte le altre proprietà.
Per la massima flessibilità nel modificare la posizione della fotocamera, utilizza
CameraUpdateFactory.newCameraPosition(CameraPosition)
che ti offre un
CameraUpdate
che sposta la videocamera nella
posizione specificata. Un CameraPosition
può essere ottenuto direttamente, utilizzando
new CameraPosition()
o con un CameraPosition.Builder
utilizzando
new CameraPosition.Builder()
.
Panoramica (scorrimento)
CameraUpdateFactory.scrollBy(float, float)
fornisce un CameraUpdate
che
modifica la latitudine e la longitudine della fotocamera in modo che la mappa si sposti
del numero specificato di pixel. Un valore x positivo fa sì che la fotocamera si sposti
verso destra, in modo che la mappa sembri essere stata spostata a sinistra. Un valore y positivo fa sì che la fotocamera si sposti verso il basso e la mappa sembrerà essere stata spostata in alto. Al contrario, valori x negativi fanno sì che la fotocamera si sposti verso sinistra,
poiché la mappa sembri mossa a destra, valori y negativi fanno sì
che la fotocamera si sposti verso l'alto. Lo scorrimento è relativo
all'orientamento attuale della fotocamera. Ad esempio, se la fotocamera ha un rilevamento di 90 gradi, l'orientamento est
è "in alto".
Stabilire dei limiti
Stabilire i limiti della mappa
A volte è utile spostare la videocamera in modo che un'intera area di interesse sia visibile al massimo livello di zoom possibile. Ad esempio, se stai mostrando tutte le stazioni di servizio entro cinque chilometri dalla posizione corrente dell'utente, ti consigliamo di spostare la fotocamera in modo che siano tutte visibili sullo schermo. Per farlo, devi prima calcolare il valore di
LatLngBounds
che vuoi che sia visibile sullo schermo. Puoi
quindi utilizzare CameraUpdateFactory.newLatLngBounds(LatLngBounds bounds, int
padding)
per ottenere un CameraUpdate
che cambi la posizione
della fotocamera in modo che il valore LatLngBounds
specificato si adatti completamente alla
mappa, tenendo conto della spaziatura interna (in pixel) specificata. Il parametro CameraUpdate
restituito assicura che lo spazio (in pixel) tra i limiti specificati e il bordo della mappa sia almeno pari alla spaziatura interna specificata. Tieni presente che l'inclinazione e l'orientamento della mappa sono entrambi 0.
Kotlin
val australiaBounds = LatLngBounds( LatLng((-44.0), 113.0), // SW bounds LatLng((-10.0), 154.0) // NE bounds ) map.moveCamera(CameraUpdateFactory.newLatLngBounds(australiaBounds, 0))
Java
LatLngBounds australiaBounds = new LatLngBounds( new LatLng(-44, 113), // SW bounds new LatLng(-10, 154) // NE bounds ); map.moveCamera(CameraUpdateFactory.newLatLngBounds(australiaBounds, 0));
Centra la mappa all'interno di un'area
In alcuni casi, è consigliabile centrare la fotocamera entro un margine invece di
includere i bordi estremi. ad esempio per centrare la fotocamera
su un paese mantenendo costante lo zoom. In questo caso, puoi utilizzare un metodo simile,
creando una LatLngBounds
e utilizzando
CameraUpdateFactory.newLatLngZoom(LatLng latLng, float zoom)
con
LatLngBounds
.Metodo getCenter()
. Il metodo getCenter() restituirà il
centro geografico di LatLngBounds
.
Kotlin
val australiaBounds = LatLngBounds( LatLng((-44.0), 113.0), // SW bounds LatLng((-10.0), 154.0) // NE bounds ) map.moveCamera(CameraUpdateFactory.newLatLngZoom(australiaBounds.center, 10f))
Java
LatLngBounds australiaBounds = new LatLngBounds( new LatLng(-44, 113), // SW bounds new LatLng(-10, 154) // NE bounds ); map.moveCamera(CameraUpdateFactory.newLatLngZoom(australiaBounds.getCenter(), 10));
Un sovraccarico del metodo, newLatLngBounds(boundary, width, height,
padding)
, ti consente di specificare la larghezza e l'altezza in pixel per un rettangolo, con l'intenzione che corrispondano alle dimensioni della mappa. Il rettangolo è posizionato in modo tale che il suo centro sia uguale a quello della visualizzazione della mappa (in modo che, se le dimensioni specificate sono uguali a quelle della visualizzazione della mappa, il rettangolo coincida con la visualizzazione della mappa). Il CameraUpdate
restituito sposterà la videocamera in modo che i LatLngBounds
specificati siano centrati sullo schermo all'interno del rettangolo specificato al massimo livello di zoom possibile, tenendo conto della spaziatura interna richiesta.
Nota: utilizza il metodo più semplice
newLatLngBounds(boundary, padding)
per generare un CameraUpdate
se verrà utilizzato per spostare
la fotocamera dopo il layout della mappa. Durante il layout, l'API calcola i limiti di visualizzazione della mappa necessari per proiettare correttamente il riquadro di delimitazione. A confronto, puoi utilizzare
CameraUpdate
restituito dal metodo più complesso
newLatLngBounds(boundary, width, height, padding)
in qualsiasi momento, anche prima che la mappa sia stata sottoposta al layout, poiché l'API
calcola i limiti di visualizzazione in base agli argomenti che passi.
Limitare la panoramica dell'utente a una determinata area
Negli scenari precedenti, puoi impostare i limiti della mappa ma l'utente può scorrere o eseguire la panoramica al di fuori di questi limiti. Ti consigliamo invece di limitare i limiti centrali latitudine/lng del punto focale della mappa (il target della fotocamera) in modo che gli utenti possano scorrere ed eseguire la panoramica solo all'interno di questi limiti. Ad esempio, un'app di vendita al dettaglio di un centro commerciale o di un aeroporto può voler limitare la mappa a un determinato limite, consentendo agli utenti di scorrere ed eseguire la panoramica all'interno di questi limiti.
Kotlin
// Create a LatLngBounds that includes the city of Adelaide in Australia. val adelaideBounds = LatLngBounds( LatLng(-35.0, 138.58), // SW bounds LatLng(-34.9, 138.61) // NE bounds ) // Constrain the camera target to the Adelaide bounds. map.setLatLngBoundsForCameraTarget(adelaideBounds)
Java
// Create a LatLngBounds that includes the city of Adelaide in Australia. LatLngBounds adelaideBounds = new LatLngBounds( new LatLng(-35.0, 138.58), // SW bounds new LatLng(-34.9, 138.61) // NE bounds ); // Constrain the camera target to the Adelaide bounds. map.setLatLngBoundsForCameraTarget(adelaideBounds);
Il seguente diagramma illustra uno scenario in cui la videocamera target è limitata a un'area leggermente più grande dell'area visibile. L'utente può scorrere e fare una panoramica, a condizione che l'obiettivo della videocamera rimanga all'interno dell'area delimitata. La croce rappresenta il target della fotocamera:
La mappa riempie sempre l'area visibile, anche se quest'ultima mostra aree al di fuori dei limiti definiti. Ad esempio, se posizioni il target della videocamera in un angolo dell'area delimitata, l'area oltre l'angolo è visibile nell'area visibile, ma gli utenti non possono scorrere ulteriormente in quell'area. Il seguente diagramma illustra questo scenario. La croce rappresenta il target della fotocamera:
Nel diagramma seguente, l'obiettivo della videocamera ha limiti molto ristretti, offrendo all'utente pochissime opportunità di scorrere o panoramica la mappa. La croce rappresenta il target della videocamera:
Aggiornamento della visualizzazione della videocamera in corso...
Per applicare una CameraUpdate
alla mappa, puoi spostare istantaneamente la fotocamera o animarla in modo uniforme. Per spostare istantaneamente la videocamera
con il CameraUpdate
specificato, puoi chiamare
GoogleMap.moveCamera(CameraUpdate)
.
Per rendere più piacevole l'esperienza utente, soprattutto per le mosse brevi, anima la modifica. Per farlo, invece di chiamare
GoogleMap.moveCamera
chiama
GoogleMap.animateCamera
.
La mappa si sposterà facilmente in corrispondenza dei nuovi attributi. La forma più dettagliata di questo metodo, GoogleMap.animateCamera(cameraUpdate, duration, callback)
, offre tre argomenti:
cameraUpdate
- L'
CameraUpdate
che descrive dove spostare la videocamera. callback
- Un oggetto che implementa
GoogleMap.CancellableCallback
. Questa interfaccia generalizzata per la gestione delle attività definisce due metodi "onCancel()" e "onFinished()". Per l'animazione, i metodi vengono chiamati nelle seguenti circostanze:onFinish()
- Richiamato se l'animazione si completa senza interruzioni.
onCancel()
-
Richiamato se l'animazione si interrompe chiamando
stopAnimation()
o avviando un nuovo movimento della videocamera.In alternativa, questo può verificarsi anche se chiami
GoogleMap.stopAnimation()
.
duration
- Durata dell'animazione desiderata, in millisecondi, come
int
.
I seguenti snippet di codice illustrano alcuni dei metodi più comuni per spostare la videocamera.
Kotlin
val sydney = LatLng(-33.88, 151.21) val mountainView = LatLng(37.4, -122.1) // Move the camera instantly to Sydney with a zoom of 15. map.moveCamera(CameraUpdateFactory.newLatLngZoom(sydney, 15f)) // Zoom in, animating the camera. map.animateCamera(CameraUpdateFactory.zoomIn()) // Zoom out to zoom level 10, animating with a duration of 2 seconds. map.animateCamera(CameraUpdateFactory.zoomTo(10f), 2000, null) // Construct a CameraPosition focusing on Mountain View and animate the camera to that position. val cameraPosition = CameraPosition.Builder() .target(mountainView) // Sets the center of the map to Mountain View .zoom(17f) // Sets the zoom .bearing(90f) // Sets the orientation of the camera to east .tilt(30f) // Sets the tilt of the camera to 30 degrees .build() // Creates a CameraPosition from the builder map.animateCamera(CameraUpdateFactory.newCameraPosition(cameraPosition))
Java
LatLng sydney = new LatLng(-33.88,151.21); LatLng mountainView = new LatLng(37.4, -122.1); // Move the camera instantly to Sydney with a zoom of 15. map.moveCamera(CameraUpdateFactory.newLatLngZoom(sydney, 15)); // Zoom in, animating the camera. map.animateCamera(CameraUpdateFactory.zoomIn()); // Zoom out to zoom level 10, animating with a duration of 2 seconds. map.animateCamera(CameraUpdateFactory.zoomTo(10), 2000, null); // Construct a CameraPosition focusing on Mountain View and animate the camera to that position. CameraPosition cameraPosition = new CameraPosition.Builder() .target(mountainView ) // Sets the center of the map to Mountain View .zoom(17) // Sets the zoom .bearing(90) // Sets the orientation of the camera to east .tilt(30) // Sets the tilt of the camera to 30 degrees .build(); // Creates a CameraPosition from the builder map.animateCamera(CameraUpdateFactory.newCameraPosition(cameraPosition));