新增地圖

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

總覽

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

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

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

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

• MapView：用來管理 GoogleMap 物件生命週期的檢視區塊。

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

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

• 連線到 Google 地圖服務。
• 下載地圖圖塊。
• 在裝置螢幕上顯示圖塊。
• 顯示各種控制項，如平移和縮放。
• 移動地圖及放大/縮小，回應平移和縮放手勢。

如要在應用程式中使用 GoogleMap 物件，您必須使用 SupportMapFragment 或 MapView 物件做為地圖的容器物件，然後從容器中擷取 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 控制台中完成相關設定

   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. 修訂交易，將片段新增至活動。詳情請參閱「片段交易」一文。

例如：

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

      

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

      

導入 OnMapReadyCallback 介面

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

class MainActivity : AppCompatActivity(), OnMapReadyCallback {

    // ...
}

      

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

      

設定內容檢視區塊

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

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

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

      

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

      

取得片段的控制代碼，並註冊回呼

1. 如要取得片段的控制代碼，請呼叫 FragmentManager.findFragmentById 方法，並傳遞版面配置檔案中的片段資源 ID。如果您動態新增片段，請跳過此步驟，因為已擷取到控制代碼。

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

舉例來說，如果您靜態新增片段：

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

      

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

      

取得 GoogleMap 物件的控制代碼

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

在這個範例中，onMapReady 回呼會擷取 GoogleMap 物件的控制代碼，然後在地圖上新增標記：

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

      

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

      

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

查看完整活動的程式碼：

arrow_upward查看 完整活動

後續步驟

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