在應用程式中加入 3D 地圖

選取平台： Android iOS JavaScript

本頁提供範例，逐步說明如何使用 Maps 3D SDK for iOS，在 iOS 應用程式中加入基本 3D 地圖。本頁的操作說明假設您已完成「設定」頁面中的步驟，並具備下列條件：

• 已啟用 Maps 3D SDK for iOS 的 Google Cloud 雲端專案
• Maps 3D SDK for iOS 的 API 金鑰
• Xcode 16.0 以上版本，並已新增 Maps 3D SDK for iOS 套件。

如要進一步瞭解這些必要條件，請參閱「設定」。

參加更進階的程式碼實驗室。

在 GitHub 查看更多程式碼範例。

第 1 部分：建立基本 SwiftUI 應用程式

1. 在 Xcode 中建立新的應用程式。
2. 將「Product Name」(產品名稱) 設為 Hello3DWorld，並將組織 ID 設為 com.example。套件名稱應為 com.example.Hello3DWorld。
3. 選擇 SwiftUI 介面。
4. 將 Maps 3D 程式庫新增至應用程式。請參閱設定一節的操作說明。

第 2 部分：新增地圖

1. 開啟名為 ContentView.swift 的檔案。這是應用程式的進入點和主要導覽。

2. 匯入 SwiftUI 和 GoogleMaps3D 套件。

3. 將主體宣告中的所有程式碼替換為 Map(mode: .hybrid)。

   如要初始化 Map，您至少需要提供 MapMode 做為初始設定：

   • .hybrid、
   • .roadmap，或
   • .satellite

   您的 ContentView.swift 檔案看起來會像這樣：

   import SwiftUI
   import GoogleMaps3D
   
   struct ContentView: View {
     var body: some View {
       Map(mode: .hybrid)
     }
   }
   
   #Preview {
     ContentView()
   }
   

第 3 部分：設定 API 金鑰。

1. API 金鑰必須在地圖初始化前設定。方法是在包含地圖的 View 的 init() 事件處理常式中設定 Map.apiKey。

   警告： 請勿將 API 金鑰簽入外部或公開原始碼控制系統

   import SwiftUI
   import GoogleMaps3D
   
   struct ContentView: View {
     init () {
       Map.apiKey = "YOUR_API_KEY"
     }
   
     var body: some View {
       Map(mode: .hybrid)
     }
   }
   

第 4 部分：使用攝影機控制地圖檢視畫面

3D 地圖檢視畫面是由 Camera 類別控制。在這個步驟中，您將瞭解如何指定位置、高度、方向、傾斜角度、滾動角度和範圍，藉此自訂地圖檢視畫面。

1. 變更 Map() 函式呼叫，加入 initialCamera 屬性。初始化 initialCamera，顯示曼哈頓市中心的檢視畫面。

   注意： 參數順序很重要。初始化攝影機時，請先提供緯度，再提供經度。請務必為每個欄位指定正確的值，尤其是從其他來源貼上時，否則攝影機可能會顯示非預期的位置。

   import SwiftUI
   import GoogleMaps3D
   
   struct ContentView: View {
     init () {
       Map.apiKey = "YOUR_API_KEY"
     }
     var body: some View {
       Map(initialCamera: .init(
         center: .init(latitude: 40.748339, longitude: -73.985912, altitude: 211.1),
         heading: 52,
         tilt: 68,
         roll: 0.0,
         range: 1039,
         fieldOfView: .degrees(50)
       ), mode: .hybrid)
     }
   }
   

上述程式碼會設定下列參數的值：

• center：代表攝影機位置的 LatLngAltitude
• heading：攝影機朝向的角度 (以度為單位，從正北算起)。
• tilt：傾斜角度 (以度為單位)，0 代表正上方，90 代表水平視角。
• roll：相機垂直平面的滾動角度，以度為單位。
• range：攝影機與經緯度位置的距離 (以公尺為單位)
• fieldOfView：代表相機視野的角度

如未提供任何額外參數，系統會使用預設值。

注意： 您也可以使用傾斜度和範圍調整攝影機的相對高度。

如要讓攝影機檢視畫面顯示更多 3D 資料，請設定初始參數，顯示更近的傾斜檢視畫面。

第 5 部分：預覽及執行應用程式

1. 新增 Xcode 預覽

   預覽是強大的 XCode 功能，可讓您查看應用程式並與其互動，不必使用模擬器或外部裝置。

   如要新增預覽畫面，請在 struct 外部新增 #Preview {} 程式碼區塊。

   #Preview {
     ContentView()
   }
   

2. 執行應用程式

建構並執行應用程式。

地圖載入和錯誤狀態

Maps 3D SDK for iOS 會自動顯示內建的視覺回饋，同時管理 Map 的狀態：

• 載入疊加層：地圖檢視畫面首次初始化或載入時，會顯示置中的進度指標。
• 錯誤疊加層：如果地圖無法載入，系統會顯示錯誤疊加層。

如果您在 Map 上使用 style(mapID:error:) 套用雲端式地圖樣式設定，可以傳遞 error 閉包來處理樣式載入錯誤。

監聽地圖輕觸事件

如要監聽地圖上的輕觸事件，請將 onTap(_:) 修飾符套用至 Map。使用者輕觸地圖時，閉包會收到 MapTapInfo 值，提供 location (LatLngAltitude) 和輕觸的 content (MapTapInfo.Content.map 或 MapTapInfo.Content.place(id:))。如要進一步瞭解搜尋點互動，請參閱「與搜尋點互動」。

Map(mode: .hybrid)
  .onTap { tapInfo in
    print("Tapped at \(tapInfo.location), content: \(tapInfo.content)")
  }

恭喜！

您已成功在應用程式中加入 3D 地圖！

接下來，您可以探索 Maps 3D SDK for iOS 的進階功能，例如攝影機路徑動畫、3D 標記或多邊形。