Как добавить 3D-карту в приложение

Выберите платформу: Android iOS JavaScript

В этой статье на примере показано, как добавить базовую 3D-карту в приложение для iOS с помощью Maps 3D SDK для iOS. Инструкции на этой странице предполагают, что вы уже выполнили действия, описанные в разделе Настройка, и у вас есть:

• Проект Google Cloud с включенным Maps 3D SDK для iOS.
• ключ API для Maps 3D SDK для iOS;
• Xcode версии 16.0 или более поздней с добавленным пакетом Maps 3D SDK для iOS.

Подробнее о настройке…

Выполните более сложную практическую работу.

Другие примеры кода на 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. Замените весь код внутри объявления body на 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 необходимо задать до инициализации карты. Для этого задайте Map.apiKey в обработчике событий init() элемента View, содержащего карту.

   Внимание! Не добавляйте ключ 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 Preview

   Предварительный просмотр – это мощная функция XCode, которая позволяет просматривать приложение и взаимодействовать с ним без использования симулятора или внешнего устройства.

   Чтобы добавить предпросмотр, добавьте блок кода #Preview {} за пределами структуры.

   #Preview {
     ContentView()
   }
   

2. Запустите приложение.

Соберите и запустите приложение.

Состояния загрузки карты и ошибки

Maps 3D SDK для iOS автоматически показывает встроенные визуальные подсказки, управляя состоянием Map:

• Оверлей загрузки. При инициализации или загрузке карты в центре экрана показывается индикатор выполнения.
• Оверлей с ошибкой. Показывается, если не удалось загрузить карту.

Если вы применяете облачный стиль карты с помощью style(mapID:error:) в Map, то можете передать замыкание 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 для iOS, например анимацию траектории камеры, 3D-маркеры или многоугольники.