Xamarin.Forms Инициализация и конфигурация карты

Элемент Map управления использует собственный элемент управления картой на каждой платформе. Это обеспечивает быстрый и знакомый интерфейс карт для пользователей, но означает, что некоторые действия по настройке необходимы для соблюдения требований API для каждой платформы.

Инициализация карты

Элемент Map управления предоставляется элементом Xamarin.Formsуправления. Сопоставляет пакет NuGet, который следует добавить в каждый проект в решении.

После установки Xamarin.Forms. Сопоставляет пакет NuGet, его необходимо инициализировать в каждом проекте платформы.

В iOS это должно происходить в AppDelegate.cs путем вызова Xamarin.FormsMaps.Init метода после Xamarin.Forms.Forms.Init метода:

Xamarin.FormsMaps.Init();

В Android это должно произойти в MainActivity.cs путем вызова Xamarin.FormsMaps.Init метода после Xamarin.Forms.Forms.Init метода:

Xamarin.FormsMaps.Init(this, savedInstanceState);

В универсальная платформа Windows (UWP) это должно происходить в MainPage.xaml.cs путем вызова Xamarin.FormsMaps.Init метода из конструктораMainPage:

Xamarin.FormsMaps.Init("INSERT_AUTHENTICATION_TOKEN_HERE");

Сведения о маркере проверки подлинности, необходимом для UWP, см. в универсальная платформа Windows.

После добавления пакета NuGet и метода инициализации, вызываемого внутри каждого приложения, Xamarin.Forms.Maps API можно использовать в проекте общего кода.

Конфигурация платформы

Дополнительная конфигурация требуется в Android и универсальная платформа Windows (UWP) перед отображением карты. Кроме того, в iOS, Android и UWP доступ к расположению пользователя требует предоставления приложению разрешений на расположение.

iOS

Отображение и взаимодействие с картой в iOS не требует дополнительной конфигурации. Однако для доступа к службам расположения необходимо задать следующие ключи в Info.plist:

• iOS 11 и более поздних версий
  • NSLocationWhenInUseUsageDescription — для использования служб расположения при использовании приложения
  • NSLocationAlwaysAndWhenInUseUsageDescription — для использования служб расположения в любое время
• iOS 10 и более ранних версий
  • NSLocationWhenInUseUsageDescription — для использования служб расположения при использовании приложения
  • NSLocationAlwaysUsageDescription — для использования служб расположения в любое время

Для поддержки iOS 11 и более ранних версий можно включить все три ключа: NSLocationWhenInUseUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescriptionи NSLocationAlwaysUsageDescription.

Ниже показано xml-представление этих ключей в Info.plist . Необходимо обновить string значения, чтобы отразить, как приложение использует сведения о расположении:

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

Записи Info.plist также можно добавить в режиме источника при редактировании файла Info.plist:

Затем появится запрос, когда приложение пытается получить доступ к расположению пользователя, запрашивая доступ:

Android

Процесс конфигурации для отображения и взаимодействия с картой в Android:

1. Получите ключ API Google Maps и добавьте его в манифест.
2. Укажите номер версии служб Google Play в манифесте.
3. Укажите требование для устаревшей библиотеки Apache HTTP в манифесте.
4. [необязательно] Укажите разрешение WRITE_EXTERNAL_STORAGE в манифесте.
5. [необязательно] Укажите разрешения расположения в манифесте.
6. [необязательно] Запрос разрешений на расположение среды выполнения в MainActivity классе.

Пример правильно настроенного файла манифеста см. в AndroidManifest.xml из примера приложения.

Получение ключа API Google Maps

Чтобы использовать API Google Maps в Android, необходимо создать ключ API. Для этого следуйте инструкциям в разделе "Получение ключа API Google Maps".

Получив ключ API, его необходимо добавить в <application> элемент файла Properties/AndroidManifest.xml :

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

Это внедряет ключ API в манифест. Без допустимого ключа API элемент Map управления отобразит пустую сетку.

Чтобы получить доступ к Google Maps, необходимо включить отпечатки пальцев SHA-1 и имена пакетов для каждого хранилища ключей (отладки и выпуска), которые вы используете для подписи APK. Например, если вы используете один компьютер для отладки и другой для создания APK выпуска, следует поместить отпечаток сертификата SHA-1 из хранилища ключей отладки на первый компьютер, о отпечаток сертификата SHA-1 из хранилища ключей выпуска на второй компьютер. Кроме того, не забудьте изменить учетные данные ключа, если имя пакета приложения изменится. Ознакомьтесь с ключом API Google Maps.

