本主題說明在專案設定使用 Maps SDK for Android 後，如何把基本地圖加進 Android 應用程式。新增地圖後，您可以變更地圖類型和地圖項目。
總覽
Maps SDK for Android 提供多種應用程式類別，可用於管理地圖的生命週期、功能和資料。這些類別支援以 Android 使用者介面模型為基礎的使用者互動，例如設定地圖的初始狀態，以及在執行階段回應使用者的手勢輸入。
處理地圖的主要介面和類別：
GoogleMap：管理基本地圖項目與資料的進入點。應用程式必須先從SupportMapFragment或MapView物件擷取GoogleMap物件，才能存取該物件。SupportMapFragment：用來管理GoogleMap物件生命週期的片段。OnMapReadyCallback：這個回呼介面會處理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。
基本步驟：
如要取得 SDK 和 API 金鑰並新增必要架構，請按照以下各篇文章的步驟操作：
將
SupportMapFragment物件新增至處理地圖的活動。 您可以透過靜態或動態方式新增片段。導入
OnMapReadyCallback介面。將版面配置檔案設為內容檢視區塊。
如果您靜態新增片段，請取得片段的控制代碼。
註冊回呼。
取得
GoogleMap物件的控制代碼。
新增 SupportMapFragment 物件
您可以透過靜態或動態方式將 SupportMapFragment 物件新增至應用程式，最簡單的方法是以靜態方式新增。如果您以動態方式新增片段，可以對該片段執行其他動作，例如在執行階段移除和取代片段。
靜態新增片段
在處理地圖的活動版面配置檔案中：
- 新增
fragment元素。 - 新增名稱宣告
xmlns:map="http://schemas.android.com/apk/res-auto"，這樣即可啟用maps自訂 XML 屬性。 - 在
fragment元素中，將android:name屬性設為com.google.android.gms.maps.SupportMapFragment。 - 在
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"/>
動態新增片段
在活動中：
- 建立
SupportMapFragment執行個體。 - 修訂交易，將片段新增至活動。詳情請參閱「片段交易」一文。
例如：
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)
}
取得片段的控制代碼，並註冊回呼
如要取得片段的控制代碼，請呼叫
FragmentManager.findFragmentById方法，並向其傳遞版面配置檔案中的片段資源 ID。如果您動態新增片段，請跳過此步驟，因為您已經擷取到控制代碼。呼叫
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")
)
}
成功建構並執行應用程式後，在該應用程式顯示的地圖中，空虛島 (經度和緯度皆為零度) 的位置會有標記。
查看完整活動的程式碼：
後續步驟
完成以上步驟後，您即可調整地圖設定。