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

Статья
07/13/2023

Элемент 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:

Info.plist for iOS 8

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

Android

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

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

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

Получение ключа API google Карты

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

Получив ключ 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 управления отобразит пустую сетку.

Примечание.

com.google.android.geo.API_KEY — рекомендуемое имя метаданных для ключа API. Для обратной совместимости можно использовать имя метаданных, но только разрешает проверку подлинности com.google.android.maps.v2.API_KEY в API Android Карты версии 2.

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

Укажите номер версии служб 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_LOCATIONACCESS_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

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

Required permissions for Android

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

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

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

const int RequestLocationId = 0;

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

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 метода.

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 Карты.

Примечание.

Для использования служб карт, таких как геокодирование, необходимо также задать MapService.ServiceToken для свойства значение ключа проверки подлинности. Это можно сделать с помощью следующей строки кода: Windows.Services.Maps.MapService.ServiceToken = "INSERT_AUTH_TOKEN_HERE";

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

В Обозреватель решений дважды щелкните package.appxmanifest и перейдите на вкладку "Возможности".
В списке возможностей проверка поле "Расположение". Это добавит location возможность устройства в файл манифеста пакета.
```
<Capabilities>
  
  <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.

Внимание

Сбой этого приведет к Map тому, что элемент управления не отображается при запуске сборки выпуска.