向应用添加 3D 地图

请选择平台： Android iOS JavaScript

本页介绍了一个示例，展示了如何使用 Maps 3D SDK for iOS 将基本 3D 地图添加到 iOS 应用。本页中的说明假定您已 完成 设置页面中的步骤，并且具备以下条件：

• 已启用 Maps 3D SDK for iOS 的 Google Cloud 项目
• Maps 3D SDK for iOS 的 API 密钥
• 已添加 Maps 3D SDK for iOS 软件包的 Xcode 16.0 版 或更高版本。

如需详细了解这些前提条件，请参阅 设置。

浏览更高级的 Codelab。

在 GitHub上查看更多代码示例。

第 1 部分：创建基本的 SwiftUI 应用

1. 在 Xcode 中创建新应用。
2. 将产品名称 设置为 Hello3DWorld，并将组织标识符设置为 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 功能，可让您查看应用并与之互动，而无需使用模拟器或外部设备。

   如需添加预览，请在结构体外部添加 #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 标记或 多边形。