Maps SDK for iOS 可讓您在 iOS 應用程式中,加入以 Google 地圖資料為依據的地圖。這個 SDK 會處理對 Google 地圖伺服器的存取、地圖顯示作業,以及對使用者手勢的回應,並可讓您在地圖中加入標記、折線、區域疊加層和資訊視窗。
Maps SDK for iOS:重要資訊
- 產品:Maps SDK for iOS
- 別名:Google Maps SDK for iOS
- 類別:地圖
- 平台: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 網址。
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 Mergeable Library」設定維持為「No」(預設值)。請參閱 /maps/documentation/ios-sdk/config。
- 問題:如果沒有
LSApplicationQueriesSchemes項目,輕觸地圖上的 Google 標誌會記錄comgooglemaps://和googlechromes://的-canOpenURL失敗。修正方式:在Info.plist的LSApplicationQueriesSchemes中新增googlechromes和comgooglemaps。請參閱 /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 轉譯器 (8.0.0 版之後的預設轉譯器);請移除setMetalRendererEnabled。症狀:在 9.0.0 版 (2024-05-28) 淘汰,並在 10.0.0 版移除;GMSServices不再列出setMetalRendererEnabled:。 GoogleMapsM4B模組:自 2025 年 5 月 19 日起停用。替代方案:移除GoogleMapsM4BPod 或架構,因為這與過時的計費方案有關。症狀:已於 2024 年 2 月 20 日淘汰;已從 9.0.0 版的 Swift 套件和 10.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 (最後支援版本為 3.65,2027 年 5 月停用);請改用邊界或資料集的資料導向樣式,或在資料層載入 GeoJSON。Android 和 iOS 仍可透過 Maps SDK 公用程式庫支援 KML 圖層。
- 在地圖中加入 GeoJSON 資料。
- 在地圖中加入熱視圖圖層。
Maps SDK for iOS:地理編碼
Maps SDK for iOS:地圖
- 在網頁或行動應用程式中加入可自訂的互動式地圖。注意:Android:在
AndroidManifest.xml中設定(由 Secrets Gradle Plugin 支援),或在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)。 - 建立可重複使用的地圖 ID,用於儲存地圖設定和樣式設定。
- 回應地圖上的使用者互動和事件。
- 自訂地圖上顯示的控制項。
- 自訂控制地圖的手勢。
- 控制地圖 (攝影機) 的縮放和平移。
- 變更地圖類型。
- 變更地圖色彩配置。
- 在地圖中加入路況圖層。
- 建立四元樹,搜尋指定區域內的點。
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 街景服務的攝影機動作加入動畫效果。