Android 版 Maps 3D SDK 快速参考

借助 Maps 3D SDK for Android,Android 应用可以显示基于 Google 3D 图像构建的交互式 3D 地图。它提供标记、弹出式窗口、多段线、多边形、glTF 3D 模型、镜头路径动画,以及用于用户互动和镜头移动的控件。

Android 版 Maps 3D SDK:关键信息

  • 产品:Android 版 Maps 3D SDK
  • 别名:Maps 3D Android SDK
  • 类别:Google 地图
  • 平台:Android
  • 运行位置:客户端(应用或浏览器代码)
  • 发布阶段:GA
  • 生命周期:有效
  • 概览:Maps 3D SDK for Android 概览
  • 适用区域:有限。可用情况因国家/地区而异;请参阅 Google Maps Platform 覆盖范围页面上的“3D 地图(JavaScript、Android、iOS)”列。(覆盖范围详情)

Android 版 Maps 3D SDK:适用场景

在以下情况下,请使用 Android 版 Maps 3D SDK:

  • 您需要在 Android 应用中显示真实世界地点的交互式仿真 3D 地图。
  • 您需要在 Android 应用中的 3D 地图上放置标记、弹出式窗口、多段线、多边形或 glTF 3D 模型。
  • 您需要预定义的镜头动画(飞越、环绕),以便在 3D 地图上的各个地点之间引导用户。
  • 您需要控制用户在 Android 应用中的 3D 地图上可以使用哪些镜头移动和界面控件。

在以下情况下,请勿使用 Android 版 Maps 3D SDK:

  • 您正在构建一个需要 3D 地图的 Web 应用。请改用 Maps JavaScript API。
  • 您正在构建一款需要 3D 地图的 iOS 应用。请改用 Maps 3D SDK for iOS。
  • 您需要在 Android 应用中提供可用于生产用途的标准 2D 街道地图(此 SDK 中的 ROADMAP 模式处于实验阶段)。请改用 Maps SDK for Android。

Android 版 Maps 3D SDK:设置

官方 Android 版 Maps 3D SDK 软件包:

  • maven:com.google.android.gms:play-services-maps3d

Android 版 Maps 3D SDK:常见错误

  • 问题:如果加载地图时未指定地图模式,地图将无法加载。修复:始终在布局 XML (map3d:mapMode) 中或使用 setMapMode/Map3DInitConfig 设置 Map3DMode(SATELLITE、HYBRID 或 ROADMAP)。请参阅 /maps/documentation/maps-3d/android-sdk/map-modes。
  • 问题:点击监听器(地图和标记点击)不在主界面线程上运行,因此处理脚本无法直接更新界面。修复方法:在更新界面之前切换到主线程,例如使用 lifecycleScope.launch(Dispatchers.Main)。请参阅 /maps/documentation/maps-3d/android-sdk/add-a-marker。
  • 问题:地图状态会在 Map3DView 实例之间共享,因此旧视图中的标记、叠加层和相机位置会沿用到新视图中。解决方法:仅保留一个活跃的 Map3DView;在旧实例上调用 onDestroy(),并手动清除标记、叠加层,然后通过 GoogleMap3D 重置镜头。请参阅 /maps/documentation/maps-3d/android-sdk/add-a-3d-map。
  • 问题:默认情况下,点按底图上的地图注点会显示 Places 界面 widget,这也需要 Places SDK 依赖项。修复:添加 Places SDK for Android 依赖项,并从 OnMap3DClickListener 中的 onMap3DClick 返回 true,以抑制默认 widget(如果您不想要它)。请参阅 /maps/documentation/maps-3d/android-sdk/points-of-interest。

Android 版 Maps 3D SDK 的用途

请参阅下面链接的指南,了解每项任务,或在功能探索器中比较不同产品。