Obter a localização do usuário

Use as APIs Windows.Devices.Geolocation para detectar a posição geográfica do dispositivo em um aplicativo SDK do Aplicativo Windows (WinUI 3). Você pode obter a localização uma única vez ou acompanhar a posição do usuário ao longo do tempo. Este artigo aborda o tratamento de permissões, leituras de localização única e contínua e como atualizar sua interface do usuário quando o local é alterado.

Note

As Windows.Devices.Geolocation APIs são APIs Windows Runtime (WinRT) que funcionam em aplicativos de área de trabalho UWP e WinUI 3. O código neste artigo usa padrões do WinUI 3 (como DispatcherQueue para serialização de threads).

Pré-requisitos

  • Um projeto WinUI 3 criado a partir do modelo Aplicativo em Branco, Empacotado (WinUI 3 na Área de Trabalho).
  • A funcionalidade Localização declarada no manifesto do pacote (consulte Habilitar a funcionalidade de localização).

Ativar a funcionalidade de localização

Seu aplicativo deve declarar a funcionalidade Local antes de poder acessar a posição do usuário.

  1. Em Gerenciador de Soluções, clique duas vezes em Package.appxmanifest e selecione a guia Recursos.
  2. Marque a caixa de seleção para Localização.

Isso adiciona a seguinte entrada ao manifesto:

<Capabilities>
    <DeviceCapability Name="location"/>
</Capabilities>

Tip

Para aplicativos não empacotados, a capacidade de Localização não é necessária no manifesto. No entanto, você ainda deve chamar RequestAccessAsync para solicitar permissão ao usuário.

Obter o local atual

Siga estas etapas para realizar uma leitura de posição única.

Solicitar acesso ao local do usuário

Chame Geolocator.RequestAccessAsync antes de acessar dados de localização. Esse método solicita permissão ao usuário na primeira vez em que ele é executado. Você deve chamar o método a partir da thread da interface do usuário enquanto seu aplicativo estiver em primeiro plano.

using Windows.Devices.Geolocation;

var accessStatus = await Geolocator.RequestAccessAsync();

Leia a posição.

Se o usuário conceder permissão, crie um Geolocator e chame GetGeopositionAsync para obter uma correção de posição única.

switch (accessStatus)
{
    case GeolocationAccessStatus.Allowed:
        var geolocator = new Geolocator { DesiredAccuracyInMeters = 50 };
        Geoposition position = await geolocator.GetGeopositionAsync();

        double latitude = position.Coordinate.Point.Position.Latitude;
        double longitude = position.Coordinate.Point.Position.Longitude;

        StatusText.Text = $"Location: {latitude:F4}, {longitude:F4}";
        break;

    case GeolocationAccessStatus.Denied:
        StatusText.Text = "Location access is denied.";
        break;

    case GeolocationAccessStatus.Unspecified:
        StatusText.Text = "An unspecified error occurred.";
        break;
}

Acompanhar a localização do usuário ao longo do tempo

Para receber atualizações de localização periódicas, assine o evento PositionChanged . Defina ReportInterval para controle baseado em tempo ou MovementThreshold para acompanhamento baseado em distância.

if (accessStatus == GeolocationAccessStatus.Allowed)
{
    var geolocator = new Geolocator { ReportInterval = 2000 }; // 2-second interval

    geolocator.PositionChanged += OnPositionChanged;
    geolocator.StatusChanged += OnStatusChanged;
}

Lide com as atualizações de posição.

O evento PositionChanged é disparado em uma thread em segundo plano. Use DispatcherQueue para serializar as atualizações da interface do usuário de volta para a thread principal.

private void OnPositionChanged(Geolocator sender, PositionChangedEventArgs args)
{
    DispatcherQueue.TryEnqueue(() =>
    {
        var position = args.Position.Coordinate.Point.Position;
        StatusText.Text = $"Updated: {position.Latitude:F4}, {position.Longitude:F4}";
    });
}

Gerenciar alterações de status

Monitore StatusChanged para detectar quando o usuário desabilita os serviços de localização ou o sinal gps é perdido.

private void OnStatusChanged(Geolocator sender, StatusChangedEventArgs args)
{
    DispatcherQueue.TryEnqueue(() =>
    {
        switch (args.Status)
        {
            case PositionStatus.Ready:
                StatusText.Text = "Location is available.";
                break;
            case PositionStatus.Disabled:
                StatusText.Text = "Location is disabled. Check Settings.";
                break;
            case PositionStatus.NoData:
                StatusText.Text = "Unable to determine location.";
                break;
            case PositionStatus.NotAvailable:
                StatusText.Text = "Location is not available on this device.";
                break;
        }
    });
}

Direcionar o usuário para as configurações de localização

Se o usuário negar acesso à localização, forneça um link para as configurações de privacidade do Windows para que ele possa alterar sua preferência.

<HyperlinkButton Content="Open location settings"
                 NavigateUri="ms-settings:privacy-location" />

Você também pode abrir a página de configurações por código:

await Windows.System.Launcher.LaunchUriAsync(new Uri("ms-settings:privacy-location"));

Mostrar o local em um mapa

Após obter uma posição, você pode exibi-la em um MapControl do WinUI 3 definindo seu Center e adicionando um MapIcon. Para obter um exemplo de trabalho completo que combina localização geográfica, exibição de mapa e geofencing, consulte os Mapas e a visão geral da localização.

Troubleshooting

Se o aplicativo não puder recuperar um local, verifique o seguinte em Configurações > Privacidade > Local de segurança>:

  • Os serviços de localização estão ativados.
  • Seu aplicativo está listado e definido como Ativado em Permitir que os aplicativos acessem sua localização.
  • O dispositivo tem um receptor GPS funcional ou o posicionamento baseado em rede está disponível.
  • Last updated on