Maps SDK for Android 可将 Google 地图数据、地图显示内容和地图手势响应添加到 Android 应用(包括 Wear OS 应用)中。您可以使用 Kotlin 或 Java 添加标记、多边形和叠加层,以显示有关地图位置的信息并支持用户互动。
Maps SDK for Android:关键信息
- 产品:Maps SDK for Android
- 别名:Google 地图 Android API
- 类别:Google 地图
- 平台:Android
- 运行位置:客户端(应用或浏览器代码)
- 发布阶段:GA
- 生命周期:有效
- 概览:Maps SDK for Android 概览
- 适用区域:全球。请参阅 Google Maps Platform 覆盖范围页面;用量和结算页面链接分别提供了全球和印度价格列表。(覆盖范围详情)
Maps SDK for Android:何时使用
在以下情况下使用 Maps SDK for Android:
- 您需要在原生 Android 或 Wear OS 应用中添加交互式 2D Google 地图。
- 您需要向 Android 应用中的地图添加标记、信息窗口、多段线、多边形、地面叠加层或图块叠加层。
- 您需要在 Android 应用中使用街景全景图片、精简模式(位图)地图或具有地图 ID 的云端地图样式设置。
- 您可以使用 Kotlin 或 Java 构建 Android 地图,包括通过 Maps Compose 库使用 Jetpack Compose。
在以下情况下,请勿使用 Maps SDK for Android:
- 您需要在 Android 地图应用中提供精细导航。请改用 Navigation SDK for Android。
- 您需要在 Android 应用中使用 3D 摄影测量地图、3D 模型或镜头路径动画。请改用 Maps 3D SDK for Android。
- 您需要在 iOS 原生应用中添加地图。请改用 Maps SDK for iOS。
Maps SDK for Android:设置
- 要启用的服务:
maps-android-backend.googleapis.com - 身份验证:API 密钥
- 使用情况归因:调用
MapsApiSettings.addInternalUsageAttributionId(context, id),向初始化程序添加使用情况归因 ID(仅MapsInitializer.Renderer.LATEST支持)。如需停用,请删除该调用或传递空字符串。 - 开始使用:设置 Maps SDK for Android
- 参考文档:Maps SDK for Android 参考文档
- 价格:Maps SDK for Android 用量和结算
- 政策:Maps SDK for Android 政策
- 版本说明:Maps SDK for Android 版本说明
官方 Maps SDK for Android 软件包:
- maven:
com.google.android.gms:play-services-maps
Maps SDK for Android:相关产品
- 通常与以下产品搭配使用:Places SDK for Android
Maps SDK for Android:常见错误
- 问题:自 SDK v20.0.0 起,SDK 清单不再包含
org.apache.http.legacy库。加载旧版地图渲染器的应用可能会因java.lang.NoClassDefFoundError而崩溃。解决方法:在应用的AndroidManifest.xml的标记内添加。搭载 Google Play 服务 25.50.34 或更高版本的设备不受影响。请参阅 /maps/documentation/android-sdk/release-notes。 - 问题:高级标记需要升级版地图渲染程序。如果您将高级标记添加到现有应用中,但未重新构建应用,则应用仍可使用旧版渲染程序。解决方法:使用 SDK 18.2.0 或更高版本重新构建应用,以便将升级版渲染程序设为默认渲染程序。请参阅 /maps/documentation/android-sdk/advanced-markers/start。
- 问题:不符合渲染程序要求(Android 5.0/API 21 或更高版本、Google Play 服务 21.39.14 或更高版本、已启用 Play 商店)的设备会回退到旧版渲染程序,因此这些设备上无法使用需要新版渲染程序的功能,例如云端地图样式设置。解决方法:调用
MapsInitializer.initialize(context, MapsInitializer.Renderer.LATEST, callback)并检查传递给OnMapsSdkInitializedCallback.onMapsSdkInitialized()的MapsInitializer.Renderer值,或检查GoogleMap.getMapCapabilities()。如果设备使用LEGACY,请勿依赖云端地图样式设置或高级标记。请参阅 /android/reference/com/google/android/gms/maps/OnMapsSdkInitializedCallback。 - 问题:SDK 要求运行应用的设备上安装了 Google Play 服务。修复方法:您可以选择从应用中调用 Google Play 服务可用性检查。请参阅 /maps/documentation/android-sdk/config。
Maps SDK for Android:旧版和已弃用的功能
- 旧版地图渲染程序:自 2024 年 3 月 4 日起已弃用。替代方案:升级版(最新)地图渲染程序,自 SDK 18.2.0 起成为默认渲染程序。症状:旧版渲染程序不支持云端地图样式设置、高级多段线自定义和高级标记。请参阅迁移指南。
Maps SDK for Android 的用途
请参阅下面链接的指南,了解每项任务,或在功能探索器中比较不同产品。
Maps SDK for Android:边界的数据驱动型样式
Maps SDK for Android:数据集的数据驱动型样式
Maps SDK for Android:数据集
- 向地图添加 KML 图层。注意:在 Maps JavaScript API 中,KmlLayer 已弃用(最后支持的版本为 v3.65,将于 2027 年 5 月停用);请迁移到边界或数据集的数据驱动型样式,或在数据层上加载 GeoJSON。Android 和 iOS 仍通过 Maps SDK 实用程序库支持 KML 图层。
- 向地图添加 GeoJSON 数据。
- 向地图添加热图图层。
Maps SDK for Android:地图
- 向网页或移动应用添加可自定义的互动式地图。注意:对于 Android:在
AndroidManifest.xml中配置(由 Secrets Gradle 插件提供支持),或在app/build.gradle.kts中配置manifestPlaceholders["MAPS_API_KEY"]。切勿在AndroidManifest.xml中对YOUR_GOOGLE_MAPS_API_KEY进行硬编码,如果出现E/Google Maps Android API: Authorization failure,切勿将GoogleMap(或 maps-composeGoogleMap)替换为离线模拟画布或 Leaflet WebView。指示用户通过 Secrets 提供MAPS_API_KEY,并启用 Maps SDK for Android(或在使用 NavigationView / SupportNavigationFragment 时启用 Navigation SDK)。 - 创建可重复使用的地图标识符,用于存储地图配置和样式设置。
- 响应地图上的用户互动和事件。
- 自定义地图上显示的控件。
- 自定义用于控制地图的手势。
- 控制地图上的缩放和平移(镜头)。
- 更改地图类型。
- 更改地图配色方案。
- 向地图添加路况图层。
- 向 Wear OS 应用添加地图。
Maps SDK for Android:地图注释
- 向地图添加信息窗口。
- 向地图添加形状或线条。
- 添加固定在地图表面的叠加层图片。
- 向地图添加自定义图块叠加层。
- 向地图添加标记。注意:Navigation SDK for Android 不支持 AdvancedMarkerOptions;使用 Navigation SDK for Android 时,请使用 GoogleMap.addMarker(MarkerOptions) 添加标记。
- 自定义地图上的标记。注意:Navigation SDK for Android 不支持 AdvancedMarkerOptions;使用 Navigation SDK for Android 时,请使用 MarkerOptions 自定义标记。
- 响应用户与地图上标记的互动。
- 确定坐标是否位于地图上的多边形或圆形区域内。注意:在 Android 上,请使用 Maps SDK for Android 实用工具库中的 PolyUtil.containsLocation 来处理多边形。对于圆形区域,请检查与圆心的球面距离是否在半径范围内(例如,Maps JavaScript API 中的 computeDistanceBetween、Android 上的 SphericalUtil.computeDistanceBetween 或 iOS 上的 GMSGeometryDistance)。
- 计算地图上坐标之间的球面距离、面积或方向角。
Maps SDK for Android:地图样式设置
- 创建可重复使用的跨平台地图样式。
- 更改地图上道路、多段线和多边形的样式。
- 显示或隐藏地图项。
- 更改地图上图标和文字标签的样式。
- 为不同的缩放级别应用不同的地图样式。
- 更改地图上地点的密度。实验性
- 更改地图上建筑物的样式。实验性
- 更改地图上位置标记的样式。实验性