API de geolocalização em componentes React

navigator.geolocation.getCurrentPosition(successCallback, errorCallback, options) solicita a localização do dispositivo uma vez. O retorno de chamada de sucesso recebe um objeto GeolocationPosition. Isso é apropriado quando você precisa da localização uma única vez, como ao encontrar a loja mais próxima depois de um clique em um botão, em vez de acompanhar um movimento contínuo.

navigator.geolocation.watchPosition(successCallback, errorCallback, options) dispara continuamente o retorno de chamada sempre que a posição do dispositivo muda. Ele retorna um watchId numérico. Isso é adequado para casos de uso em tempo real, como acompanhamento de entregas ou navegação curva a curva, nos quais a posição precisa permanecer atualizada.

O objeto GeolocationPosition contém uma propriedade coords com latitude, longitude e accuracy (em metros). Os campos opcionais adicionais incluem altitude, altitudeAccuracy, heading e speed. O campo timestamp registra quando a posição foi capturada.

O retorno de chamada de erro recebe um GeolocationPositionError com uma propriedade code numérica. O código 1 é PERMISSION_DENIED (o usuário recusou), o código 2 é POSITION_UNAVAILABLE (falha de hardware ou de rede) e o código 3 é TIMEOUT (a solicitação demorou demais). Sempre trate os três casos.

Um ouvinte de watchPosition é executado indefinidamente até que você o interrompa. Em useEffect, retorne uma função de limpeza que chame navigator.geolocation.clearWatch(watchId). Se você esquecer a limpeza, o acompanhamento continuará sendo executado depois que o componente for desmontado, consumindo a bateria e podendo atualizar um estado desmontado.

Um gancho useGeolocation gerencia um estado de status com quatro valores possíveis: idle (ainda não solicitado), loading (solicitação em andamento), success (posição recebida) e error (falha). Ele também mantém position e errorMessage no estado. Os componentes recebem uma interface clara e consistente.

Quando o usuário recusar a geolocalização, mostre uma mensagem útil explicando por que o recurso precisa de acesso à localização e como reativá-lo nas configurações do navegador. Nunca mostre um código de erro bruto aos usuários. Ofereça uma alternativa de inserção manual de endereço para que o recurso continue utilizável sem a permissão de localização.

Assim como a maioria das APIs poderosas do navegador, a geolocalização é restrita a contextos seguros. navigator.geolocation é undefined em páginas HTTP comuns. Durante o desenvolvimento em localhost, ela funciona sem HTTPS. Em produção, sempre garanta que seu aplicativo seja servido por HTTPS, ou os usuários nunca receberão uma solicitação de permissão.

O terceiro argumento opcional de getCurrentPosition e watchPosition aceita um objeto de opções. enableHighAccuracy: true solicita precisão no nível do GPS, consumindo mais energia. timeout define o tempo máximo de espera em milissegundos. maximumAge permite uma posição armazenada em cache se ela tiver sido capturada dentro do número de milissegundos especificado.

A geolocalização possibilita recursos como "encontrar uma loja perto de mim", acompanhamento de entregadores em um mapa, previsão do tempo com base na cidade atual, publicações marcadas com a localização e cálculos de distância entre o usuário e um destino. Sempre explique claramente aos usuários por que o aplicativo precisa da localização deles antes de solicitar permissão.

O Chrome DevTools permite definir uma localização falsa para o dispositivo. Abra o DevTools, acesse o menu de três pontos, selecione Mais ferramentas e, em seguida, Sensores. Você pode digitar coordenadas de latitude e longitude para simular qualquer localização. Isso é muito mais rápido do que viajar fisicamente para testar recursos que dependem da localização.

O que significa um código 1 de GeolocationPositionError?

Use getCurrentPosition para uma leitura única e watchPosition para o acompanhamento contínuo. Sempre chame clearWatch na função de limpeza de useEffect. Crie um gancho useGeolocation com os estados idle, loading, success e error. Trate a recusa de permissão com cuidado e lembre-se de que a geolocalização exige HTTPS em produção.