在應用程式中加入 3D 地圖

選取平台： Android iOS JavaScript

顯示紐約市的 3D 地圖

本頁面將逐步說明範例，瞭解如何使用 Maps 3D SDK for Android，在 Android 應用程式中加入基本 3D 地圖。本頁的操作說明假設您已完成「設定」頁面中的步驟，並具備下列條件：

  • 已啟用 Maps 3D SDK for Android 的 Google 雲端專案
  • 已設定為與 Maps 3D SDK for Android 搭配使用的 API 金鑰
  • 已設定為使用 Maps 3D SDK for Android 的 Android Studio 專案

如要進一步瞭解這些必要條件，請參閱「設定」。

第 1 部分：更新版面配置檔案 (activity_main.xml) 以新增 Map3DView 元件

Map3DView 元件是負責在應用程式中算繪 3D 地圖的檢視畫面。請按照下列步驟新增元件，並設定地圖的初始狀態，包括攝影機位置和相關屬性：

  1. 開啟主要活動的版面配置檔案，通常位於 app/src/main/res/layout/activity_main.xml。

  2. 在根 ConstraintLayout (或根版面配置元素) 中，新增 map3d XML 命名空間：

    xmlns:map3d="http://schemas.android.com/apk/res-auto"

  3. 刪除顯示「Hello World!」的預設 <TextView>。

  4. 在版面配置中新增 Map3DView 元件。您可以自訂攝影機位置和其他屬性：

    <?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  xmlns:map3d="http://schemas.android.com/apk/res-auto" xmlns:tools="http://schemas.android.com/tools"
  android:id="@+id/main"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  tools:context=".MainActivity">

  <com.google.android.gms.maps3d.Map3DView
    android:id="@+id/map3dView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    map3d:mapMode="hybrid"
    map3d:centerLat="38.544012"
    map3d:centerLng="-107.670428"
    map3d:centerAlt="2427.6"
    map3d:heading="310"
    map3d:tilt="63"
    map3d:range="8266"
    map3d:roll="0"
    map3d:minAltitude="0"
    map3d:maxAltitude="1000000"
    map3d:minHeading="0"
    map3d:maxHeading="360"
    map3d:minTilt="0"
    map3d:maxTilt="90"
    app:layout_constraintBottom_toBottomOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintTop_toTopOf="parent" />
</androidx.constraintlayout.widget.ConstraintLayout>

第 2 部分：更新 MainActivity.kt

下列步驟會初始化在第 1 部分中新增至 activity_main.xml 檔案的 Map3DView 元件，並管理元件生命週期事件。

請注意，Maps 3D SDK for Android 一次只能有一個有效的 Map3DView 執行個體。系統不支援同時顯示多個 Map3DView 執行個體 (例如在同一個版面配置中，或在不同的可見活動或片段中)，否則可能導致算繪問題，例如次要檢視畫面顯示黑畫面。

此外，所有 Map3DView 都會共用並反映相同的地圖狀態 (例如攝影機位置、新增的標記、多邊形等)，即使一個 Map3DView 遭到刪除 (使用 onDestroy) 並建立另一個，除非手動清除，否則該狀態仍會保留。舉例來說，如果您在 Map3DView1 中新增標記，然後刪除該地圖並建立 Map3DView2，則 Map3DView2 中仍會顯示相同的標記。

開發人員責任：

  • 一次一個檢視區塊：確保在任何時刻，檢視區塊階層的有效部分中只有一個 Map3DView。
  • 手動清除：從一個 Map3DView (例如 Map3DView1) 切換至另一個 (例如 Map3DView2) 時，您必須在舊例項 (Map3DView1) 上呼叫 onDestroy()。由於底層地圖狀態是共用的，為確保 Map3DView2 以全新或特定狀態啟動，您必須手動清除 Map3DView1 設定的任何狀態。包括移除標記、疊加層等，以及使用 OnMap3DViewReadyCallback 中取得的 GoogleMap3D 物件重設攝影機位置。

  1. 開啟 MainActivity.kt 檔案，通常位於 app/src/main/java/com/example/yourpackagename/MainActivity.kt。

  2. 新增 Maps 3D SDK for Android 的必要匯入項目：

    import android.util.Log
