Compartilhar via

Xamarin.Forms Inicialização e configuração do mapa

  • Artigo

O Map controle usa o controle de mapa nativo em cada plataforma. Isso fornece uma experiência de mapas rápida e familiar para os usuários, mas significa que algumas etapas de configuração são necessárias para aderir aos requisitos de API de cada plataforma.

Inicialização do mapa

O Map controle é fornecido pelo Xamarin.Forms. Pacote NuGet do Maps , que deve ser adicionado a todos os projetos da solução.

Depois de instalar o Xamarin.Forms. Pacote NuGet do Maps , ele deve ser inicializado em cada projeto de plataforma.

No iOS, isso deve ocorrer em AppDelegate.cs invocando o Xamarin.FormsMaps.Init método após o Xamarin.Forms.Forms.Init método:

Xamarin.FormsMaps.Init();

No Android, isso deve ocorrer em MainActivity.cs invocando o Xamarin.FormsMaps.Init método após o Xamarin.Forms.Forms.Init método:

Xamarin.FormsMaps.Init(this, savedInstanceState);

Na Plataforma Universal do Windows (UWP), isso deve ocorrer em MainPage.xaml.cs invocando o Xamarin.FormsMaps.InitMainPage método do construtor:

Xamarin.FormsMaps.Init("INSERT_AUTHENTICATION_TOKEN_HERE");

Para obter informações sobre o token de autenticação necessário na UWP, consulte Plataforma Universal do Windows.

Depois que o pacote NuGet tiver sido adicionado e o método de inicialização chamado dentro de cada aplicativo, Xamarin.Forms.Maps as APIs poderão ser usadas no projeto de código compartilhado.

Configuração da plataforma

É necessária uma configuração adicional no Android e na Plataforma Universal do Windows (UWP) antes que o mapa seja exibido. Além disso, no iOS, Android e UWP, o acesso à localização do usuário requer que as permissões de localização tenham sido concedidas ao aplicativo.

iOS

A exibição e a interação com um mapa no iOS não exigem nenhuma configuração adicional. No entanto, para acessar os serviços de localização, você deve definir as seguintes chaves em Info.plist:

Para suportar o iOS 11 e versões anteriores, você pode incluir as três chaves: NSLocationWhenInUseUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescriptione NSLocationAlwaysUsageDescription.

A representação XML para essas chaves em Info.plist é mostrada abaixo. Você deve atualizar os string valores para refletir como seu aplicativo está usando as informações de local:

<key>NSLocationAlwaysUsageDescription</key>
<string>Can we use your location at all times?</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Can we use your location when your application is being used?</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Can we use your location at all times?</string>

As entradas Info.plist também podem ser adicionadas na visualização Origem durante a edição do arquivo Info.plist :

Info.plist para iOS 8

Um prompt é exibido quando o aplicativo tenta acessar a localização do usuário, solicitando acesso:

Captura de ecrã do pedido de permissão de localização no iOS

Android

O processo de configuração para exibir e interagir com um mapa no Android é:

  1. Obtenha uma chave da API do Google Maps e adicione-a ao manifesto.
  2. Especifique o número da versão dos serviços do Google Play no manifesto.
  3. Especifique o requisito para a biblioteca Apache HTTP Legacy no manifesto.
  4. [opcional] Especifique a permissão WRITE_EXTERNAL_STORAGE no manifesto.
  5. [opcional] Especifique permissões de local no manifesto.
  6. [opcional] Solicite permissões de local de tempo de execução na MainActivity classe.

Para obter um exemplo de um arquivo de manifesto configurado corretamente, consulte AndroidManifest.xml do aplicativo de exemplo.

Obter uma chave da API do Google Maps

Para usar a API do Google Maps no Android, você deve gerar uma chave de API. Para fazer isso, siga as instruções em Como obter uma chave da API do Google Maps.

Depois de obter uma chave de API, ela deve ser adicionada <application> ao elemento do arquivo Properties/AndroidManifest.xml :

<application ...>
    <meta-data android:name="com.google.android.geo.API_KEY" android:value="PASTE-YOUR-API-KEY-HERE" />
</application>

Isso incorpora a chave de API no manifesto. Sem uma chave de API válida, o Map controle exibirá uma grade em branco.

Observação

com.google.android.geo.API_KEY é o nome de metadados recomendado para a chave de API. Para compatibilidade com versões anteriores, o nome dos com.google.android.maps.v2.API_KEY metadados pode ser usado, mas só permite a autenticação para a API v2 do Android Maps.

Para que seu APK acesse o Google Maps, você deve incluir impressões digitais SHA-1 e nomes de pacotes para cada keystore (debug e release) que você usa para assinar seu APK. Por exemplo, se você usar um computador para depuração e outro computador para gerar o APK de versão, deverá incluir a impressão digital do certificado SHA-1 do keystore de depuração do primeiro computador e a impressão digital do certificado SHA-1 do keystore de release do segundo computador. Lembre-se também de editar as credenciais de chave se o Nome do pacote do aplicativo for alterado. Consulte Obter uma chave da API do Google Maps.

Especificar o número da versão dos serviços do Google Play

Acrescentar a seguinte declaração no <application> elemento AndroidManifest.xml:

<meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" />

Isso incorpora a versão dos serviços do Google Play com a qual o aplicativo foi compilado no manifesto.

Especifique o requisito para a biblioteca herdada Apache HTTP

Se seu Xamarin.Forms aplicativo tem como alvo a API 28 ou superior, você deve adicionar a seguinte declaração dentro do <application> elemento de AndroidManifest.xml:

<uses-library android:name="org.apache.http.legacy" android:required="false" />

Isso diz ao aplicativo para usar a biblioteca de cliente Apache Http, que foi removida do bootclasspath no Android 9.