Укажите номер версии служб Google Play

Добавьте следующее объявление в <application> элементе AndroidManifest.xml:

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

Это внедряет версию служб Google Play, с которыми было скомпилировано приложение, в манифест.

Укажите требование для устаревшей библиотеки Apache HTTP

Если приложение Xamarin.Forms предназначено для API 28 или более поздней версии, необходимо добавить следующее объявление в <application> элемент AndroidManifest.xml:

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

Это сообщает приложению использовать клиентская библиотека Apache Http, которая была удалена из bootclasspath Android 9.

Укажите разрешение WRITE_EXTERNAL_STORAGE

Если приложение предназначено для API 22 или ниже, возможно, потребуется добавить WRITE_EXTERNAL_STORAGE разрешение в манифест в качестве дочернего <manifest> элемента:

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

Это не обязательно, если приложение предназначено для API 23 или более поздней версии.

Указание разрешений на расположение

Если приложению необходимо получить доступ к расположению пользователя, необходимо запросить разрешение, добавив ACCESS_COARSE_LOCATION ACCESS_FINE_LOCATION или разрешения в манифест (или оба), в качестве дочернего <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>

Разрешение ACCESS_COARSE_LOCATION позволяет API использовать Wi-Fi или мобильные данные или оба, чтобы определить расположение устройства. Разрешения ACCESS_FINE_LOCATION позволяют API использовать глобальную систему позиционирования (GPS), Wi-Fi или мобильные данные, чтобы определить точное расположение по возможности.

Кроме того, эти разрешения можно включить с помощью редактора манифеста, чтобы добавить следующие разрешения:

• AccessCoarseLocation
• AccessFineLocation

Они показаны на снимке экрана ниже:

Запрос разрешений на расположение среды выполнения

Если приложение предназначено для API 23 или более поздней версии и должно получить доступ к расположению пользователя, он должен проверить наличие требуемого разрешения во время выполнения и запросить его, если у него нет. Это можно обеспечить, выполнив следующие действия.

1. MainActivity В классе добавьте следующие поля:

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

2. MainActivity В классе добавьте следующую OnStart переопределение:

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

   Если приложение предназначено для API 23 или более поздней версии, этот код выполняет проверку разрешений среды выполнения для AccessFineLocation разрешения. Если разрешение не предоставлено, запрос на разрешение выполняется путем вызова RequestPermissions метода.

3. MainActivity В классе добавьте следующую OnRequestPermissionsResult переопределение:

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

   Это переопределение обрабатывает результат запроса разрешений.

Общий эффект этого кода заключается в том, что, когда приложение запрашивает расположение пользователя, отображается следующее диалоговое окно, которое запрашивает разрешение:

Универсальная платформа Windows

В UWP приложение должно пройти проверку подлинности перед отображением карты и использованием служб карт. Для проверки подлинности приложения необходимо указать ключ проверки подлинности карт. Дополнительные сведения см. в разделе "Запрос ключа проверки подлинности карт". Затем маркер проверки подлинности должен быть указан в вызове FormsMaps.Init("AUTHORIZATION_TOKEN") метода для проверки подлинности приложения с помощью карт Bing.

Кроме того, если приложение должно получить доступ к расположению пользователя, необходимо включить возможность расположения в манифесте пакета. Это можно обеспечить, выполнив следующие действия.

1. В Обозреватель решений дважды щелкните package.appxmanifest и перейдите на вкладку "Возможности".

2. В списке возможностей установите флажок " Расположение". Это добавит location возможность устройства в файл манифеста пакета.

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

Сборки выпуска

Сборки выпуска UWP используют собственную компиляцию .NET для компиляции приложения непосредственно в машинный код. Однако следствием этого является то, что отрисовщик элемента управления в Map UWP может быть связан из исполняемого файла. Это можно исправить с помощью перегрузки для конкретного Forms.Init метода uWP в App.xaml.cs:

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

Этот код передает сборку, в которой Xamarin.Forms.Maps.UWP.MapRenderer находится класс, Forms.Init в метод. Это гарантирует, что сборка не связана из исполняемого файла в собственном процессе компиляции .NET.

Дополнительные ссылки

• Xamarin.Forms. Карты закреплений.
• API карт
• Сопоставление пользовательского отрисовщика