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

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

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

設定開發環境

  1. 此程序需要 Android Studio。如果您尚未下載安裝,請先完成此步驟。

  2. Google Play 服務 SDK 加入 Android Studio。Maps SDK for Android 屬於 Google Play 服務 SDK 的一部分,您可以透過 SDK Manager 新增這個 SDK。

設定 Android 裝置

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

建立 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 最低版本) 設為測試裝置支援的 Android SDK 版本。

  4. 按一下 [Finish] (完成)

專案建立完成後,Android Studio 會啟動 Gradle 並建立專案。請稍待片刻。建立完成後,Android Studio 會開啟 google_maps_api.xmlMapsActivity 檔案。您的活動名稱可能有所不同,但會是您在設定期間採用的名稱。

如要進一步瞭解如何建立專案,請參閱「建立 Android 專案」一文。

google_maps_api.xml 檔案包含取得 Google Maps API 金鑰,以及將金鑰加入檔案的操作說明。請勿直接將 API 金鑰加入檔案中,這麼做會使 API 金鑰的保存安全性受到影響。請改按照下一節的說明操作。

在 Cloud Console 中設定

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

步驟 1

  1. 在 Google Cloud Console 的專案選取器頁面中,按一下 [建立專案],開始建立新的 Cloud 專案。

    前往專案選取器頁面

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

    Google Cloud 提供 $300 美元的免費試用額度,而 Google 地圖平台每月則提供 $200 美元的抵免額。詳情請參閱帳單帳戶抵免額帳單

步驟 2

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

啟用 Maps SDK for Android

步驟 3

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

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

建立 API 金鑰的方法如下:

  1. 前往「API 和服務」>「憑證」頁面。

    前往憑證頁面

  2. 在「憑證」頁面上,按一下 [建立憑證] > [API 金鑰]
    「建立的 API 金鑰」對話方塊會顯示您新建立的 API 金鑰。
  3. 按一下 [關閉]
    新建立的 API 金鑰便會出現在「憑證」頁面的「API 金鑰」下方。
    (在實際工作環境使用新建金鑰前,記得要先限制 API 金鑰。)

在應用程式加入 API 金鑰

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

您可以使用 Secrets Gradle Plugin Android 版來簡化這項工作。

安裝外掛程式並儲存 API 金鑰的操作步驟如下:

  1. 在 Android Studio 中開啟應用程式層級的 build.gradle 檔案,並將下列程式碼加進 plugins 元素。
    id 'com.google.secrets_gradle_plugin' version '0.5'
        
  2. 儲存檔案,然後使用 Gradle 同步處理專案
  3. 在專案層級目錄中開啟 local.properties 並新增下列程式碼,然後將 YOUR_API_KEY 替換成您的 API 金鑰。
    MAPS_API_KEY=YOUR_API_KEY
        
  4. 儲存檔案,並使用 Gradle 同步處理專案。
  5. 在您的 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

// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.maps.example;

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;

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

// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.maps.example.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
import com.google.maps.example.R

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:17.0.1'
    // ...
}

如要進一步瞭解如何管理地圖依附元件,請參閱版本管理

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 的其他功能。