Android Academy · Lezione

Mostrare una mappa

Aggiunga Google Maps alla sua app

Mostrare una mappa è una lezione Android Academy gratuita su CoddyKit. Questa è la lezione 1 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Android Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Android Academy include 4 lezioni in totale.

Portare l'app sulla mappa

Le mappe trasformano coordinate grezze in qualcosa che gli utenti possono vedere ed esplorare. In questa lezione aggiungerà una Google Map interattiva a una schermata Jetpack Compose utilizzando la libreria ufficiale maps-compose.

Al termine sarà in grado di inserire una mappa reale, esplorabile con panoramiche e zoom, in qualsiasi composable. Prepariamo gli elementi fondamentali.

La libreria Maps Compose

Google fornisce un wrapper compatibile con Compose chiamato maps-compose. Espone il composable GoogleMap, così non deve interagire direttamente con la vecchia MapView XML.

Aggiunga queste dipendenze al file build.gradle.kts del modulo. L'artefatto play-services-maps è l'SDK sottostante; maps-compose lo adatta a Compose.

// build.gradle.kts (module)
dependencies {
    implementation("com.google.maps.android:maps-compose:6.1.0")
    implementation("com.google.android.gms:play-services-maps:19.0.0")
}

Ottenere una chiave API

Google Maps richiede una chiave API. Ne crei una nella Google Cloud Console, abiliti Maps SDK for Android e inserisca poi la chiave in AndroidManifest.xml, all'interno del tag <application>.

Non inserisca mai la chiave direttamente nel codice sorgente che pubblica. La memorizzi in local.properties e la inietti tramite il placeholder del manifest.

<!-- AndroidManifest.xml, inside <application> -->
<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

Il primo GoogleMap

La mappa più semplice è costituita da un singolo composable GoogleMap. Gli assegni un Modifier.fillMaxSize() e otterrà subito una mappa esplorabile con panoramiche e zoom.

Non ha bisogno di elementi figli per essere visualizzata: i riquadri di Google vengono renderizzati automaticamente non appena la chiave API è valida.

import com.google.maps.android.compose.GoogleMap

@Composable
fun MapScreen() {
    GoogleMap(
        modifier = Modifier.fillMaxSize()
    )
}

Controllare la fotocamera

La fotocamera determina quale area della mappa viene visualizzata e il livello di zoom. Deve fornire un CameraPositionState memorizzato tra le ricomposizioni.

Crei un CameraPosition a partire da un LatLng (latitudine, longitudine) e da un livello di zoom. Un livello di zoom più alto significa una visuale più ravvicinata.

import com.google.android.gms.maps.model.CameraPosition
import com.google.android.gms.maps.model.LatLng
import com.google.maps.android.compose.rememberCameraPositionState

val sanFrancisco = LatLng(37.7749, -122.4194)
val cameraPositionState = rememberCameraPositionState {
    position = CameraPosition.fromLatLngZoom(sanFrancisco, 12f)
}

Collegare la fotocamera alla mappa

Passi cameraPositionState a GoogleMap per aprire la mappa centrata nel punto desiderato. Poiché lo stato viene conservato, gli spostamenti e gli zoom dell'utente vengono mantenuti durante la ricomposizione.

@Composable
fun CenteredMap() {
    val sf = LatLng(37.7749, -122.4194)
    val cameraPositionState = rememberCameraPositionState {
        position = CameraPosition.fromLatLngZoom(sf, 12f)
    }
    GoogleMap(
        modifier = Modifier.fillMaxSize(),
        cameraPositionState = cameraPositionState
    )
}

Proprietà della mappa

MapProperties configura ciò che viene visualizzato sulla mappa. Tra le opzioni più comuni ci sono il tipo di mappa (normale, satellitare, terreno, ibrida) e l'abilitazione del punto blu della mia posizione.

Ricordi l'oggetto delle proprietà, così non viene ricreato a ogni ricomposizione.

import com.google.maps.android.compose.MapProperties
import com.google.maps.android.compose.MapType

