Android Academy · Lección

Cómo mostrar un mapa

Añada Google Maps a su aplicación

Cómo mostrar un mapa es una lección gratuita de Android Academy en CoddyKit. Esta es la lección 1 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Android Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Android Academy incluye 4 lecciones en total.

Poner su aplicación en el mapa

Los mapas convierten las coordenadas sin procesar en algo que los usuarios pueden ver y explorar. En esta lección añadirá un Google Map interactivo a una pantalla de Jetpack Compose mediante la biblioteca oficial maps-compose.

Al final podrá insertar un mapa real, que se puede desplazar y ampliar, en cualquier composable. Vamos a preparar los componentes básicos.

La biblioteca Maps Compose

Google ofrece un contenedor compatible con Compose llamado maps-compose. Expone un composable GoogleMap, por lo que nunca tendrá que interactuar directamente con el antiguo MapView de XML.

Añada estas dependencias al build.gradle.kts de su módulo. El artefacto play-services-maps es el SDK subyacente; maps-compose lo adapta para 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")
}

Obtener una clave de API

Google Maps requiere una clave de API. Cree una en Google Cloud Console, habilite Maps SDK for Android y coloque la clave en su AndroidManifest.xml, dentro de la etiqueta <application>.

Nunca incluya la clave directamente en el código fuente que publique en un repositorio. Guárdela en local.properties e inyéctela mediante el marcador de posición del manifiesto.

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

Su primer GoogleMap

El mapa más sencillo es un único composable GoogleMap. Asígnele un Modifier.fillMaxSize() y obtendrá al instante un mapa que se puede desplazar y ampliar.

No necesita elementos secundarios para mostrarse: las teselas de Google se renderizan automáticamente cuando la clave de API es válida.

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

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

Controlar la cámara

La cámara determina qué zona muestra el mapa y el nivel de ampliación. Debe proporcionar un CameraPositionState recordado entre recomposiciones.

Cree un CameraPosition a partir de un LatLng (latitud y longitud), además de un nivel de zoom. Cuanto mayor sea el zoom, más cerca se verá la zona.

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)
}

Conectar la cámara al mapa

Pase ese cameraPositionState a GoogleMap para que el mapa se abra centrado donde desee. Como el estado se conserva, los desplazamientos y cambios de zoom del usuario se mantienen después de la recomposición.

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

Propiedades del mapa

MapProperties configura lo que muestra el mapa. Entre las opciones habituales se encuentran el tipo de mapa (normal, satélite, terreno o híbrido) y si está habilitado el punto azul de mi ubicación.

Recuerde el objeto de propiedades para que no se reconstruya en cada recomposición.

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

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

Configuración de la interfaz del mapa

MapUiSettings activa o desactiva los controles en pantalla: los botones de zoom, la brújula, el botón de mi ubicación y los gestos.

Desactive los controles que no necesite para obtener un aspecto más limpio; por ejemplo, oculte los botones de zoom, pero mantenga habilitados los gestos de pellizcar para ampliar.

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

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

Unir todos los elementos

Combine la cámara, las propiedades y la configuración de la interfaz en un mapa configurado. Esta es la estructura habitual de una pantalla de mapa en producción.

@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
    )
}

Reaccionar a los clics en el mapa

GoogleMap expone callbacks como onMapClick. Úselos para responder cuando el usuario toque el mapa; por ejemplo, para capturar un LatLng seleccionado.

Conserve el punto tocado en el estado para que la interfaz pueda reaccionar a él.

@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}")
    }
}

El ciclo de vida se gestiona automáticamente

Con el MapView clásico de XML, tenía que reenviar manualmente cada evento del ciclo de vida. La biblioteca maps-compose conecta el mapa con el ciclo de vida de la composición de forma automática.

Esto significa que no necesita gestionar manualmente onResume/onPause/onDestroy; es una razón más para preferir la API de Compose en las pantallas nuevas.

Comprobación rápida

¿Qué objeto de estado componible debe recordar y pasar a GoogleMap para controlar dónde se centra el mapa y su nivel de zoom?

Resumen

Ahora puede colocar un mapa de Google real en Compose:

Añada maps-compose + play-services-maps y una clave de API en el manifiesto.
Represente un mapa con el componible GoogleMap.
Centre el mapa y ajuste su zoom con rememberCameraPositionState y CameraPosition.
Personalícelo con MapProperties y MapUiSettings, y reaccione a los toques con onMapClick.

A continuación: obtener la ubicación real del dispositivo para centrar el mapa en el usuario.

Preguntas frecuentes

¿La lección «Cómo mostrar un mapa» es gratis?

Sí — el texto completo de «Cómo mostrar un mapa» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Android Academy, actualiza a CoddyKit PRO. El curso de Android Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Cómo mostrar un mapa»?

Añada Google Maps a su aplicación Practicas Android Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar Android Academy?

No se requiere experiencia previa. Android Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 1 de 4.

¿Cuánto tiempo toma la lección «Cómo mostrar un mapa»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de Android Academy?

Sí. Cada lección de Android Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

Cómo mostrar un mapa
Cómo obtener la ubicación del usuario
Marcadores y cámara
Permisos de ubicación correctamente implementados

← Volver a Android Academy