Le mappe nell'SDK di Maps per Android possono essere inclinate e ruotate con gesti semplici, offrendo agli utenti la possibilità di regolare la mappa con un orientamento adeguato. A qualsiasi livello di zoom, puoi eseguire la panoramica della mappa o cambiarne la prospettiva con una latenza molto ridotta grazie al minore ingombro dei riquadri della mappa basati su vettori.
Esempi di codice
Il repository ApiDemos su GitHub include un esempio che dimostra le funzionalità della fotocamera:
- VideocameraDemoActivity - Java: modifica della posizione della videocamera
- VideocameraDemoActivity - Kotlin: cambiare la posizione della videocamera
Introduzione
Come Google Maps sul Web, l'SDK Maps per Android rappresenta la superficie del mondo (una sfera) sullo schermo del tuo dispositivo (un piano) con la proiezione del reindirizzamento. Nella direzione est e ovest, la mappa si ripete all'infinito mentre il mondo si avvolge senza soluzione di continuità. A nord e a sud la mappa è limitata a circa 85 gradi nord e 85 gradi sud.
Nota: una proiezione di Mercatore ha una larghezza limitata, in senso longitudinale, ma un'altezza latitudinalica, Abbiamo "tagliato" le immagini di base della mappa utilizzando la proiezione di Mercator a circa +/- 85 gradi per ottenere la forma della mappa quadrata risultante, il che consente una logica più semplice per la selezione delle schede.
L'SDK Maps per Android consente di modificare il punto di vista dell'utente della mappa modificando la fotocamera della mappa.
Le modifiche apportate alla fotocamera non apporteranno modifiche a indicatori, overlay o altri elementi grafici che hai aggiunto, anche se ti consigliamo di modificare gli elementi aggiunti in modo che si adattino meglio alla nuova visualizzazione.
Poiché puoi ascoltare i gesti degli utenti sulla mappa, puoi modificarla 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 località tocco, puoi rispondere eseguendo una panoramica o lo zoom in quel punto.
Sono disponibili metodi simili per rispondere ai tocchi con il fumetto di un indicatore o per rispondere a un gesto di trascinamento su un indicatore.
Puoi anche ascoltare i movimenti della videocamera, così la tua app riceverà una notifica quando la videocamera inizia a muoversi, è attualmente in movimento o smette di muoversi. Per informazioni dettagliate, consulta la guida agli eventi di cambio della videocamera.
La posizione della fotocamera
La visualizzazione mappa è modellata come una fotocamera rivolta verso il basso su un piano. La posizione della fotocamera (e quindi il rendering della mappa) è specificata dalle seguenti proprietà: target (posizione di latitudine/longitudine), cuscinetto, inclinazione e zoom.

