借助 Maps SDK for iOS,您可以将基于 Google 地图数据的地图添加到 iOS 应用。该 SDK 会处理对 Google 地图服务器的访问、地图显示以及对用户手势的响应,并允许您为地图添加标记、多段线、地面叠加层和信息窗口。
Maps SDK for iOS:关键信息
- 产品:Maps SDK for iOS
- 别名:Google Maps SDK for iOS
- 类别:Google 地图
- 平台:iOS
- 运行位置:客户端(应用或浏览器代码)
- 发布阶段:GA
- 生命周期:有效
- 概览:Maps SDK for iOS 概览
- 适用区域:全球。请参阅 Google Maps Platform 覆盖范围页面;用量和结算页面链接分别提供了全球和印度价格列表。(覆盖范围详情)
Maps SDK for iOS:何时使用
在以下情况下使用 Maps SDK for iOS:
- 您需要在原生 iOS 应用中添加一个支持手势处理的互动式 Google 地图。
- 您需要在 iOS 应用中向地图添加标记、多段线、地面叠加层或信息窗口。
- 您需要在 iOS 应用内显示街景全景图片。
- 您需要通过一款显示地图的 iOS 应用,将坐标反向地理编码为地址。
在以下情况下,请勿使用 Maps SDK for iOS:
- 您需要在 iOS 应用中使用 3D 摄影测量地图。请改用 Maps 3D SDK for iOS。
- 您只需在 Google 地图应用中打开某个地点或路线,而无需在应用中呈现地图。请改用 Maps URL。
Maps SDK for iOS:设置
- 要启用的服务:
maps-ios-backend.googleapis.com - 身份验证:API 密钥
- 使用情况归因:调用
GMSServices类方法addInternalUsageAttributionID:(Swift:GMSServices.addInternalUsageAttributionID(_:)),向初始化程序添加使用情况归因 ID。如要停用,请删除该调用或传递空字符串。 - 开始使用:设置 Maps SDK for iOS
- 参考文档:Maps SDK for iOS 参考文档
- 价格:Maps SDK for iOS 的用量和结算
- 政策:Maps SDK for iOS 政策
- 版本说明:Maps SDK for iOS 版本说明
官方 Maps SDK for iOS 软件包:
- swift_package:
https://github.com/googlemaps/ios-maps-sdk
Maps SDK for iOS:相关产品
- 通常与以下 API 搭配使用:Geocoding API、Places SDK for iOS
Maps SDK for iOS:常见错误
- 问题:SDK 不支持可合并库;在 Xcode 中启用“Build Mergeable Library”(构建可合并库)会导致发布 build 中出现链接器故障。解决方法:将“Build Mergeable Library”(构建可合并库)设置保持为“No”(否,默认值)。请参阅 /maps/documentation/ios-sdk/config。
- 问题:如果没有
LSApplicationQueriesSchemes条目,点按地图上的 Google 徽标会记录comgooglemaps://和googlechromes://的-canOpenURL失败。解决方法:在Info.plist中将googlechromes和comgooglemaps添加到LSApplicationQueriesSchemes。请参阅 /maps/documentation/ios-sdk/config。 - 问题:由于严格的内存限制,在 iOS 应用扩展程序(例如自定义键盘)中使用 SDK 可能会失败。解决方法:在主应用中使用 SDK,而不是在应用扩展程序中使用。请参阅 /maps/documentation/ios-sdk/overview。
- 问题:SDK 未针对 iPadOS 13 及更高版本的多窗口或同时运行的实例进行优化,可能会出现未定义的行为。解决方法:仔细测试 iPad 多窗口模式场景,或避免同时运行多个地图实例。请参阅 /maps/documentation/ios-sdk/overview。
Maps SDK for iOS:旧版和已弃用的功能
- OpenGL 渲染程序和
setMetalRendererEnabled:自 2025 年 5 月 19 日起已停用。替代方案:Metal 渲染程序(自 v8.0.0 起默认使用);移除setMetalRendererEnabled。症状:在 v9.0.0 (2024-05-28) 中已弃用,并在 v10.0.0 中移除;GMSServices不再列出setMetalRendererEnabled:。 GoogleMapsM4B模块:自 2025-05-19 起已停用。替代方案:移除GoogleMapsM4Bpod 或框架;它与已废弃的结算方案相关。症状:已于 2024 年 2 月 20 日弃用;已从 v9.0.0 的 Swift 软件包和 v10.0.0 的 SDK 中移除。- CocoaPods 分发:自 2026 年 8 月 6 日起弃用。替代方案:Swift Package Manager。症状:自 2025 年 8 月 18 日起进入维护模式;自 11.0.0 版起弃用。请参阅迁移指南。
- Carthage 安装:自 2022 年 6 月 27 日起已弃用。替代方案:Swift Package Manager。症状:Carthage 不支持面向 iOS 13 及更高版本的库;通过 Carthage 提供的最新版本为 6.2.1。请参阅迁移指南。
Maps SDK for iOS 的用途
请参阅下面链接的指南,了解每项任务,或在功能探索器中比较不同产品。
Maps SDK for iOS:边界的数据驱动型样式
Maps SDK for iOS:数据集的数据驱动型样式
Maps SDK for iOS:数据集
- 向地图添加 KML 图层。注意:在 Maps JavaScript API 中,KmlLayer 已弃用(最后支持的版本为 v3.65,将于 2027 年 5 月停用);请迁移到边界或数据集的数据驱动型样式,或在数据层上加载 GeoJSON。Android 和 iOS 仍通过 Maps SDK 实用程序库支持 KML 图层。
- 向地图添加 GeoJSON 数据。
- 向地图添加热图图层。
Maps SDK for iOS:地理编码
Maps SDK for iOS:地图
- 向网页或移动应用添加可自定义的互动式地图。注意:对于 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)。 - 创建可重复使用的地图标识符,用于存储地图配置和样式设置。
- 响应地图上的用户互动和事件。
- 自定义地图上显示的控件。
- 自定义用于控制地图的手势。
- 控制地图上的缩放和平移(镜头)。
- 更改地图类型。
- 更改地图配色方案。
- 向地图添加路况图层。
- 创建四叉树,以搜索指定区域内的点。
Maps SDK for iOS:地图注释
- 向地图添加信息窗口。
- 向地图添加形状或线条。
- 添加固定在地图表面的叠加层图片。
- 向地图添加自定义图块叠加层。
- 向地图添加标记。注意: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 iOS:地图样式设置
- 创建可重复使用的跨平台地图样式。
- 更改地图上道路、多段线和多边形的样式。
- 显示或隐藏地图项。
- 更改地图上图标和文字标签的样式。
- 为不同的缩放级别应用不同的地图样式。
- 更改地图上地点的密度。实验性
- 更改地图上建筑物的样式。实验性
- 更改地图上位置标记的样式。实验性
Maps SDK for iOS:街景
- 向网页或移动应用添加可配置的互动式 Google 街景。
- 向 Google 街景添加标记或叠加层。
- 在 Google 街景中响应用户互动和事件。
- 自定义 Google 街景中可用的手势。
- 为 Google 街景的镜头移动添加动画效果。