Xamarin.Forms Inizializzazione e configurazione mappa

Il Map controllo usa il controllo mappa nativo in ogni piattaforma. Ciò offre un'esperienza di mappe veloce e familiare per gli utenti, ma significa che alcuni passaggi di configurazione sono necessari per rispettare i requisiti api di ogni piattaforma.

Inizializzazione mappa

Il Map controllo viene fornito da Xamarin.Forms.Mappe Pacchetto NuGet, che deve essere aggiunto a ogni progetto nella soluzione.

Dopo l'installazione di Xamarin.Forms.Mappe Il pacchetto NuGet deve essere inizializzato in ogni progetto di piattaforma.

In iOS, questo dovrebbe verificarsi in AppDelegate.cs richiamando il Xamarin.FormsMaps.Init metodo dopo il metodo :Xamarin.Forms.Forms.Init

Xamarin.FormsMaps.Init();

In Android, questo dovrebbe verificarsi in MainActivity.cs richiamando il Xamarin.FormsMaps.Init metodo dopo il Xamarin.Forms.Forms.Init metodo :

Xamarin.FormsMaps.Init(this, savedInstanceState);

Nella piattaforma UWP (Universal Windows Platform) (UWP), questo dovrebbe verificarsi in MainPage.xaml.cs richiamando il Xamarin.FormsMaps.Init metodo dal MainPage costruttore:

Xamarin.FormsMaps.Init("INSERT_AUTHENTICATION_TOKEN_HERE");

Per informazioni sul token di autenticazione richiesto nella piattaforma UWP, vedi piattaforma UWP (Universal Windows Platform).

Dopo aver aggiunto il pacchetto NuGet e aver chiamato il metodo di inizializzazione all'interno di ogni applicazione, Xamarin.Forms.Maps le API possono essere usate nel progetto di codice condiviso.

Configurazione della piattaforma

È necessaria una configurazione aggiuntiva in Android e la piattaforma UWP (Universal Windows Platform) (UWP) prima che la mappa venga visualizzata. Inoltre, in iOS, Android e UWP, per accedere alla posizione dell'utente sono necessarie autorizzazioni per la posizione per l'applicazione.

iOS

La visualizzazione e l'interazione con una mappa in iOS non richiede alcuna configurazione aggiuntiva. Tuttavia, per accedere ai servizi di posizione, è necessario impostare le chiavi seguenti in Info.plist:

• iOS 11 e versioni successive
  • NSLocationWhenInUseUsageDescription : per l'uso dei servizi di posizione quando l'applicazione è in uso
  • NSLocationAlwaysAndWhenInUseUsageDescription – per l'uso di servizi di posizione in qualsiasi momento
• iOS 10 e versioni precedenti
  • NSLocationWhenInUseUsageDescription : per l'uso dei servizi di posizione quando l'applicazione è in uso
  • NSLocationAlwaysUsageDescription – per l'uso di servizi di posizione in qualsiasi momento

Per supportare iOS 11 e versioni precedenti, è possibile includere tutte e tre le chiavi: NSLocationWhenInUseUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescriptione NSLocationAlwaysUsageDescription.

La rappresentazione XML per queste chiavi in Info.plist è illustrata di seguito. È consigliabile aggiornare i string valori in modo da riflettere il modo in cui l'applicazione usa le informazioni sulla posizione:

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

Le voci Info.plist possono essere aggiunte anche nella visualizzazione Origine durante la modifica del file Info.plist :

Viene quindi visualizzata una richiesta quando l'applicazione tenta di accedere alla posizione dell'utente, richiedendo l'accesso:

Android

Il processo di configurazione per la visualizzazione e l'interazione con una mappa in Android è:

1. Ottenere una chiave API di Google Mappe e aggiungerla al manifesto.
2. Specificare il numero di versione di Google Play Services nel manifesto.
3. Specificare il requisito per la libreria legacy HTTP Apache nel manifesto.
4. [facoltativo] Specificare l'autorizzazione WRITE_EXTERNAL_STORAGE nel manifesto.
5. [facoltativo] Specificare le autorizzazioni per il percorso nel manifesto.
6. [facoltativo] Richiedere le autorizzazioni per il percorso di runtime nella MainActivity classe .

Per un esempio di file manifesto configurato correttamente, vedere AndroidManifest.xml dall'applicazione di esempio.

Ottenere una chiave API di Google Mappe

Per usare l'API Google Mappe in Android, è necessario generare una chiave API. A tale scopo, seguire le istruzioni riportate in Ottenere una chiave API di Google Mappe.

Dopo aver ottenuto una chiave API, è necessario aggiungerla all'interno dell'elemento <application> del file Properties/AndroidManifest.xml :

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

In questo modo la chiave API viene incorporata nel manifesto. Senza una chiave API valida, il Map controllo visualizzerà una griglia vuota.

Nota

com.google.android.geo.API_KEY è il nome dei metadati consigliato per la chiave API. Per garantire la compatibilità con le versioni precedenti, è possibile usare il com.google.android.maps.v2.API_KEY nome dei metadati, ma consente solo l'autenticazione all'API android Mappe v2.

Per consentire all'APK di accedere a Google Mappe, è necessario includere le impronte digitali SHA-1 e i nomi dei pacchetti per ogni archivio chiavi (debug e versione) usato per firmare il file APK. Ad esempio, se si usa un computer per il debug e un altro computer per la generazione dell'APK di versione, è necessario includere l'impronta digitale del certificato SHA-1 dall'archivio chiavi di debug del primo computer e l'impronta digitale del certificato SHA-1 dall'archivio chiavi di rilascio del secondo computer. Ricordarsi anche di modificare le credenziali della chiave se il nome del pacchetto dell'app cambia. Vedere Ottenere una chiave API di Google Mappe.

