12k
All articles

Adicionando mapas nativos a um app React Native

Configure o expo-maps no React Native com Apple Maps e Google Maps, marcadores compartilhados, permissões de localização, câmera, chave Android e limites do iOS.

OpenReplay Team
OpenReplay Team
Adicionando mapas nativos a um app React Native

Instale o expo-maps em um development build e, em seguida, renderize AppleMaps.View no iOS e GoogleMaps.View no Android. Os dois componentes recebem os mesmos dados de câmera, marcadores e localização, então um único wrapper atende às duas plataformas.

A maioria dos tutoriais de mapas para React Native é escrita para o react-native-maps, e as props usadas neles não funcionam na biblioteca da Expo. Se você copiar um trecho com <MapView> para um projeto com expo-maps, vai receber erros de tipo em tudo, inclusive na câmera.

Este guia cobre o fluxo completo no expo-maps: escolher a biblioteca, gerar o build do app, adicionar a chave de API do Android, renderizar um mapa nas duas plataformas, adicionar marcadores, centralizar o mapa no usuário e tratar toques em marcadores. Também aborda os limites de versão do iOS que determinam quais recursos você pode usar. Se você prefere tiles vetoriais e estilos personalizados do Mapbox, veja como criar um mapa em React Native com Mapbox.

Principais pontos

  • O expo-maps exibe o Apple Maps no iOS e o Google Maps no Android por meio de dois componentes, AppleMaps.View e GoogleMaps.View, e não oferece suporte ao Google Maps no iOS.
  • Execute o expo-maps em um development build. O Apple Maps não precisa de chave de API, mas o Android exige uma chave do Google Maps em android.config.googleMaps.apiKey no app.json, seguida de um novo build.
  • cameraPosition define apenas a posição inicial do mapa. Para mover a câmera depois, chame setCameraPosition em uma ref do mapa.
  • A documentação da Expo indica o iOS 17 como versão mínima para o expo-maps, e callbacks de toque em marcadores, como onMarkerClick, exigem o iOS 18.

Você deve usar expo-maps ou react-native-maps?

Para um projeto Expo que já usa development builds, escolha o expo-maps. Escolha o react-native-maps se você precisar do Google Maps no iOS ou de rodar o app no Expo Go. O expo-maps é a biblioteca de mapas da própria Expo e renderiza por meio de SwiftUI no iOS e Jetpack Compose no Android. O react-native-maps é mantido pela comunidade e oferece uma única API MapView que funciona com vários provedores de mapas.

expo-mapsreact-native-maps
Desenvolvido porEquipe da ExpoComunidade
Camada nativaSwiftUI (iOS), Jetpack Compose (Android)Um componente MapView
Provedor no iOSSomente Apple MapsApple Maps ou Google Maps
Versão mínima do iOSiOS 17, segundo a documentação da Expo; o README do pacote indica iOS 18.0Não abordado aqui
Expo GoUse um development buildIncluído no Expo Go, segundo a documentação da Expo
Componentes React como marcadoresNão suportado (use marcadores com imagem)Suportado
Formato da APIDois componentes por plataformaUm componente

No lançamento, o anúncio do expo-maps descrevia a biblioteca como alfa: “Com o SDK 53, estamos lançando nossa versão alfa do expo-maps.” A página de referência do SDK 58 não exibe nenhum rótulo de status. Consulte a referência do expo-maps para verificar o status atual antes de ir para produção. A página do react-native-maps na documentação da Expo cobre a outra opção.

Instale o expo-maps e crie um development build

O expo-maps precisa de duas coisas: o pacote e um binário nativo (um development build) que o inclua. Instale o pacote com a Expo CLI para que a versão seja compatível com o seu SDK:

npx expo install expo-maps expo-location expo-dev-client
npx expo run:ios      # or: npx expo run:android

O expo-location fornece as coordenadas do usuário mais adiante neste guia. O expo-dev-client transforma o binário em um development build. A documentação do expo-maps descreve apenas a execução em um development build, então use um. Você também pode gerar o build na nuvem com o EAS. Para um projeto pronto, npx create-expo-app --example with-maps já vem com o expo-maps instalado e configurado.