Target (località)
La località target della fotocamera corrisponde alla posizione del centro della mappa, specificata come longitudine 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. Ad esempio, se specifichi una latitudine di 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, i valori 480, 840 e 1200 vengono aggregati a 120 gradi.Rilevamento (orientamento)
Il rilevamento della fotocamera specifica la direzione della bussola, misurata in gradi da vero nord, corrispondente al bordo superiore della mappa. Se tracci una linea verticale dal centro della mappa al bordo superiore della mappa, il cuscinetto corrisponde all'intestazione della fotocamera (misurata in gradi) rispetto al vero nord.
Il valore 0 indica che la parte superiore della mappa punta a nord. Un valore di rilevamento di 90 indica la parte superiore della mappa che punta verso est (90 gradi su una bussola). Un valore 180 indica la parte superiore dei punti della mappa dovuti a sud.
L'API di Google Maps ti consente di modificare il rilevamento di una mappa. Ad esempio, un utente che guida un'auto spesso gira una mappa stradale per allinearla alla sua direzione di viaggio, mentre gli escursionisti che utilizzano una mappa e una bussola di solito orientano la mappa in modo che una linea verticale sia rivolta verso nord.
Inclinazione (angolo di visualizzazione)
L'inclinazione definisce la posizione della fotocamera su un arco direttamente sopra la posizione centrale della mappa, misurata in gradi dal nadir (la direzione che punta direttamente sotto la fotocamera). Un valore 0 corrisponde a una videocamera puntata verso il basso. I valori maggiori di 0 corrispondono a una videocamera inclinata verso l'orizzonte del numero di gradi specificato. Quando cambi l'angolo di visione, la mappa appare in prospettiva, con gli elementi lontani che appaiono più piccoli e le funzionalità vicine 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 ciò; la posizione 1 è la posizione della fotocamera e la posizione 2 è la posizione corrente sulla mappa. La mappa risultante viene mostrata sotto di esso.
![]() |
![]() |
Nelle immagini di seguito, l'angolo di visione è di 45 gradi. Tieni presente che la videocamera si sposta a metà dell'arco tra onda dritta (0 gradi) e il suolo (90 gradi), in posizione 3. La fotocamera è ancora rivolta verso il punto centrale della mappa, ma l'area rappresentata dalla linea nella posizione 4 è ora visibile.
![]() |
![]() |
La mappa di questo screenshot è ancora centrata sullo stesso punto della mappa originale, ma nella parte superiore della mappa sono state visualizzate altre funzionalità. Se aumenti l'angolo di oltre 45 gradi, gli elementi tra la fotocamera e la posizione sulla mappa appaiono proporzionalmente più grandi, mentre gli elementi oltre la posizione della mappa appaiono proporzionalmente più piccoli, con un effetto tridimensionale.
Assumi una prospettiva
Il livello di zoom della fotocamera determina la portata della mappa. A livelli di zoom più elevati, si possono vedere più dettagli sullo schermo, mentre a livelli di zoom più piccoli si può vedere più parte del mondo sullo schermo. Al livello di zoom 0, la scala della mappa è tale che l'intero mondo abbia una larghezza di circa 256 dp (pixel indipendenti dalla densità).
Aumentando di 1 il livello di zoom, aumenti la larghezza del mondo sullo schermo. Di conseguenza, a livello di zoom N, la larghezza del mondo è di circa 256 * 2N dp. Ad esempio, al livello di zoom 2, il mondo intero ha una larghezza di circa 1024 dp.
Il livello di zoom non deve essere un numero intero. La portata dei livelli di zoom consentiti dalla mappa dipende da una serie di fattori, tra cui target, tipo di mappa e dimensioni dello schermo. Qualsiasi numero al di fuori dell'intervallo verrà convertito nel valore valido successivo più vicino, che può essere il livello di zoom minimo o il livello di zoom massimo. Il seguente elenco mostra il livello approssimativo di dettaglio previsto da ciascun livello di zoom:
- 1: mondo
- 5: Terra di massa/continente
- 10: città
- 15: Strade
- 20: Edifici
![]() |
![]() |
![]() |
Spostamento della videocamera in corso...
L'API di Google Maps ti consente di modificare la parte del mondo visibile sulla mappa. Ciò si ottiene modificando la posizione della fotocamera (anziché sullo spostamento della mappa).
Quando cambi la videocamera, hai la possibilità di animare il movimento della videocamera risultante. L'animazione interpola tra gli attributi della videocamera corrente e quelli nuovi. Puoi anche controllare la durata dell'animazione.
Per cambiare la posizione della videocamera, devi specificare dove vuoi
spostare la videocamera, utilizzando una CameraUpdate
. L'API di Google Maps
consente di creare vari tipi 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()
offrono un CameraUpdate
che cambia il livello di zoom di 1,0, mantenendo
le stesse proprietà.
CameraUpdateFactory.zoomTo(float)
ti fornisce un CameraUpdate
che modifica il livello di zoom sul valore specificato, mantenendo invariate le altre proprietà.
CameraUpdateFactory.zoomBy(float)
e
CameraUpdateFactory.zoomBy(float, Point)
forniscono un CameraUpdate
che aumenta (o diminuisce, se il valore è
negativo) del livello di zoom in base al valore specificato. Quest'ultimo corregge il punto specifico
sullo schermo in modo che rimanga nella stessa posizione (longitudine/longitudine)
e potrebbe cambiare la posizione della videocamera per raggiungere questo obiettivo.
Potresti trovare utile impostare un livello minimo e/o massimo di zoom. Ad esempio, questa impostazione è 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 riquadri personalizzato con un insieme limitato di livelli di zoom.
Java
private GoogleMap map; map.setMinZoomPreference(6.0f); map.setMaxZoomPreference(14.0f);
Kotlin
private lateinit var map: GoogleMap 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 eseguire lo zoom troppo in basso o troppo in alto. Ad esempio, il satellite o il rilievo potrebbero avere uno zoom massimo inferiore rispetto ai riquadri della mappa di base.
Modifica della posizione della fotocamera
Esistono due metodi pratici per i cambi di posizione più comuni.
CameraUpdateFactory.newLatLng(LatLng)
offre un CameraUpdate
che cambia la latitudine e la longitudine della fotocamera,
mantenendo le altre proprietà.
CameraUpdateFactory.newLatLngZoom(LatLng, float)
ti offre un CameraUpdate
che modifica
la latitudine, la longitudine e lo zoom della fotocamera, mantenendo inalterate tutte le altre proprietà.
Per una maggiore flessibilità nel cambiare la posizione della fotocamera, utilizza
CameraUpdateFactory.newCameraPosition(CameraPosition)
che ti offre una CameraUpdate
che sposta la fotocamera nella
posizione specificata. È possibile ottenere un CameraPosition
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 in base al numero di pixel specificato. Un valore x positivo fa sì che la fotocamera si muova a destra, in modo che la mappa appaia come spostata a sinistra. Un valore y positivo fa sì che la videocamera si sposti verso il basso, in modo che la mappa sembri spostata in alto. Al contrario, valori x negativi fanno sì che la fotocamera si muova a sinistra, in modo che
la mappa sembri avere spostato a destra e valori y negativi fanno sì che
la fotocamera si sposti verso l'alto. Lo scorrimento è relativo all'orientamento attuale della videocamera. Ad esempio, se la fotocamera ha un cuscinetto di 90 gradi, allora est è "su".
Definizione dei confini
Impostazione dei confini della mappa
A volte è utile spostare la fotocamera in modo che un'intera area di interesse sia visibile al massimo livello di zoom possibile. Ad esempio, se stai visualizzando tutte le stazioni di servizio entro cinque chilometri dalla posizione attuale dell'utente, potresti voler spostare la videocamera in modo che sia tutte visibili sullo schermo. Per farlo, devi prima calcolare il
LatLngBounds
che vuoi rendere visibile sullo schermo. Puoi quindi utilizzare CameraUpdateFactory.newLatLngBounds(LatLngBounds bounds, int
padding)
per ottenere un CameraUpdate
che cambia la posizione della fotocamera in modo che l'elemento LatLngBounds
specificato si adatti interamente alla mappa, tenendo conto della spaziatura interna (in pixel) specificata. Il CameraUpdate
restituito garantisce che il divario (in pixel) tra i limiti specificati e il bordo della mappa sia almeno pari alla spaziatura interna specificata. Tieni presente che l'inclinazione e il cuscinetto della mappa saranno entrambi pari a 0.
Java
LatLngBounds australiaBounds = new LatLngBounds( new LatLng(-44, 113), // SW bounds new LatLng(-10, 154) // NE bounds ); map.moveCamera(CameraUpdateFactory.newLatLngBounds(australiaBounds, 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))
Centrare la mappa all'interno di un'area
In alcuni casi, potresti voler centrare la fotocamera entro i confini anziché
includere i bordi estremi. Ad esempio, centrando la fotocamera in un paese
mantenendo uno zoom costante. In questo caso, puoi utilizzare un metodo simile creando un elemento LatLngBounds
e utilizzando CameraUpdateFactory.newLatLngZoom(LatLng latLng, float zoom)
con LatLngBounds
.Metodo getCenter()
. Il metodo getCenter() restituirà il centro geografico del LatLngBounds
.
Java
LatLngBounds australiaBounds = new LatLngBounds( new LatLng(-44, 113), // SW bounds new LatLng(-10, 154) // NE bounds ); map.moveCamera(CameraUpdateFactory.newLatLngZoom(australiaBounds.getCenter(), 10));
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))
Un sovraccarico del metodo, newLatLngBounds(boundary, width, height,
padding)
ti consente di specificare una larghezza e un'altezza in pixel per un rettangolo, con l'intenzione che corrispondano alle dimensioni della mappa. Il rettangolo è posizionato in modo che il suo centro sia lo stesso della vista della mappa (in modo che se le dimensioni specificate sono uguali a quelle della visualizzazione della mappa, il rettangolo coincide con la visualizzazione della mappa). L'oggetto CameraUpdate
restitato sposterà la fotocamera in modo cheLatLngBounds
sia centrato sullo schermo all'interno del rettangolo specificato al livello di zoom più alto possibile, tenendo conto dell'imbottitura richiesta.
Nota: utilizza il metodo più semplice newLatLngBounds(boundary, padding)
per generare un CameraUpdate
solo se verrà utilizzato per spostare la fotocamera dopo che la mappa ha subito un layout. Durante il layout, l'API
calcola i confini di visualizzazione della mappa, necessari per proiettare correttamente
il riquadro di delimitazione. In confronto, puoi utilizzare l'elemento CameraUpdate
restituito dal metodo più complesso newLatLngBounds(boundary, width, height, padding)
in qualsiasi momento, anche prima che la mappa abbia subito un layout, perché l'API calcola i limiti di visualizzazione dagli argomenti trasmessi.
Limitazione della panoramica dell'utente a una determinata area
Negli scenari sopra indicati, hai impostato i limiti della mappa, ma l'utente può quindi scorrere o scorrere al di fuori di questi limiti. Ti consigliamo invece di vincolare i limiti di latitudine/longitudine del punto focale della mappa (il target della fotocamera) in modo che gli utenti possano scorrere e scorrere solo all'interno di questi limiti. Ad esempio, un'app di vendita al dettaglio per un centro commerciale o un aeroporto potrebbe voler limitare la mappa a particolari confini, consentendo agli utenti di scorrere e spostarsi all'interno di quei confini.
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);
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)
Il seguente diagramma illustra uno scenario in cui il target della fotocamera è limitato a un'area leggermente più grande dell'area visibile. L'utente può scorrere e eseguire la panoramica, a condizione che il target della videocamera rimanga all'interno dell'area delimitata. La croce rappresenta il target della fotocamera:
La mappa riempie sempre l'area visibile, anche se in questo modo l'area visibile mostra aree esterne ai confini definiti. Ad esempio, se posizioni il target della fotocamera 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 videocamera:
Nel diagramma seguente, il target della fotocamera ha dei limiti molto limitati, offrendo all'utente una minima opportunità di scorrere la mappa. La croce rappresenta il target della videocamera:
Aggiornamento dell'inquadratura della fotocamera
Per applicare una CameraUpdate
alla mappa, puoi spostare la fotocamera all'istante o animarla senza problemi. Per spostare la fotocamera all'istante con il dispositivo CameraUpdate
specificato, puoi chiamare GoogleMap.moveCamera(CameraUpdate)
.
Puoi rendere l'esperienza utente più piacevole, soprattutto per gli spostamenti brevi, animando la modifica. Per farlo, anziché chiamare
GoogleMap.moveCamera
chiama
GoogleMap.animateCamera
.
La mappa si sposterà senza problemi con i nuovi attributi. La forma più dettagliata di questo metodo, GoogleMap.animateCamera(cameraUpdate, duration, callback)
, offre tre argomenti:
cameraUpdate
- La
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 le animazioni, i metodi sono chiamati nelle seguenti circostanze:onFinish()
- Richiamato se l'animazione va a buon fine senza interruzioni.
onCancel()
-
Richiamato se l'animazione viene interrotta chiamando
stopAnimation()
o avviando un nuovo movimento della videocamera.In alternativa, questo problema può verificarsi anche se chiami
GoogleMap.stopAnimation()
.
duration
- Durata desiderata dell'animazione, in millisecondi, espressa come
int
.
I seguenti snippet di codice illustrano alcuni dei modi più comuni per spostare la videocamera.
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));
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))