import com.google.android.gms.maps3d.GoogleMap3D
import com.google.android.gms.maps3d.Map3DView
import com.google.android.gms.maps3d.OnMap3DViewReadyCallback

  3. 修改 MainActivity 類別，實作 OnMap3DViewReadyCallback：

    class MainActivity : AppCompatActivity(), OnMap3DViewReadyCallback {

  4. 為 Map3DView 和 GoogleMap3D 宣告變數：

    private lateinit var map3DView: Map3DView
private var googleMap3D: GoogleMap3D? = null

  5. 在 onCreate 方法中，於 setContentView(...) 和 ViewCompat.setOnApplyWindowInsetsListener 區塊之後，初始化 map3DView、呼叫其 onCreate 生命週期方法，並以非同步方式要求地圖：

    override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    enableEdgeToEdge()
    setContentView(R.layout.activity_main)
    ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.main)) { v, insets ->
        val systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
        v.setPadding(systemBars.left, systemBars.top, systemBars.right, systemBars.bottom)
        insets
    }

    map3DView = findViewById(R.id.map3dView)
    map3DView.onCreate(savedInstanceState)
    map3DView.getMap3DViewAsync(this)
}

  6. 覆寫 onMap3DViewReady 和 onError 方法。地圖準備就緒時，或初始化期間發生錯誤時，就會觸發這些回呼：

    override fun onMap3DViewReady(googleMap3D: GoogleMap3D) {
    // Interact with the googleMap3D object here
    this.googleMap3D = googleMap3D
    // You can now make calls to the googleMap3D object, e.g.,
    // googleMap3D.flyTo(camera { ... })
}

override fun onError(error: Exception) {
    // Handle the error gracefully here (for example, show an error dialog or log the error).
    Log.e("MainActivity", "Error loading 3D map", error)
}

  7. 將下列覆寫項目新增至 MainActivity，即可將生命週期事件從活動轉送至 Map3DView：

    override fun onStart() {
    super.onStart()
    map3DView.onStart()
}

override fun onResume() {
    super.onResume()
    map3DView.onResume()
}

override fun onPause() {
    map3DView.onPause()
    super.onPause()
}

override fun onStop() {
    map3DView.onStop()
    super.onStop()
}

override fun onDestroy() {
    map3DView.onDestroy()
    super.onDestroy()
}

override fun onSaveInstanceState(outState: Bundle) {
    super.onSaveInstanceState(outState)
    map3DView.onSaveInstanceState(outState)
}

override fun onLowMemory() {
    super.onLowMemory()
    map3DView.onLowMemory()
}

第 3 部分：同步處理 Gradle 並執行

更新應用程式的版面配置和活動後，即可建構並執行應用程式，查看 3D 地圖檢視畫面。

  1. 如要將專案與 Gradle 同步處理，請依序選取「File」>「Sync Project with Gradle Files」。

  2. 如要在模擬器或實體裝置上建構及執行應用程式，請選取「Run」>「Run」。

如果所有設定都正確無誤，應用程式中應會顯示 3D 地圖，並以 activity_main.xml 中指定的座標為中心。

地圖載入和錯誤狀態

Maps 3D SDK for Android 會自動顯示內建的視覺回饋，同時管理地圖狀態：

  • 載入疊加層：地圖檢視畫面首次初始化或載入初始可視區域時，系統會顯示置中的進度指標。
  • 錯誤疊加層：如果發生重大錯誤 (例如 API 金鑰無效、網路錯誤，或在不支援的裝置上執行)，系統會顯示樣式錯誤資訊卡。

您可以覆寫 OnMap3DViewReadyCallback 實作中的 onError(error: Exception)，以程式輔助方式擷取這些初始化或載入錯誤。

監聽地圖點擊事件

如要監聽地圖上的點擊事件，請在 GoogleMap3D 上呼叫 setMap3DClickListener。使用者點按地圖時，onMap3DClick 回呼會收到 Map3DClickEvent 物件，提供所點位置的 location 和 placeId，並傳回 Boolean (true 可抑制預設的 Places UI 小工具，false 則會顯示該小工具)。詳情請參閱「與搜尋點互動」。

以下範例說明如何設定地圖點擊事件監聽器：

googleMap3D.setMap3DClickListener { event: Map3DClickEvent ->
    Log.d(
        "MainActivity",
        "Clicked at ${event.location}, placeId: ${event.placeId}"
    )
    false
}

後續步驟

您已在應用程式中加入基本 3D 地圖，現在可以探索 Maps 3D SDK for Android 的進階功能，例如攝影機路徑動畫、3D 標記或多邊形。