Especifique a permissão WRITE_EXTERNAL_STORAGE

Se o aplicativo tiver como alvo a API 22 ou inferior, talvez seja necessário adicionar a WRITE_EXTERNAL_STORAGE permissão ao manifesto, como filho do <manifest> elemento:

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Isso não será necessário se o aplicativo tiver como alvo a API 23 ou superior.

Especificar permissões de localização

Se o aplicativo precisar acessar o local do usuário, você deverá solicitar permissão adicionando as ACCESS_COARSE_LOCATION permissões ou ACCESS_FINE_LOCATION ao manifesto (ou ambas), como filho do <manifest> elemento:

<manifest xmlns:android="http://schemas.android.com/apk/res/android" android:versionCode="1" android:versionName="1.0" package="com.companyname.myapp">
  ...
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
</manifest>

A ACCESS_COARSE_LOCATION permissão permite que a API use Wi-Fi ou dados móveis, ou ambos, para determinar a localização do dispositivo. As ACCESS_FINE_LOCATION permissões permitem que a API use o Sistema de Posicionamento Global (GPS), Wi-Fi ou dados móveis para determinar uma localização precisa possível.

Como alternativa, essas permissões podem ser habilitadas usando o editor de manifesto para adicionar as seguintes permissões:

  • AccessCoarseLocation
  • AccessFineLocation

Estes são mostrados na captura de tela abaixo:

Permissões necessárias para Android

Solicitar permissões de local de tempo de execução

Se o aplicativo tiver como alvo a API 23 ou posterior e precisar acessar o local do usuário, ele deverá verificar se tem a permissão necessária em tempo de execução e solicitá-la se não a tiver. Isso pode ser feito da seguinte maneira:

  1. MainActivity Na classe, adicione os seguintes campos:

    const int RequestLocationId = 0;

readonly string[] LocationPermissions =
{
    Manifest.Permission.AccessCoarseLocation,
    Manifest.Permission.AccessFineLocation
};

  2. MainActivity Na classe, adicione a seguinte OnStart substituição:

    protected override void OnStart()
{
    base.OnStart();

    if ((int)Build.VERSION.SdkInt >= 23)
    {
        if (CheckSelfPermission(Manifest.Permission.AccessFineLocation) != Permission.Granted)
        {
            RequestPermissions(LocationPermissions, RequestLocationId);
        }
        else
        {
            // Permissions already granted - display a message.
        }
    }
}

    Desde que o aplicativo esteja direcionando a API 23 ou superior, esse código executa uma verificação de permissão de tempo de execução para a AccessFineLocation permissão. Se a permissão não tiver sido concedida, uma solicitação de permissão será feita chamando o RequestPermissions método.

  3. MainActivity Na classe, adicione a seguinte OnRequestPermissionsResult substituição:

    public override void OnRequestPermissionsResult(int requestCode, string[] permissions, [GeneratedEnum] Permission[] grantResults)
{
    if (requestCode == RequestLocationId)
    {
        if ((grantResults.Length == 1) && (grantResults[0] == (int)Permission.Granted))
            // Permissions granted - display a message.
        else
            // Permissions denied - display a message.
    }
    else
    {
        base.OnRequestPermissionsResult(requestCode, permissions, grantResults);
    }
}

    Essa substituição manipula o resultado da solicitação de permissão.

O efeito geral desse código é que, quando o aplicativo solicita a localização do usuário, é exibida a seguinte caixa de diálogo que solicita permissão:

Captura de tela da solicitação de permissão de localização no Android

Plataforma Universal do Windows

Na UWP, seu aplicativo deve ser autenticado para que possa exibir um mapa e consumir serviços de mapa. Para autenticar seu aplicativo, você deve especificar uma chave de autenticação de mapas. Para obter mais informações, consulte Solicitar uma chave de autenticação de mapas. O token de autenticação deve ser especificado na chamada de FormsMaps.Init("AUTHORIZATION_TOKEN") método, para autenticar o aplicativo com o Bing Maps.

Observação

Na UWP, para usar serviços de mapa, como geocodificação, você também deve definir a MapService.ServiceToken propriedade como o valor da chave de autenticação. Isso pode ser feito com a seguinte linha de código: Windows.Services.Maps.MapService.ServiceToken = "INSERT_AUTH_TOKEN_HERE";.

Além disso, se o aplicativo precisar acessar o local do usuário, você deverá habilitar o recurso de localização no manifesto do pacote. Isso pode ser feito da seguinte maneira:

  1. No Gerenciador de Soluções, clique duas vezes em package.appxmanifest e selecione a guia Recursos .

  2. Na lista Recursos, marque a caixa para Local. Isso adiciona o recurso do location dispositivo ao arquivo de manifesto do pacote.

    <Capabilities>
  <!-- DeviceCapability elements must follow Capability elements (if present) -->
  <DeviceCapability Name="location"/>
</Capabilities>

Builds de lançamento

As compilações de versão UWP usam a compilação nativa do .NET para compilar o aplicativo diretamente no código nativo. No entanto, uma consequência disso é que o renderizador para o Map controle na UWP pode ser vinculado fora do executável. Isso pode ser corrigido usando uma sobrecarga específica da UWP do Forms.Init método em App.xaml.cs:

var assembliesToInclude = new [] { typeof(Xamarin.Forms.Maps.UWP.MapRenderer).GetTypeInfo().Assembly };
Xamarin.Forms.Forms.Init(e, assembliesToInclude);

Esse código passa o assembly no qual a Xamarin.Forms.Maps.UWP.MapRenderer classe reside para o Forms.Init método. Isso garante que o assembly não seja vinculado fora do executável pelo processo de compilação nativo do .NET.

Importante

Se isso não for feito, o Map controle não aparecerá ao executar uma compilação de versão.