新增地圖

選取平台: Android iOS JavaScript

本主題說明如何在將專案設定為使用 Maps SDK for Android 之後,把基本地圖加進 Android 應用程式。新增地圖後,您可以變更地圖類型和地圖項目

總覽

Maps SDK for Android 提供多種應用程式類別,可用於管理地圖的生命週期、功能和資料。這些類別支援以 Android 使用者介面模型為基礎的使用者互動,例如設定地圖的初始狀態,以及在執行階段回應使用者的手勢輸入。

處理地圖的主要介面和類別:

  • GoogleMap:管理基本地圖項目與資料的進入點。應用程式必須先從 SupportMapFragmentMapView 物件擷取 GoogleMap 物件,才能存取該物件。

  • SupportMapFragment:用來管理 GoogleMap 物件生命週期的片段

  • MapView:用來管理 GoogleMap 物件生命週期的檢視畫面

  • OnMapReadyCallback:這個回呼介面會處理 GoogleMap 物件的事件與使用者互動。

GoogleMap 物件會自動執行以下作業:

  • 連線到 Google 地圖服務。
  • 下載地圖圖塊。
  • 顯示在設備屏幕上的瓷磚。
  • 顯示各種控件,如平移和縮放。
  • 藉由移動地圖及放大/縮小,回應平移和縮放手勢。

如要在應用程式中使用 GoogleMap 物件,您必須使用 SupportMapFragmentMapView 物件做為地圖的容器物件,然後從容器中擷取 GoogleMap 物件。由於容器類別衍生自 Android 片段或檢視畫面,因此可為地圖提供 Android 基礎類別的生命週期管理和使用者介面功能。SupportMapFragment 類別是更先進的常見容器,適合 GoogleMap 物件使用。

查看程式碼

以下程式碼是這個主題靜態新增片段時所用的完整 Java 活動。Android 專案是透過 Empty 專案範本建立,再根據專案設定指南進行更新。 執行這個主題中的步驟後,您的程式碼可能會因為專案範本而不同。

  package com.example.mapsetup;

  import androidx.appcompat.app.AppCompatActivity;

  import android.os.Bundle;

  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;

  // Implement OnMapReadyCallback.
  public class MainActivity extends AppCompatActivity implements OnMapReadyCallback {

      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          // Set the layout file as the content view.
          setContentView(R.layout.activity_main);

          // Get a handle to the fragment and register the callback.
          SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                  .findFragmentById(R.id.map);
          mapFragment.getMapAsync(this);

      }

      // Get a handle to the GoogleMap object and display marker.
      @Override
      public void onMapReady(GoogleMap googleMap) {
          googleMap.addMarker(new MarkerOptions()
                  .position(new LatLng(0, 0))
                  .title("Marker"));
      }
  }

新增地圖

本節說明如何使用區段做為地圖容器來新增基本地圖,不過您也可以改用檢視畫面進行。如需範例,請參閱 GitHub 上的 RawMapViewDemoActivity

基本步驟:

  1. 如要取得 SDK 和 API 金鑰並新增必要架構,請按照以下各篇文章的步驟操作:

    1. 在 Google Cloud Console 中完成相關設定

    2. 使用 API 金鑰

    3. 設定 Android Studio 專案

  2. SupportMapFragment 物件新增至處理地圖的活動。 您可以透過靜態或動態方式新增片段。

  3. 導入 OnMapReadyCallback 介面。

  4. 將版面配置檔案設為內容檢視。

  5. 如果您靜態新增片段,請取得片段的處理常式。

  6. 註冊回呼。

  7. 取得 GoogleMap 物件的處理常式。

新增 SupportMapFragment 物件

您可以透過靜態或動態方式將 SupportMapFragment 物件新增至應用程式,最簡單的方法是以靜態方式新增。如果您以動態方式新增片段,則可對片段執行其他動作,例如在執行階段移除和取代片段。

靜態新增片段

在處理地圖的活動版面配置檔案中:

  1. 新增 fragment 元素。
  2. 新增名稱宣告 xmlns:map="http://schemas.android.com/apk/res-auto",這樣即可啟用 maps 自訂 XML 屬性
  3. fragment 元素中,將 android:name 屬性設為 com.google.android.gms.maps.SupportMapFragment
  4. fragment 元素中新增 android:id 屬性,並將該屬性設定為 R.id.map 資源 ID (@+id/map)。

下列範例是包含 fragment 元素的完整版面配置檔案:

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:id="@+id/map"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

動態新增片段

在活動中:

  1. 建立 SupportMapFragment 執行個體。
  2. 修訂交易,將片段新增至活動。詳情請參閱「片段交易」一文。

例如:

Java


SupportMapFragment mapFragment = SupportMapFragment.newInstance();
getSupportFragmentManager()
    .beginTransaction()
    .add(R.id.my_container, mapFragment)
    .commit();

      

Kotlin


val mapFragment = SupportMapFragment.newInstance()
supportFragmentManager
    .beginTransaction()
    .add(R.id.my_container, mapFragment)
    .commit()

      

導入 OnMapReadyCallback 介面

依照下列方式更新活動宣告:

Java


class MainActivity extends AppCompatActivity implements OnMapReadyCallback {
    // ...
}

      

Kotlin


class MainActivity : AppCompatActivity(), OnMapReadyCallback {

    // ...
}

      

設定內容檢視

在活動的 onCreate 方法中呼叫 setContentView 方法,並將版面配置檔案設為內容檢視。

舉例來說,如果版面配置檔案的名稱是 main.xml

Java


@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
}

      

Kotlin


override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)
}

      

取得片段的處理常式,並註冊回呼

  1. 如要處理片段,請呼叫 FragmentManager.findFragmentById 方法,並將其傳遞給版面配置檔案中的片段資源 ID。如果您動態新增片段,請跳過此步驟,因為您已經擷取到處理常式。

  2. 呼叫 getMapAsync 方法來設定片段的回呼。

舉例來說,如果您以靜態方式新增片段:

Java


SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
    .findFragmentById(R.id.map);
mapFragment.getMapAsync(this);

      

Kotlin


val mapFragment = supportFragmentManager
    .findFragmentById(R.id.map) as SupportMapFragment
mapFragment.getMapAsync(this)

      

取得 GoogleMap 物件的處理常式

使用 onMapReady 回呼方法取得 GoogleMap 物件的處理常式。地圖已準備好接收使用者輸入內容時,就會觸發回呼,並提供 GoogleMap 類別的非空值執行個體,方便您用來更新地圖。

在這個範例中,onMapReady 回呼會擷取 GoogleMap 物件的處理常式,然後在地圖上新增標記

Java


@Override
public void onMapReady(GoogleMap googleMap) {
    googleMap.addMarker(new MarkerOptions()
        .position(new LatLng(0, 0))
        .title("Marker"));
}

      

Kotlin


override fun onMapReady(googleMap: GoogleMap) {
    googleMap.addMarker(
        MarkerOptions()
            .position(LatLng(0.0, 0.0))
            .title("Marker")
    )
}

      

地圖的螢幕截圖,且以「空虛島」(Null Island) 為中心標記。

成功建構並執行應用程式後,在該應用程式顯示的地圖中,「空虛島」(經度和緯度皆為零度) 的位置會有標記。

查看完整活動的程式碼:

查看 完整活動


後續步驟

完成以上步驟後,您即可調整地圖設定