新增地圖

本主題說明如何在將專案設定為使用 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. 事前準備:請務必完成專案設定指南中的步驟,將專案設為能夠使用 Maps SDK for Android。

  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) 為中心標記。

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

查看完整活動的程式碼:

查看 完整活動


後續步驟

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