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

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

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

設定開發環境

  1. 必須使用 Android Studio Arctic Fox 或更新版本。如果您尚未下載安裝,請先完成此步驟。
  2. 確認您在 Android Studio 中使用的是 Android Gradle 外掛程式 7.0 以上版本

設定 Android 裝置

如要執行使用 Maps SDK for Android 的應用程式,您必須將其部署至採用 Android 4.0 以上版本且包含 Google API 的 Android 裝置或 Android Emulator。

在 Android Studio 中建立 Google 地圖專案

  1. 開啟 Android Studio,然後在「Welcome to Android Studio」(歡迎使用 Android Studio) 視窗中按一下「Create New Project」(建立新專案)

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

  3. 填寫 Google 地圖活動表單:

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

    • 將「Minimum SDK」設為與測試裝置相容的 SDK 版本。您所選的版本必須高於 Maps SDK for Android 18.0.x 版所需的最低版本,目前為 Android API 級別 19 (Android 4.4 KitKat) 以上版本。如需 SDK 版本需求條件的最新資訊,請參閱「版本資訊」一文。

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

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

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

  6. 您可依據 AndroidManifest.xml 檔案內的操作說明,取得 Google Maps API 金鑰並加進 local.properties 檔案。請勿直接將 API 金鑰加入 AndroidManifest.xml 檔案中,這麼做會使 API 金鑰的保存安全性受到影響。請改為按照下一節的操作說明,建立 Cloud 專案並設定 API 金鑰。

設定 Google Cloud 專案

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

步驟 1

控制台

  1. 在 Google Cloud 控制台的專案選取器頁面中,按一下「建立專案」,開始建立新的 Cloud 專案。

    前往專案選取器頁面

  2. 確認 Cloud 專案已啟用計費功能。 確認專案已啟用計費功能

    Google Cloud 提供免付費試用期。試用期將於 90 天後或帳戶費用累積達 $300 美元時 (以先發生者為準) 結束。您隨時可以取消試用。Google 地圖平台每月提供 $200 美元的抵免額。詳情請參閱「帳單帳戶抵免額」和「帳單」。

Cloud SDK

gcloud projects create "PROJECT"

進一步瞭解 Google Cloud SDKCloud SDK 安裝和下列指令:

步驟 2

如要使用 Google 地圖平台,您必須啟用打算在專案中使用的 API 或 SDK。

控制台

啟用 Maps SDK for Android

Cloud SDK

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

進一步瞭解 Google Cloud SDKCloud SDK 安裝和下列指令:

步驟 3

此步驟僅適用 API 金鑰建立程序。若您在實際工作環境中使用 API 金鑰,強烈建議您限制 API 金鑰。詳情請參閱特定產品的「使用 API 金鑰」頁面。

API 金鑰是一組專屬 ID,用於驗證與您專案有關的使用權限及帳單處理要求。您的專案至少要有一個相關聯的 API 金鑰。

建立 API 金鑰的方法如下:

控制台

  1. 前往「Google 地圖平台」>「憑證」頁面。

    前往「憑證」頁面

  2. 在「憑證」頁面上,點選「建立憑證」>「API 金鑰」
    「建立的 API 金鑰」對話方塊會顯示您新建立的 API 金鑰。
  3. 按一下「關閉」。
    新建立的 API 金鑰會出現在「憑證」頁面的「API 金鑰」下方。
    (別忘了先為 API 金鑰設定限制,然後才在實際工作環境中使用。)

Cloud SDK

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

進一步瞭解 Google Cloud SDKCloud SDK 安裝和下列指令:

在應用程式加入 API 金鑰

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

建議您使用 Secrets Gradle Plugin for Android 來簡化這項工作。如要安裝這個外掛程式並儲存 API 金鑰,請按照下列步驟操作:

  1. 在 Android Studio 中開啟專案層級的 build.gradle 檔案,然後將下列程式碼加進 buildscript 下方的 dependencies 元素。
    plugins {
        // ...
        id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
    }
  2. 接著,開啟模組層級的 build.gradle 檔案,然後將下列程式碼加進 plugins 元素。
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
        
  3. 儲存檔案,然後使用 Gradle 同步處理專案
  4. 在專案層級目錄中開啟 local.properties,接著新增下列程式碼,然後將 YOUR_API_KEY 替換成您的 API 金鑰。
    MAPS_API_KEY=YOUR_API_KEY
        
  5. 儲存檔案。
  6. 在您的 AndroidManifest.xml 檔案中,前往 com.google.android.geo.API_KEY 並按照以下方式更新 android:value attribute
    <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 專案中的下列檔案。

地圖活動檔案

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

地圖活動的主要元素:

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

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

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

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

地圖活動檔案含有下列程式碼:

Java


import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.OnMapReadyCallback;
import com.google.android.gms.maps.SupportMapFragment;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.MarkerOptions;

public class MapsActivity extends AppCompatActivity implements OnMapReadyCallback {

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_maps);
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     *
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    @Override
    public void onMapReady(GoogleMap googleMap) {
        mMap = googleMap;

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

      

Kotlin


import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle

import com.google.android.gms.maps.CameraUpdateFactory
import com.google.android.gms.maps.GoogleMap
import com.google.android.gms.maps.OnMapReadyCallback
import com.google.android.gms.maps.SupportMapFragment
import com.google.android.gms.maps.model.LatLng
import com.google.android.gms.maps.model.MarkerOptions

internal class MapsActivity : AppCompatActivity(), OnMapReadyCallback {

    private lateinit var mMap: GoogleMap

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_maps)
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        val mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync(this)
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    override fun onMapReady(googleMap: GoogleMap) {
        mMap = googleMap

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

      

Gradle 模組檔案

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

dependencies {
    implementation 'com.google.android.gms:play-services-maps:18.1.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:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:id="@+id/map"
    tools:context=".MapsActivity"
    android:name="com.google.android.gms.maps.SupportMapFragment" />

部署及執行應用程式

地圖的螢幕截圖,且以「澳洲雪梨」為中心標記。

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

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

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