Adicione a chave de API do Google Maps para Android

O Apple Maps funciona sem chave. Já o Google Maps no Android precisa de uma chave de API do Google Cloud com o Maps SDK for Android ativado, adicionada ao app.json, seguida de um novo build do app.

  1. Crie um projeto no Google Cloud e ative o Maps SDK for Android.
  2. Crie uma chave de API e restrinja-a a apps Android usando o nome do seu pacote e a impressão digital SHA-1 do seu certificado de assinatura. Para builds com EAS, o comando eas credentials exibe a impressão digital.
  3. Adicione a chave e o plugin de permissão de localização ao app.json:
{
  "expo": {
    "android": {
      "package": "com.example.places",
      "config": {
        "googleMaps": { "apiKey": "YOUR_ANDROID_MAPS_KEY" }
      }
    },
    "plugins": [
      [
        "expo-maps",
        {
          "requestLocationPermission": true,
          "locationPermission": "Allow $(PRODUCT_NAME) to show your position on the map"
        }
      ]
    ]
  }
}
  1. Gere um novo build com npx expo run:android. Um reload do JavaScript não aplica alterações na configuração nativa.

Nas opções do plugin, requestLocationPermission é um booleano que adiciona as permissões ao AndroidManifest.xml e ao Info.plist, e locationPermission define a mensagem de uso, exclusiva do iOS. O app.json não consegue ler variáveis de ambiente. Para manter a chave fora do controle de versão, mova o mesmo caminho android.config.googleMaps.apiKey para o app.config.js e leia a chave a partir de process.env nesse arquivo.

Exiba um mapa nas duas plataformas

O expo-maps não tem um componente multiplataforma, então escreva um pequeno wrapper que escolha AppleMaps.View ou GoogleMaps.View com base em Platform.OS e passe o mesmo cameraPosition para os dois. Um CameraPosition é um objeto com coordinates e zoom:

import { Platform, Text } from 'react-native';
import { AppleMaps, GoogleMaps } from 'expo-maps';

const START = { coordinates: { latitude: 51.5074, longitude: -0.1278 }, zoom: 12 };

export function BasicMap() {
  if (Platform.OS === 'ios') return <AppleMaps.View style={{ flex: 1 }} cameraPosition={START} />;
  if (Platform.OS === 'android') return <GoogleMaps.View style={{ flex: 1 }} cameraPosition={START} />;
  return <Text>Maps are only available on Android and iOS.</Text>;
}

O último branch trata a web e qualquer outra plataforma, onde nenhum dos dois componentes existe.

Adicione marcadores a partir de um único array de dados

Tanto AppleMaps.View quanto GoogleMaps.View recebem um array markers, e os dois tipos de marcador aceitam id, title e coordinates. Isso significa que uma única função de mapeamento pode alimentar as duas plataformas. Adicione campos exclusivos de cada plataforma, como tintColor na Apple ou snippet no Google, usando spread sobre o marcador compartilhado:

type Place = { id: string; title: string; latitude: number; longitude: number };

export const PLACES: Place[] = [
  { id: 'office', title: 'Office', latitude: 51.5154, longitude: -0.141 },
  { id: 'cafe', title: 'Cafe', latitude: 51.5113, longitude: -0.1198 },
];

export const toMarker = (p: Place) => ({
  id: p.id,
  title: p.title,
  coordinates: { latitude: p.latitude, longitude: p.longitude },
});

// iOS:     markers={PLACES.map((p) => ({ ...toMarker(p), tintColor: '#e5484d' }))}
// Android: markers={PLACES.map((p) => ({ ...toMarker(p), snippet: 'Open now' }))}

O expo-maps não consegue renderizar componentes React como marcadores. Para pins personalizados, ele oferece suporte a ícones de imagem carregados com useImage do expo-image.

Como exibir a localização do usuário e centralizar o mapa nela?

