向应用添加 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 组件，并管理组件生命周期事件：

  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 地图，接下来可以探索 Maps 3D SDK for Android 的更高级功能，例如摄像头路径动画、3D 标记或多边形。