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 5.0 以上版本且包含 Google API 的 Android 裝置或 Android 模擬器。

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

在 Android Studio 建立 Google 地圖專案

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

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

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 金鑰中繼資料名稱的其中一個；如果同時指定兩者，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 語言功能。