Exibir a localização do usuário no expo-maps envolve três etapas: solicitar a permissão de localização, mostrar o ponto de localização depois que a permissão for concedida e mover a câmera quando as coordenadas chegarem. A permissão precisa ser declarada no build e solicitada em tempo de execução antes que o ponto possa aparecer. O hook useLocationPermissions do expo-maps retorna o status atual e uma função para solicitá-la.

TarefaAppleMaps.ViewGoogleMaps.View
Ponto de localizaçãoproperties.isMyLocationEnabledproperties.isMyLocationEnabled mais userLocation
Seguir o usuárioChamar setCameraPositionuserLocation.followUserLocation
Duração da animaçãoNão suportadoduration em ms

Só ative o ponto depois que a permissão for concedida. Uma issue reportada no Android mostrou que ativar isMyLocationEnabled sem a permissão fazia o app travar no Android, enquanto o iOS simplesmente ignorava. Uma correção foi incorporada ao branch principal da Expo em 4 de novembro de 2026, mas as versões mais antigas do expo-maps não a incluem, e condicionar o ponto à permissão funciona em todas as versões. A issue também destaca que a opção requestLocationPermission do config plugin apenas declara as permissões em tempo de build e nunca solicita nada em tempo de execução.

No expo-maps, a prop cameraPosition é documentada como a posição inicial da câmera do mapa, então alterá-la via state não é a forma documentada de mover a câmera. Em vez disso, chame setCameraPosition em uma ref. No iOS, a duração da animação não é suportada, e a promise retornada é resolvida quando a atualização da câmera é agendada, e não quando a animação termina.

import { useEffect, useRef, useState, type ComponentRef } from 'react';
import { Platform, Text, View } from 'react-native';
import { AppleMaps, GoogleMaps, useLocationPermissions } from 'expo-maps';
import * as Location from 'expo-location';
import { PLACES, toMarker } from './places';

const START = { coordinates: { latitude: 51.5074, longitude: -0.1278 }, zoom: 12 };
type Coords = { latitude: number; longitude: number };

export function PlacesMap({ onSelect }: { onSelect: (id: string) => void }) {
  const appleRef = useRef<ComponentRef<typeof AppleMaps.View>>(null);
  const [permission, requestPermission] = useLocationPermissions();
  const [me, setMe] = useState<Coords | null>(null);
  const granted = !!permission?.granted;

  useEffect(() => {
    if (permission && !permission.granted && permission.canAskAgain) requestPermission();
  }, [permission]);

  useEffect(() => {
    if (!granted) return;
    Location.getCurrentPositionAsync().then(({ coords }) => {
      const here = { latitude: coords.latitude, longitude: coords.longitude };
      setMe(here);
      appleRef.current?.setCameraPosition({ coordinates: here, zoom: 14 }); // iOS only; no duration
    });
  }, [granted]);

  const handleMarker = (m: { id?: string }) => m.id && onSelect(m.id);
  const denied = permission && !permission.granted && !permission.canAskAgain;

  const map =
    Platform.OS === 'ios' ? (
      <AppleMaps.View
        ref={appleRef}
        style={{ flex: 1 }}
        cameraPosition={START}
        markers={PLACES.map((p) => ({ ...toMarker(p), tintColor: '#e5484d' }))}
        properties={{ isMyLocationEnabled: granted }}
        onMarkerClick={handleMarker} // iOS 18+
      />
    ) : Platform.OS === 'android' ? (
      <GoogleMaps.View
        style={{ flex: 1 }}
        cameraPosition={START}
        markers={PLACES.map(toMarker)}
        properties={{ isMyLocationEnabled: granted }}
        userLocation={me ? { coordinates: me, followUserLocation: true } : undefined}
        onMarkerClick={handleMarker}
      />
    ) : (
      <Text>Maps are only available on Android and iOS.</Text>
    );

  return (
    <View style={{ flex: 1 }}>
      {map}
      {denied && <Text>Location is off. Enable it in Settings to see where you are.</Text>}
    </View>
  );
}

