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

選取平台： Android iOS JavaScript

這項產品或功能仍在實驗階段 (正式發布前)。我們對於正式發布前的產品和功能僅提供有限度的支援。此外，這類產品和功能的變更可能與其他正式發布前版本不相容。正式發布前產品/功能受到《Google 地圖平台服務專屬條款》規範。詳情請參閱推出階段說明。

本頁將逐步說明如何使用 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 或
   • .satellite

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

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

第 3 部分：設定 API 金鑰。

1. 您必須先設定 API 金鑰，才能初始化地圖。方法是在包含 Map 的 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，顯示曼哈頓市中心的檢視畫面。

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

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

上述程式碼會為這些參數設定值：

• heading：攝影機的航向 (以度為單位，從正北算起)。
• tilt：傾斜角度 (以度為單位)，0 代表正上方，90 代表水平。
• roll：攝影機垂直平面周圍的側傾角度 (以度為單位)。
• range：相機與緯度/經度位置的距離 (以公尺為單位)
• altitude：相機高於海平面的高度。

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

注意： 相機海拔高度是絕對值。如果地面高度遠高於海平面，將高度設為低於地面高度可能會導致奇怪的視覺效果。

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

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

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

1. 新增 Xcode 預覽畫面

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

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

   #Preview {
     CameraDemo()
   }
   

2. 執行應用程式

建構並執行應用程式。

恭喜！

您已成功在應用程式中新增 3D 地圖！

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