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

選取平台： Android iOS JavaScript

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

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

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

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

參加更進階的程式碼研究室。

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

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

1. 在 Xcode 中建立新應用程式。
2. 將「產品名稱」設為 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 金鑰。方法是在包含地圖的 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(
         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 標記或多邊形。