O Location.getCurrentPositionAsync fornece as coordenadas. No Android, followUserLocation mantém a câmera no usuário, então o código só chama setCameraPosition no iOS. Se a permissão for negada definitivamente, o mapa permanece em START e uma mensagem não bloqueante aparece abaixo dele.

Responda a toques em marcadores com onMarkerClick

Para tratar toques em marcadores no expo-maps, passe onMarkerClick para AppleMaps.View ou GoogleMaps.View. O callback recebe o marcador tocado, então você pode ler o id dele e encontrar o registro correspondente nos seus dados. No Android, isso funciona em todas as versões suportadas. No iOS, a documentação da Expo indica iOS 18.0+, e o mesmo limite se aplica aos demais callbacks de toque e à seleção programática com selectMarker e selectAnnotation.

Em dispositivos com iOS 17, o mapa continua sendo renderizado, mas tocar em um marcador não dispara nada no JavaScript. Se a interface baseada em toques for obrigatória, defina ios.deploymentTarget como 18.0 via expo-build-properties. Caso contrário, adicione uma lista abaixo do mapa que controle o mesmo estado de seleção, para que usuários do iOS 17 ainda consigam acessar cada local.

Conclusão

O expo-maps atende à tela de mapa mais comum com componentes nativos: Apple Maps no iOS, Google Maps no Android, um único array de dados compartilhado e um pequeno branch com Platform.OS. Em seguida, gere um novo build com sua chave do Android e teste em um dispositivo real com iOS 17 e em outro com iOS 18. É ali que as diferenças de toque e de permissão aparecem. Depois do lançamento, o session replay para React Native mostra as falhas que você não enxerga nos logs, como usuários arrastando o mapa à procura de um pin ou dispensando o pedido de localização. Assistir a essas sessões revela se o fluxo do mapa funciona para usuários reais.

Perguntas frequentes

Por que o mapa do Google funciona em desenvolvimento, mas fica em branco no build da Play Store?

Geralmente, a chave de API está restrita à impressão digital SHA-1 errada. Com a Assinatura de apps do Google Play, o Google assina novamente a versão de release, então o app instalado carrega o certificado de assinatura de apps do Google em vez da sua chave de upload ou de debug. Copie o SHA-1 do certificado de assinatura de apps na página Integridade do app do Play Console e adicione-o às restrições de app Android da chave. Mantenha também a impressão digital de desenvolvimento na chave.

O expo-maps consegue desenhar rotas, áreas ou círculos de raio?

Sim. Tanto AppleMaps.View quanto GoogleMaps.View aceitam as props polylines, polygons e circles. Cada prop recebe um array de formas construídas a partir de coordenadas, e um círculo recebe um centro e um raio em metros. O expo-maps desenha formas, mas não calcula rotas. Para um trajeto de carro ou a pé, obtenha a geometria da rota de um serviço de direções e passe as coordenadas decodificadas como uma polyline.

Como mudo o expo-maps para a visualização de satélite?

Defina mapType dentro da prop properties. No AppleMaps.View, use o enum AppleMapsMapType: STANDARD, IMAGERY (somente satélite) ou HYBRID (satélite com ruas e rótulos). No GoogleMaps.View, use GoogleMapsMapType: NORMAL, SATELLITE, HYBRID ou TERRAIN. Os nomes dos valores variam conforme a plataforma, então um wrapper compartilhado deve mapear uma única configuração, como 'satellite', para IMAGERY no iOS e SATELLITE no Android.

A permissão de localização concedida pelo expo-maps também vale para o expo-location?

Sim. O Android e o iOS concedem acesso à localização ao app como um todo, e não a uma biblioteca específica. Depois que o usuário aceita o pedido de localização em primeiro plano feito pelo hook useLocationPermissions do expo-maps, o expo-location enxerga a mesma permissão, então getCurrentPositionAsync é executado sem um segundo pedido. A localização em segundo plano é uma concessão separada nas duas plataformas e precisa de uma solicitação própria via expo-location.

DevTools for the frontend

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.

Star on GitHub12k

We use cookies to improve your experience. By using our site, you accept cookies.