使用 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 已有所調整。
開啟 Android Studio,然後在「Welcome to Android Studio」視窗中按一下「New Project」。
在「New Project」(新增專案) 視窗中的「Phone and Tablet」(手機和平板電腦) 類別下方,選取「No Activity」(無活動),然後點選「Next」(下一步)。
填寫「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,這兩種建構設定語言的程式碼片段隨即會顯示在下列程序中。
按一下「Finish」(完成)。
Android Studio 會啟動 Gradle,並開始建構專案。這個過程需要一點時間,請耐心等待。
新增「Google Maps Views Activity」(Google 地圖檢視畫面活動):
- 對著專案中的
app
資料夾按一下滑鼠右鍵。 依序選取「New」(新增) >「Google」>「Google Maps Views Activity」(Google 地圖檢視畫面活動)。
在「New Android Activity」(新增 Android 活動) 對話方塊中,勾選「Launcher Activity」(啟動器活動) 核取方塊。
選取「Finish」(完成)。
詳情請參閱「加入範本中的程式碼」一文。
- 對著專案中的
建構完成後,Android Studio 會開啟
AndroidManifest.xml
和MapsActivity
檔案。活動的名稱可能會改變,但會是您在設定期間採用的名稱。
設定 Google Cloud 專案
請點選以下分頁標籤,完成必要的 Cloud 控制台設定步驟:
步驟 1
控制台
-
在 Google Cloud 控制台的專案選取器頁面中,按一下「建立專案」,開始建立新的 Cloud 專案。
-
確認 Cloud 專案已啟用計費功能。 確認專案已啟用計費功能。
Google Cloud 提供免付費試用期。試用期將於 90 天後或帳戶費用累積達 $300 美元時 (以先發生者為準) 結束。您隨時可以取消試用。Google 地圖平台每月提供 $200 美元的抵免額。詳情請參閱「帳單帳戶抵免額」和「帳單」。
Cloud SDK
gcloud projects create "PROJECT"
進一步瞭解 Google Cloud SDK、Cloud SDK 安裝和下列指令:
步驟 2
如要使用 Google 地圖平台,請啟用打算在專案中使用的 API 或 SDK。
控制台
Cloud SDK
gcloud services enable \ --project "PROJECT" \ "maps-android-backend.googleapis.com"
進一步瞭解 Google Cloud SDK、Cloud SDK 安裝和下列指令:
步驟 3
此步驟僅適用 API 金鑰建立程序。若您在正式環境中使用 API 金鑰,強烈建議您為 API 金鑰設定限制。詳情請參閱特定產品的「使用 API 金鑰」頁面。
API 金鑰是一組專屬 ID,用於驗證與您專案有關的使用權限及帳單處理要求。您的專案至少要有一個相關聯的 API 金鑰。
建立 API 金鑰的方法如下:
控制台
-
前往「Google Maps Platform」(Google 地圖平台) >「Credentials」(憑證) 頁面。
-
在「Credentials」(憑證) 頁面上,點選「Create credentials」(建立憑證) >「API key」(API 金鑰)。
「API key created」(建立的 API 金鑰) 對話方塊會顯示您新建立的 API 金鑰。 -
按一下「Close」(關閉)。
新建立的 API 金鑰會出現在「Credentials」(憑證) 頁面的「API keys」(API 金鑰) 下方。
(別忘了先為 API 金鑰設定限制,然後才在正式環境中使用)
Cloud SDK
gcloud alpha services api-keys create \ --project "PROJECT" \ --display-name "DISPLAY_NAME"
進一步瞭解 Google Cloud SDK、Cloud SDK 安裝和下列指令:
在應用程式中加入 API 金鑰
本節將說明如何儲存 API 金鑰,讓應用程式以安全的方式參照金鑰。API 金鑰不應該登錄在版本管控系統中;我們建議將金鑰儲存在位於專案根目錄的 secrets.properties
檔案內。如要進一步瞭解 secrets.properties
檔案,請參閱這篇文章中關於 Gradle 屬性檔案的說明。
建議您使用 Secrets Gradle Plugin for Android 來簡化這項工作。
如要在 Google 地圖專案中安裝 Secrets Gradle Plugin for Android,請按照下列步驟操作:
-
在 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" } }
-
開啟模組層級的
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' }
- 在模組層級的
build.gradle.kts
或build.gradle
檔案中,確認targetSdk
和compileSdk
已設為 34。 - 儲存檔案,然後使用 Gradle 同步處理專案。
-
開啟頂層目錄中的
secrets.properties
檔案,並加入下列程式碼,然後將YOUR_API_KEY
替換成您的 API 金鑰。secrets.properties
不會登錄在版本管控系統中,因此請將金鑰儲存至該檔案。MAPS_API_KEY=YOUR_API_KEY
- 儲存檔案。
-
在頂層目錄 (與
secrets.properties
檔案相同的資料夾) 中建立local.defaults.properties
檔案,然後加入下列程式碼。MAPS_API_KEY=DEFAULT_API_KEY
如果找不到
secrets.properties
檔案,這個檔案便可做為 API 金鑰的備份位置,以確保建置程序不會失敗。如果您從略過secrets.properties
的版本管控系統複製應用程式,且尚未在本機建立secrets.properties
檔案來提供 API 金鑰,就可能會發生這種情況。 - 儲存檔案。
-
找到
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}" />
注意: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 就會擲回例外狀況。 -
在 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
座標。新增地圖時,第一個要設定的通常是地圖位置和相機設定,例如視角、地圖方向和縮放等級。詳情請參閱相機和檢視畫面指南。
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" />
部署及執行應用程式
成功執行應用程式時,這個應用程式會顯示以澳洲雪梨為中心的地圖,其中城市上方有標記,如下方的螢幕截圖所示。
部署及執行應用程式的方法如下:
- 在 Android Studio 中,按一下「Run」(執行) 選單選項 (或播放按鈕圖示),執行應用程式。
- 系統提示您選擇裝置時,請選擇下列其中一個選項:
- 選取與您電腦連結的 Android 裝置。
- 或者,選取「Launch emulator」(啟動模擬器) 圓形按鈕,然後選擇您設定的虛擬裝置。
- 按一下「OK」(確定)。Android Studio 會啟動 Gradle 來建構應用程式,然後在裝置或模擬器上顯示搜尋結果。啟動應用程式可能需要幾分鐘的時間。
後續步驟
設定地圖:本文件說明如何進行地圖的初始和執行階段設定,例如相機位置、地圖類型、使用者介面元件和手勢。
在 Android 應用程式中加入地圖 (Kotlin):這個程式碼研究室將逐步引導您使用應用程式,並示範 Maps SDK for Android 的其他功能。
使用 Maps Android KTX 程式庫:這個 Kotlin 擴充功能 (KTX) 程式庫可讓您在使用 Maps SDK for Android 時,運用數種 Kotlin 語言功能。