向应用添加 3D 地图

请选择平台： Android iOS JavaScript

显示纽约市的 3D 地图

本页将通过一个示例，介绍如何使用 Android 版 Maps 3D SDK 向 Android 应用添加基本 3D 地图。本页中的说明 假定您已完成 设置页面中的步骤，并且具备 以下条件：

  • 已启用 Android 版 Maps 3D SDK 的 Google Cloud 项目
  • 已配置为与 Android 版 Maps 3D SDK 搭配使用的 API 密钥
  • 已设置为与 Android 版 Maps 3D SDK 搭配使用的 Android Studio 项目

如需详细了解这些前提条件，请参阅 设置。

第 1 部分：更新布局文件 (activity_main.xml) 以添加 Map3DView 组件

Map3DView 组件是用于在应用内呈现 3D 地图的视图。以下步骤将添加该组件并配置地图的初始状态，包括相机位置和相关属性：

  1. 打开主 activity 的布局文件，该文件通常位于 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:mode="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 组件，并管理组件生命周期事件。

请注意，Android 版 Maps 3D SDK 一次仅支持 一个处于活动状态的 Map3DView 实例。不支持同时显示多个 Map3DView 实例（例如，在同一布局或不同的可见 Activity 或 Fragment 中），这可能会导致呈现问题，例如辅助视图上出现黑屏。

此外，所有 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. 为 Android 版 Maps 3D SDK 添加必要的导入：

    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 方法。此回调将在地图做好使用准备时触发：

    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.cameraController.flyTo(camera { ... })
}

  7. 通过向 MainActivity 添加以下替换，将生命周期事件从 activity 转发到 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 并运行

现在，您已更新应用的布局和 activity，可以构建并运行应用以查看 3D 地图视图。

  1. 如需将项目与 Gradle 同步，请依次选择 File > Sync Project with Gradle Files 。

  2. 如需在模拟器或实体设备上构建并运行应用，请依次选择 Run > Run 。

如果一切配置正确，您应该会在应用中看到一个 3D 地图，该地图以 activity_main.xml 中指定的坐标附近为中心。

后续步骤

现在，您已向应用添加了基本 3D 地图，接下来可以探索 Android 版 Maps 3D SDK 的更多 高级功能，例如 相机路径动画、 3D 标记或 多边形。

监听地图点击事件

如需监听地图上的点击事件，请使用 GoogleMap3D.setMap3DClickListener。当用户点击地图时，系统会触发此监听器，并提供点击点的位置和地点 ID。

以下示例展示了如何设置地图点击监听器：

googleMap3D.setMap3DClickListener { location, placeId ->
    lifecycleScope.launch(Dispatchers.Main) {
        if (placeId != null) {
            Toast.makeText(this@MainActivity, "Clicked on place with ID: $placeId", Toast.LENGTH_SHORT).show()
        } else {
            Toast.makeText(this@MainActivity, "Clicked on location: $location", Toast.LENGTH_SHORT).show()
        }
    }
}

请注意，点击处理程序不会在主线程（或界面线程）上运行。如果您想对界面进行更改（例如显示 Toast 消息），则必须切换到主线程。对于 Kotlin，您可以使用 lifecycleScope.launch(Dispatchers.Main) 来实现此目的。