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

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

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

關於開發環境

建議您使用最新穩定版的 Android Studio 和 Android Gradle 外掛程式。

設定 Android 裝置

如要執行使用 Maps SDK for Android 的應用程式，請務必將該應用程式部署至採用 Android 6.0 以上版本且包含 Google API 的 Android 裝置或 Android 模擬器。

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

在 Android Studio 中建立 Google 地圖專案

1. 開啟 Android Studio，然後在「Welcome to Android Studio」(歡迎使用 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 20.0.x 版所需的最低版本，也就是 Android API 級別 23 (「Marshmallow」；Android 6.0) 以上版本。如想瞭解 SDK 版本需求條件的最新資訊，請參閱「版本資訊」一文。

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

4. 按一下「完成」。

   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 services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

在應用程式中加入 API 金鑰

本節說明如何儲存 API 金鑰，讓應用程式以安全的方式參照金鑰。API 金鑰不應登錄在版本管控系統中，因此建議將金鑰儲存在專案根目錄的 secrets.properties 檔案內，並將該檔案排除在版本管控之外。如要進一步瞭解 Gradle 屬性檔案，請參閱「Gradle 屬性檔案」。

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

如要安裝 Secrets Gradle Plugin for Android 並儲存 API 金鑰，請按照下列步驟操作：

1. 在 Android Studio 中開啟頂層的 build.gradle.kts 或 build.gradle 檔案， 然後將下列程式碼加進 plugins 區塊。

   Kotlin

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

   Groovy

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

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

   Kotlin

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

   Groovy

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

3. 如果您使用 Android Studio，請使用 Gradle 同步處理專案。
4. 開啟頂層目錄中的 secrets.properties 檔案，並加入下列程式碼，然後將 YOUR_API_KEY 替換成您的 API 金鑰。請務必將 secrets.properties 新增至 .gitignore 檔案 (或以其他方式從版本管控系統中排除)，以免將 API 金鑰登錄至版本管控系統。

   MAPS_API_KEY=YOUR_API_KEY

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

   MAPS_API_KEY=DEFAULT_API_KEY

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

6. 在 AndroidManifest.xml 檔案中，前往 com.google.android.geo.API_KEY 並按照以下方式更新 android:value 屬性：

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

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

7. 在 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 root directory (the same folder as the root 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"
   }

   Groovy

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root 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"
   }

查看程式碼

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

地圖活動檔案

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

地圖活動的主要元素：

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

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

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

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

// Add a marker in Sydney and move the camera
val sydney = LatLng(-34.0, 151.0)
map.addMarker(
    MarkerOptions()
        .position(sydney)
        .title("Marker in Sydney"),
)
map.moveCamera(CameraUpdateFactory.newLatLng(sydney))

      

// Add a marker in Sydney and move the camera
LatLng sydney = new LatLng(-34, 151);
map.addMarker(new MarkerOptions().position(sydney).title("Marker in Sydney"));
map.moveCamera(CameraUpdateFactory.newLatLng(sydney));

      

Gradle 模組檔案

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

dependencies {

    // Maps SDK for Android
    implementation(libs.play.services.maps)
}

dependencies {

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

如果專案使用 Gradle 版本目錄 (gradle/libs.versions.toml)，請在 libs.versions.toml 中定義 play-services-maps 依附元件：

[versions]
play-services-maps = "20.0.0"

[libraries]
play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }

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

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 語言功能。