使用 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 已有所調整。
開啟 Android Studio,然後按一下窗格中的「New Project」 「Welcome to Android Studio」視窗。
在「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
或build.gradle.kts
檔案, 然後將下列程式碼加進buildscript
下方的dependencies
元素。Groovy
buildscript { dependencies { classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1" } }
Kotlin
buildscript { dependencies { classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1") } }
-
開啟模組層級的
build.gradle
檔案,然後將下列程式碼加進plugins
元素。Groovy
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
Kotlin
plugins { id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
- 在模組層級的
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}" />
Note:
com.google.android.geo.API_KEY
is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the namecom.google.android.maps.v2.API_KEY
. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception. -
In Android Studio, open your module-level
build.gradle
orbuild.gradle.kts
file and edit thesecrets
property. If thesecrets
property does not exist, add it.Edit the properties of the plugin to set
propertiesFileName
tosecrets.properties
, setdefaultPropertiesFileName
tolocal.defaults.properties
, and set any other properties.Groovy
secrets { // Optionally specify a different file name containing your secrets. // The plugin defaults to "local.properties" 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.*" }
Kotlin
secrets { // Optionally specify a different file name containing your secrets. // The plugin defaults to "local.properties" 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
檔案包含下列地圖依附元件;該元件是 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 語言功能。
除非另有註明,否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權,程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間:2024-08-16 (世界標準時間)。
[] [] { "last_modified": "上次更新時間:2024-08-16 (世界標準時間)。", "state": "" }