Xamarin.Forms 對應初始化和設定

下載範例。 下載範例

Map控制項會在每個平臺上使用原生地圖控制項。 這可為使用者提供快速且熟悉的地圖體驗,但表示需要一些設定步驟才能遵守每個平臺的 API 需求。

對應初始化

Map控制項是由所提供, Xamarin.Forms 地圖NuGet 封裝,應加入至方案中的每個專案。

安裝 Xamarin.Forms 地圖NuGet 套件之後,必須在每個平臺專案中加以初始化。

在 iOS 上,這應該發生在 AppDelegate 中,方法是在 Xamarin.FormsMaps.Init 方法 之後 叫用方法 Xamarin.Forms.Forms.Init

Xamarin.FormsMaps.Init();

在 Android 上,在方法之後叫用方法,就應該在 >mainactivity 中執行此動作 Xamarin.FormsMaps.Init Xamarin.Forms.Forms.Init

Xamarin.FormsMaps.Init(this, savedInstanceState);

在通用 Windows 平臺 (UWP) 上,這應該會出現在 MainPage 中,方法是從函式叫用 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 和更早版本,您可以包含三個金鑰: NSLocationWhenInUseUsageDescriptionNSLocationAlwaysAndWhenInUseUsageDescriptionNSLocationAlwaysUsageDescription

這些索引鍵在 plist 中的 XML 表示如下所示。 您應更新這些 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 檔案時,也可以在 來源 視圖中加入 plist 專案:

適用于 iOS 8 的 plist。

當應用程式嘗試存取使用者的位置、要求存取權時,就會出現提示:

[![IOS 上位置許可權要求的螢幕擷取畫面] (設定-映射/permission-ios.png "iOS 許可權要求"。](setup-images/permission-ios-large.png#lightbox "iOS 許可權要求")

Android

在 Android 上顯示地圖和與之互動的設定程式如下:

  1. 取得 Google 地圖 API 金鑰,並將它新增至資訊清單。
  2. 在資訊清單中指定 Google Play 服務版本號碼。
  3. 在資訊清單中指定 Apache HTTP 舊版程式庫的需求。
  4. 參數在資訊清單中指定 WRITE_EXTERNAL_STORAGE 許可權。
  5. 參數指定資訊清單中的位置許可權。
  6. 參數要求類別中的執行時間位置許可權 MainActivity

如需正確設定之資訊清單檔的範例,請參閱範例應用程式中的 AndroidManifest.xml

取得 Google 地圖 API 金鑰

若要在 Android 上使用Google 地圖 api ,您必須產生 API 金鑰。 若要這樣做,請依照取得 Google 地圖 API 金鑰中的指示進行。

一旦取得 API 金鑰,就必須將其新增至 <application> 屬性/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 可以使用中繼資料名稱,但只允許對 Android 地圖 API v2 進行驗證。

為了讓您的 APK 存取 Google 地圖,您必須針對每個金鑰儲存區包含 SHA-1 指紋和套件名稱, (debug 和 release) 用來簽署 APK。 例如,如果您使用一部電腦進行 debug,而另一部電腦用來產生 release APK,您應該在第一部電腦的 debug 金鑰儲存區中包含 SHA-1 憑證指紋,並在第二部電腦的版本金鑰儲存區中加入 SHA-1 憑證指紋。 如果應用程式的 套件名稱 有所變更,也請記得編輯金鑰認證。 請參閱取得 Google 地圖 API 金鑰

指定 Google Play 服務版本號碼

在AndroidManifest.xml的元素內新增下列宣告 <application>

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

這會將用來編譯應用程式的 Google Play 服務版本內嵌到資訊清單中。

指定 Apache HTTP 舊版程式庫的需求

如果您的 Xamarin.Forms 應用程式是以 API 28 或更高版本為目標,您必須在AndroidManifest.xml的元素內新增下列宣告 <application>

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

這會告訴應用程式使用已從 Android 9 中移除的 Apache Http 用戶端程式庫 bootclasspath

指定 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 使用 WiFi 或行動資料(或兩者)來判斷裝置的位置。 這些 ACCESS_FINE_LOCATION 許可權可讓 API 使用全球定位系統 (GPS) 、WiFi 或行動資料來判斷盡可能精確的位置。

或者,您可以使用資訊清單編輯器來新增下列許可權,以啟用這些許可權:

  • AccessCoarseLocation
  • AccessFineLocation

這些會顯示在下列螢幕擷取畫面中:

Android 的必要許可權。

要求執行時間位置許可權

如果您的應用程式是以 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);
        }
    }
    

    此覆寫會處理許可權要求的結果。

這段程式碼的整體效果是,當應用程式要求使用者的位置時,會顯示下列對話方塊來要求許可權:

[![Android 上位置許可權要求的螢幕擷取畫面] (設定-images/permission-android.png "Android 許可權要求"。](setup-images/permission-android-large.png#lightbox "Android 許可權要求")

通用 Windows 平台

在 UWP 上,您的應用程式必須經過驗證,才能顯示地圖並使用地圖服務。 若要驗證您的應用程式,您必須指定對應的驗證金鑰。 如需詳細資訊,請參閱 要求對應驗證金鑰。 然後,您應該在方法呼叫中指定驗證權杖 FormsMaps.Init("AUTHORIZATION_TOKEN") ,以 Bing 地圖服務驗證應用程式。

注意

在 UWP 上,若要使用地理編碼之類的地圖服務,您也必須將 MapService.ServiceToken 屬性設定為驗證金鑰值。 您可以使用下列這行程式碼來完成這項作業: Windows.Services.Maps.MapService.ServiceToken = "INSERT_AUTH_TOKEN_HERE";

此外,如果您的應用程式需要存取使用者的位置,您必須啟用套件資訊清單中的位置功能。 執行下列工作即可達成這點:

  1. 在 [方案總管] 中按兩下 package.appxmanifest,然後選取 [功能] 索引標籤。

  2. [功能] 清單中,選取 [位置] 的方塊。 這會將 location 裝置功能新增至套件資訊清單檔案。

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

發行組建

UWP 版本組建使用 .NET 原生編譯,將應用程式直接編譯成機器碼。 不過,這是 Map 因為 UWP 上的控制項轉譯器可能會從可執行檔連結。 您可以使用 App.config 中方法的 UWP 特定多載來修正此 Forms.Init 問題:

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

此程式碼會將類別所在的元件傳遞 Xamarin.Forms.Maps.UWP.MapRendererForms.Init 方法。 這可確保元件不會由 .NET 原生編譯器連結到可執行檔。

重要

若未執行此動作,就會導致控制項在執行 Map 發行組建時不會出現。