Specificare il numero di versione di Google Play Services

Aggiungere la dichiarazione seguente all'interno dell'elemento <application> di AndroidManifest.xml:

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

In questo modo viene incorporata la versione dei servizi Google Play con cui l'applicazione è stata compilata nel manifesto.

Specificare il requisito per la libreria legacy APACHE HTTP

Se l'applicazione Xamarin.Forms è destinata all'API 28 o successiva, è necessario aggiungere la dichiarazione seguente all'interno dell'elemento <application> di AndroidManifest.xml:

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

Questo indica all'applicazione di usare la libreria client Apache Http, che è stata rimossa da bootclasspath in Android 9.

Specificare l'autorizzazione WRITE_EXTERNAL_STORAGE

Se l'applicazione è destinata all'API 22 o versione precedente, potrebbe essere necessario aggiungere l'autorizzazione WRITE_EXTERNAL_STORAGE al manifesto, come elemento figlio dell'elemento <manifest> :

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

Questa operazione non è necessaria se l'applicazione è destinata all'API 23 o successiva.

Specificare le autorizzazioni per la posizione

Se l'applicazione deve accedere alla posizione dell'utente, è necessario richiedere l'autorizzazione aggiungendo le ACCESS_COARSE_LOCATION autorizzazioni o ACCESS_FINE_LOCATION al manifesto (o entrambe), come elemento figlio dell'elemento <manifest> :

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

L'autorizzazione ACCESS_COARSE_LOCATION consente all'API di usare i dati Wi-Fi o mobili o entrambi, per determinare la posizione del dispositivo. Le ACCESS_FINE_LOCATION autorizzazioni consentono all'API di usare il sistema di posizionamento globale (GPS), WiFi o dati mobili per determinare una posizione precisa possibile.

In alternativa, queste autorizzazioni possono essere abilitate usando l'editor del manifesto per aggiungere le autorizzazioni seguenti:

• AccessCoarseLocation
• AccessFineLocation

Questi sono mostrati nella schermata seguente:

Richiedere autorizzazioni per il percorso di runtime

Se l'applicazione è destinata all'API 23 o successiva e deve accedere alla posizione dell'utente, deve verificare se ha l'autorizzazione necessaria in fase di esecuzione e richiederla se non è disponibile. Per ottenere questo risultato, è possibile procedere come segue:

1. MainActivity Nella classe aggiungere i campi seguenti:

   const int RequestLocationId = 0;
   
   readonly string[] LocationPermissions =
   {
       Manifest.Permission.AccessCoarseLocation,
       Manifest.Permission.AccessFineLocation
   };
   

2. MainActivity Nella classe aggiungere l'override seguenteOnStart:

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

   A condizione che l'applicazione sia destinata all'API 23 o successiva, questo codice esegue un controllo delle autorizzazioni di runtime per l'autorizzazione AccessFineLocation . Se l'autorizzazione non è stata concessa, viene effettuata una richiesta di autorizzazione chiamando il RequestPermissions metodo .

3. MainActivity Nella classe aggiungere l'override seguenteOnRequestPermissionsResult:

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

   Questa override gestisce il risultato della richiesta di autorizzazione.

L'effetto complessivo di questo codice è che quando l'applicazione richiede la posizione dell'utente, viene visualizzata la finestra di dialogo seguente che richiede l'autorizzazione:

Piattaforma UWP (Universal Windows Platform)

Nella piattaforma UWP, l'applicazione deve essere autenticata prima di poter visualizzare una mappa e utilizzare i servizi mappa. Per autenticare l'applicazione, è necessario specificare una chiave di autenticazione per le mappe. Per altre informazioni, vedere Richiedere una chiave di autenticazione per le mappe. Il token di autenticazione deve quindi essere specificato nella chiamata al FormsMaps.Init("AUTHORIZATION_TOKEN") metodo per autenticare l'applicazione con Bing Mappe.

Nota

Nella piattaforma UWP, per usare servizi di mapping come la geocodifica, devi anche impostare la MapService.ServiceToken proprietà sul valore della chiave di autenticazione. Questa operazione può essere eseguita con la riga di codice seguente: Windows.Services.Maps.MapService.ServiceToken = "INSERT_AUTH_TOKEN_HERE";.

Inoltre, se l'applicazione deve accedere alla posizione dell'utente, è necessario abilitare la funzionalità di posizione nel manifesto del pacchetto. Per ottenere questo risultato, è possibile procedere come segue:

1. In Esplora soluzioni fare doppio clic su package.appxmanifest e selezionare la scheda Funzionalità.

2. Nell'elenco Funzionalità selezionare la casella Posizione. In questo modo si aggiunge la location funzionalità del dispositivo al file manifesto del pacchetto.

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

Build di versione

Le build di versione UWP usano la compilazione nativa .NET per compilare l'applicazione direttamente nel codice nativo. Tuttavia, una conseguenza di questo è che il renderer per il Map controllo nella piattaforma UWP può essere collegato all'esterno dell'eseguibile. Questo problema può essere risolto usando un overload specifico della piattaforma UWP del Forms.Init metodo in App.xaml.cs:

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

Questo codice passa l'assembly in cui risiede la Xamarin.Forms.Maps.UWP.MapRenderer classe , al Forms.Init metodo . Ciò garantisce che l'assembly non sia collegato all'eseguibile dal processo di compilazione .NET native.

Importante

In caso contrario, il controllo non viene visualizzato durante l'esecuzione Map di una build di versione.

Collegamenti correlati

• Xamarin.Forms. Mappe pin.
• API Maps
• Renderer personalizzato mappa