Maps SDK for Android 快速入門導覽課程

使用 Android Studio 適用的 Google 地圖 Views 範本，建立可顯示地圖的 Android 應用程式。如果想設定現有的 Android Studio 專案，請參閱「設定 Android Studio 專案」一文。

本快速入門導覽課程適用於熟悉 Kotlin 或 Java 基本 Android 開發作業的開發人員。

關於開發環境

本快速入門導覽課程在製作時，使用的是 Android Studio Hedgehog 和 Android Gradle 外掛程式 8.2 版。

設定 Android 裝置

如要執行使用 Maps SDK for Android 的應用程式，必須部署至 Android 裝置或 Android 以 Android 5.0 以上版本為基礎，且包含 Google API

• 如要使用 Android 裝置，請按照在硬體裝置上執行應用程式一文的說明操作。
• 如要使用 Android 模擬器，您可以使用 Android Studio 隨附的 Android 虛擬裝置管理工具 (AVD Manager) 建立虛擬裝置並安裝模擬器。

在 Android Studio 建立 Google 地圖專案

在 Android Studio 建立 Google 地圖專案的步驟，在 Flamingo 和較新版的 Android Studio 已有所調整。

1. 開啟 Android Studio，然後按一下窗格中的「New Project」 「Welcome to Android Studio」視窗。

2. 在「New Project」(新增專案) 視窗中的「Phone and Tablet」(手機和平板電腦) 類別下方，選取「No Activity」(無活動)，然後點選「Next」(下一步)。

3. 填寫「New Project」(新增專案) 表單：

   • 將「Language」(語言) 設為 Java 或 Kotlin。Maps SDK for Android 全面支援這兩種語言。如要進一步瞭解 Kotlin，請參閱「使用 Kotlin 開發 Android 應用程式」一文。

   • 將「Minimum SDK」(SDK 最低版本) 設為與測試裝置相容的 SDK 版本。您所選的版本必須高於 Maps SDK for Android 19.0.x 版所需的最低版本，也就是 Android API 級別 21 (「Lollipop」；Android 5.0) 以上版本。如想瞭解 SDK 版本需求條件的最新資訊，請參閱「版本資訊」一文。

   • 將「Build configuration language」(建構設定語言) 設為 Kotlin DSL 或 Groovy DSL，這兩種建構設定語言的程式碼片段隨即會顯示在下列程序中。

4. 按一下「Finish」(完成)。

   Android Studio 會啟動 Gradle，並開始建構專案。這個過程需要一點時間，請耐心等待。

5. 新增「Google Maps Views Activity」(Google 地圖檢視畫面活動)：

   1. 對著專案中的 app 資料夾按一下滑鼠右鍵。

   2. 依序選取「New」(新增) >「Google」>「Google Maps Views Activity」(Google 地圖檢視畫面活動)。

      

   3. 在「New Android Activity」(新增 Android 活動) 對話方塊中，勾選「Launcher Activity」(啟動器活動) 核取方塊。

   4. 選取「Finish」(完成)。

      詳情請參閱「加入範本中的程式碼」一文。

6. 建構完成後，Android Studio 會開啟 AndroidManifest.xml 和 MapsActivity 檔案。活動的名稱可能會改變，但會是您在設定期間採用的名稱。

設定 Google Cloud 專案

請點選以下分頁標籤，完成必要的 Cloud 控制台設定步驟：

gcloud projects create "PROJECT"

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

gcloud alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

在應用程式中加入 API 金鑰

本節將說明如何儲存 API 金鑰，讓應用程式以安全的方式參照金鑰。API 金鑰不應該登錄在版本管控系統中；我們建議將金鑰儲存在位於專案根目錄的 secrets.properties 檔案內。如要進一步瞭解 secrets.properties 檔案，請參閱這篇文章中關於 Gradle 屬性檔案的說明。

建議您使用 Secrets Gradle Plugin for Android 來簡化這項工作。

如要在 Google 地圖專案中安裝 Secrets Gradle Plugin for Android，請按照下列步驟操作：

