0Pricing
Android Academy · Aula

Exibindo um mapa

Adicione Google Maps ao seu aplicativo.

Exibindo um mapa é uma aula grátis de Android Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Android Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Android Academy inclui 4 aulas no total.

Colocando seu aplicativo no mapa

Os mapas transformam coordenadas brutas em algo que os usuários podem ver e explorar. Nesta lição, você adicionará um Google Map interativo a uma tela do Jetpack Compose usando a biblioteca oficial maps-compose.

Ao final, você poderá inserir um mapa real, que pode ser movido e ampliado, em qualquer composable. Vamos preparar os blocos básicos.

A biblioteca Maps Compose

O Google fornece um wrapper compatível com Compose chamado maps-compose. Ele expõe um composable GoogleMap, para que você nunca precise acessar diretamente o antigo MapView em XML.

Adicione estas dependências ao módulo no seu build.gradle.kts. O artefato play-services-maps é o SDK subjacente; maps-compose faz a adaptação para o 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")
}

Obtendo uma chave de API

O Google Maps exige uma chave de API. Crie uma no Google Cloud Console, ative o Maps SDK for Android e coloque a chave no seu AndroidManifest.xml, dentro da tag <application>.

Nunca inclua a chave diretamente no código-fonte que você publica em um repositório público. Armazene-a em local.properties e injete-a por meio do marcador de posição do manifesto.

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

Seu primeiro GoogleMap

O mapa mais simples é um único composable GoogleMap. Forneça a ele um Modifier.fillMaxSize() e você terá instantaneamente um mapa que pode ser movido e ampliado.

Nenhum filho é necessário para exibi-lo — os blocos do Google são renderizados automaticamente assim que sua chave de API é válida.

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

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

Controlando a câmera

A câmera determina para onde o mapa aponta e o nível de ampliação. Você fornece um CameraPositionState mantido entre as recomposições.

Crie um CameraPosition a partir de um LatLng (latitude e longitude) e de um nível de zoom. Quanto maior o zoom, mais próxima será a visualização.

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

Integrando a câmera ao mapa

Passe esse cameraPositionState para GoogleMap para que o mapa seja aberto centralizado onde você quiser. Como o estado é lembrado, os movimentos e os zooms do usuário são preservados durante a recomposição.

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

Propriedades do mapa

MapProperties configura o que o mapa exibe. As opções comuns incluem o tipo de mapa (normal, satélite, terreno, híbrido) e se o ponto azul de minha localização está ativado.

Lembre-se do objeto de propriedades para que ele não seja recriado a cada recomposição.

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

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

Configurações da interface do mapa

MapUiSettings ativa ou desativa os controles na tela: botões de zoom, bússola, botão de minha localização e gestos.

Desative os controles de que você não precisa para obter uma aparência mais limpa — por exemplo, oculte os botões de zoom, mas mantenha os gestos de zoom com pinça ativados.

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

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

Juntando tudo

Combine a câmera, as propriedades e as configurações da interface em um único mapa configurado. Essa é a estrutura típica de uma tela de mapa em produção.

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

Reagindo a toques no mapa

GoogleMap disponibiliza retornos de chamada como onMapClick. Use-os para reagir quando o usuário tocar no mapa — por exemplo, para capturar um LatLng escolhido.

Mantenha o ponto tocado no estado para que a interface possa reagir a ele.

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

O ciclo de vida é gerenciado para você

Com o MapView XML clássico, era necessário encaminhar manualmente cada evento do ciclo de vida. A biblioteca maps-compose conecta o mapa ao ciclo de vida da composição de forma automática.

Isso significa que não é necessário gerenciar manualmente onResume/onPause/onDestroy — mais um motivo para preferir a API do Compose em telas novas.

Verificação rápida

Qual objeto de estado composable você deve lembrar e passar para GoogleMap para controlar onde o mapa fica centralizado e qual é o nível de zoom?

Recapitulação

Agora você já consegue inserir um mapa real do Google no Compose:

  • Adicione maps-compose + play-services-maps e uma chave de API no manifesto.
  • Renderize um mapa com o composable GoogleMap.
  • Centralize e aplique zoom usando rememberCameraPositionState e CameraPosition.
  • Personalize-o com MapProperties e MapUiSettings, e reaja a toques com onMapClick.

A seguir: obter a localização real do dispositivo para centralizar o mapa no usuário.

Perguntas Frequentes

A aula “Exibindo um mapa” é grátis?

Sim — o texto completo de “Exibindo um mapa” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Android Academy, atualize para CoddyKit PRO. O curso de Android Academy inclui 4 aulas no total.

O que vou aprender em “Exibindo um mapa”?

Adicione Google Maps ao seu aplicativo. Você pratica Android Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Android Academy?

Nenhuma experiência prévia é necessária. Android Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “Exibindo um mapa”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Android Academy?

Sim. Cada aula de Android Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Exibindo um mapa
  2. Obtendo a localização do usuário
  3. Marcadores e câmera
  4. Permissões de localização do jeito certo
← Voltar para Android Academy