val properties = remember {
    MapProperties(
        mapType = MapType.NORMAL,
        isMyLocationEnabled = false
    )
}

Impostazioni dell'interfaccia della mappa

MapUiSettings attiva o disattiva i controlli visualizzati: pulsanti dello zoom, bussola, pulsante della mia posizione e gesti.

Disabiliti i controlli che non servono per ottenere un aspetto più ordinato: ad esempio, nasconda i pulsanti dello zoom mantenendo attivi i gesti di zoom con pizzico.

import com.google.maps.android.compose.MapUiSettings

val uiSettings = remember {
    MapUiSettings(
        zoomControlsEnabled = false,
        compassEnabled = true,
        scrollGesturesEnabled = true,
        zoomGesturesEnabled = true
    )
}

Unire tutti gli elementi

Combini la fotocamera, le proprietà e le impostazioni dell'interfaccia in un'unica mappa configurata. Questa è la struttura tipica di una schermata di mappa pronta per la produzione.

@Composable
fun ConfiguredMap() {
    val sf = LatLng(37.7749, -122.4194)
    val cameraPositionState = rememberCameraPositionState {
        position = CameraPosition.fromLatLngZoom(sf, 12f)
    }
    val properties = remember { MapProperties(mapType = MapType.NORMAL) }
    val uiSettings = remember { MapUiSettings(zoomControlsEnabled = false) }

    GoogleMap(
        modifier = Modifier.fillMaxSize(),
        cameraPositionState = cameraPositionState,
        properties = properties,
        uiSettings = uiSettings
    )
}

Reagire ai clic sulla mappa

GoogleMap espone callback come onMapClick. Le utilizzi per reagire quando l'utente tocca la mappa, ad esempio per acquisire un LatLng scelto.

Conservi il punto toccato nello stato, così l'interfaccia può reagire di conseguenza.

@Composable
fun ClickableMap() {
    var picked by remember { mutableStateOf<LatLng?>(null) }
    GoogleMap(
        modifier = Modifier.fillMaxSize(),
        onMapClick = { latLng -> picked = latLng }
    )
    picked?.let { p ->
        Text("Picked: ${p.latitude}, ${p.longitude}")
    }
}

Il ciclo di vita viene gestito automaticamente

Con il classico MapView XML era necessario inoltrare manualmente ogni evento del ciclo di vita. La libreria maps-compose collega automaticamente la mappa al ciclo di vita della composizione.

Questo significa che non è necessario gestire manualmente onResume/onPause/onDestroy: un motivo in più per preferire l'API Compose nelle nuove schermate.

Verifica rapida

Quale oggetto di stato composable deve essere ricordato e passato a GoogleMap per controllare il centro e il livello di zoom della mappa?

Riepilogo

Ora è in grado di inserire una vera mappa Google in Compose:

Aggiunga maps-compose + play-services-maps e una chiave API nel manifest.
Visualizzi una mappa con il composable GoogleMap.
La centri e ne imposti lo zoom con rememberCameraPositionState e CameraPosition.
La personalizzi con MapProperties e MapUiSettings, e reagisca ai tocchi con onMapClick.

Prossimo argomento: ottenere la posizione effettiva del dispositivo per centrare la mappa sull'utente.

Domande Frequenti

La lezione «Mostrare una mappa» è gratuita?

Sì — il testo completo di «Mostrare una mappa» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Android Academy, passa a CoddyKit PRO. Il corso Android Academy include 4 lezioni in totale.

Cosa imparerò in «Mostrare una mappa»?

Aggiunga Google Maps alla sua app Eserciti Android Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare Android Academy?

Non è richiesta alcuna esperienza precedente. Android Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 1 di 4.

Quanto tempo richiede la lezione «Mostrare una mappa»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione Android Academy?

Sì. Ogni lezione Android Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

Mostrare una mappa
Ottenere la posizione dell'utente
Marcatori e videocamera
Gestire correttamente i permessi di posizione

← Torna a Android Academy