1. 在 Android Studio 中開啟頂層的 build.gradle.kts 或 build.gradle 檔案， 然後將下列程式碼加進 buildscript 下方的 dependencies 元素。

   Kotlin

   buildscript {
       dependencies {
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }

   Groovy

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

2. 開啟模組層級的 build.gradle.kts 或 build.gradle 檔案，然後將下列程式碼加進 plugins 元素。

   Kotlin

   plugins {
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

   Groovy

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

3. 在模組層級的 build.gradle.kts 或 build.gradle 檔案中，確認 targetSdk 和 compileSdk 已設為 34。
4. 儲存檔案，然後使用 Gradle 同步處理專案。
5. 開啟頂層目錄中的 secrets.properties 檔案，並加入下列程式碼，然後將 YOUR_API_KEY 替換成您的 API 金鑰。secrets.properties 不會登錄在版本管控系統中，因此請將金鑰儲存至該檔案。

   MAPS_API_KEY=YOUR_API_KEY

6. 儲存檔案。

7. 在頂層目錄 (與 secrets.properties 檔案相同的資料夾) 中建立 local.defaults.properties 檔案，然後加入下列程式碼。

   MAPS_API_KEY=DEFAULT_API_KEY

   如果找不到 secrets.properties 檔案，這個檔案便可做為 API 金鑰的備份位置，以確保建置程序不會失敗。如果您從略過 secrets.properties 的版本管控系統複製應用程式，且尚未在本機建立 secrets.properties 檔案來提供 API 金鑰，就可能會發生這種情況。

8. 儲存檔案。
9. 找到 AndroidManifest.xml 檔案中的 com.google.android.geo.API_KEY，並更新 android:value attribute。如果沒有 <meta-data> 標記，請以 <application> 標記子項的形式建立該標記。

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />

   注意： 建議的中繼資料名稱為 com.google.android.geo.API_KEY API 金鑰具備此名稱的金鑰可用於驗證多個 Android 平台上的 Google 地圖式 API，包括 Maps SDK for Android。為了兼顧回溯相容性，API 也會 支援名稱 com.google.android.maps.v2.API_KEY。這個舊版 名稱僅允許對 Android Maps API 第 2 版進行驗證。應用程式只能指定這兩種 API 金鑰中繼資料名稱的其中一個；如果同時指定兩者 就會擲回例外狀況。

10. 在 Android Studio 中開啟模組層級的 build.gradle.kts 或 build.gradle 檔案，然後編輯 secrets 屬性。如果 secrets 屬性不存在，請新增該屬性。

    編輯外掛程式的屬性，將 propertiesFileName 設為 secrets.properties、將 defaultPropertiesFileName 設為 local.defaults.properties，並設定任何其他屬性。

    Kotlin

    secrets {
        // To add your Maps API key to this project:
        // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
        // 2. Add this line, where YOUR_API_KEY is your API key:
        //        MAPS_API_KEY=YOUR_API_KEY
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

    Groovy

    secrets {
        // To add your Maps API key to this project:
        // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
        // 2. Add this line, where YOUR_API_KEY is your API key:
        //        MAPS_API_KEY=YOUR_API_KEY
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

查看程式碼

檢查範本提供的程式碼。請特別留意 Android Studio 專案中的下列檔案。

地圖活動檔案

地圖活動檔案是應用程式的主要「活動」，其中含有管理和顯示地圖的程式碼。根據預設，定義活動的檔案名稱為 MapsActivity.java；如果您將 Kotlin 設為應用程式的語言，則為 MapsActivity.kt。

地圖活動的主要元素：

• SupportMapFragment 物件會管理地圖的生命週期，且是應用程式使用者介面的父項元素。

• GoogleMap 物件提供地圖資料和檢視畫面的存取權。這是 Maps SDK for Android 的主要類別。地圖物件指南將詳細說明 SupportMapFragment 和 GoogleMap 物件。

• moveCamera 函式，會把地圖中心設在澳洲雪梨的 LatLng 座標。新增地圖時，第一個要設定的通常是地圖位置和相機設定，例如視角、地圖方向和縮放等級。詳情請參閱相機和檢視畫面指南。

• addMarker 函式會為雪梨的座標新增標記。詳情請參閱標記指南。

Gradle 模組檔案

模組 build.gradle.kts 檔案包含下列地圖依附元件；該元件是 Maps SDK for Android 的必要資料。

dependencies {

    // Maps SDK for Android
    implementation("com.google.android.gms:play-services-maps:19.0.0")
}

如要進一步瞭解如何管理地圖依附元件，請參閱「版本管理」一文。

XML 版面配置檔案

activity_maps.xml 檔案是定義應用程式使用者介面結構的 XML 版面配置檔案。這個檔案位於 res/layout 目錄中。activity_maps.xml 檔案會宣告內含下列元素的片段：

• tools:context 會將片段的預設活動設為 MapsActivity，並在地圖活動檔案中定義。
• android:name 會將片段的類別名稱設為 SupportMapFragment，也就是地圖活動檔案中所使用的片段類型。

XML 版面配置檔案內含以下程式碼：

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/map"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MapsActivity" />

部署及執行應用程式

成功執行應用程式時，這個應用程式會顯示以澳洲雪梨為中心的地圖，其中城市上方有標記，如下方的螢幕截圖所示。

部署及執行應用程式的方法如下：

1. 在 Android Studio 中，按一下「Run」(執行) 選單選項 (或播放按鈕圖示)，執行應用程式。
2. 系統提示您選擇裝置時，請選擇下列其中一個選項：
   • 選取與您電腦連結的 Android 裝置。
   • 或者，選取「Launch emulator」(啟動模擬器) 圓形按鈕，然後選擇您設定的虛擬裝置。
3. 按一下「OK」(確定)。Android Studio 會啟動 Gradle 來建構應用程式，然後在裝置或模擬器上顯示搜尋結果。啟動應用程式可能需要幾分鐘的時間。

後續步驟

• 設定地圖：本文件說明如何進行地圖的初始和執行階段設定，例如相機位置、地圖類型、使用者介面元件和手勢。

• 在 Android 應用程式中加入地圖 (Kotlin)：這個程式碼研究室將逐步引導您使用應用程式，並示範 Maps SDK for Android 的其他功能。

• 使用 Maps Android KTX 程式庫：這個 Kotlin 擴充功能 (KTX) 程式庫可讓您在使用 Maps SDK for Android 時，運用數種 Kotlin 語言功能。