Добавьте 3D-карту в свое приложение,Добавьте 3D-карту в свое приложение

Данный продукт или функция являются экспериментальными (предварительно выпущенными). Поддержка предварительно выпущенных продуктов и функций может быть ограничена, а изменения в них могут быть несовместимы с другими предварительно выпущенными версиями. На предварительно выпущенные продукты и функции распространяются Условия использования сервиса Google Maps Platform . Для получения дополнительной информации см. описания этапов запуска .

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

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

• Проект Google Cloud с поддержкой Maps 3D SDK для Android.
• Ключ API, настроенный для использования с Maps 3D SDK для Android.
• Проект Android Studio, созданный для использования с Maps 3D SDK для Android.

Для получения более подробной информации об этих предварительных условиях см. раздел «Настройка» .

Часть 1: Обновите файл макета ( activity_main.xml ), добавив компонент Map3DView

Компонент Map3DView — это представление, которое отображает 3D-карту в приложении. Следующие шаги включают добавление компонента и настройку начального состояния карты, включая положение камеры и связанные с ним атрибуты:

Примечание: Действия в этом разделе предполагают, что вы создали и настроили свой проект Android Studio, используя процесс, описанный в разделе «Настройка» , или что вы добавили новую активность View в существующий проект. Если вы создадите новый проект Android Studio, не добавив активность View, ваш проект не будет содержать файл activity_main.xml .

1. Откройте файл макета вашей основной активности, который обычно находится по адресу app/src/main/res/layout/activity_main.xml .

2. В корневой ConstraintLayout (или в корневом элементе макета) добавьте пространство имен XML map3d :

   xmlns:map3d="http://schemas.android.com/apk/res-auto"
   

3. Удалите элемент <TextView> по умолчанию, отображающий "Hello World!".

4. Добавьте компонент Map3DView в свой макет. Вы можете настроить положение камеры и другие атрибуты:

   <?xml version="1.0" encoding="utf-8"?>
   <androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
     xmlns:app="http://schemas.android.com/apk/res-auto"
     xmlns:map3d="http://schemas.android.com/apk/res-auto" xmlns:tools="http://schemas.android.com/tools"
     android:id="@+id/main"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
     tools:context=".MainActivity">
   
     <com.google.android.gms.maps3d.Map3DView
       android:id="@+id/map3dView"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       map3d:mode="hybrid"
       map3d:centerLat="38.544012"
       map3d:centerLng="-107.670428"
       map3d:centerAlt="2427.6"
       map3d:heading="310"
       map3d:tilt="63"
       map3d:range="8266"
       map3d:roll="0"
       map3d:minAltitude="0"
       map3d:maxAltitude="1000000"
       map3d:minHeading="0"
       map3d:maxHeading="360"
       map3d:minTilt="0"
       map3d:maxTilt="90"
       app:layout_constraintBottom_toBottomOf="parent"
       app:layout_constraintEnd_toEndOf="parent"
       app:layout_constraintStart_toStartOf="parent"
       app:layout_constraintTop_toTopOf="parent" />
   </androidx.constraintlayout.widget.ConstraintLayout>
   

Часть 2: Обновление файла MainActivity.kt

Следующие шаги инициализируют компонент Map3DView , добавленный в файл activity_main.xml в Части 1, и управляют событиями жизненного цикла компонента.

Обратите внимание, что Maps 3D SDK для Android поддерживает только один активный экземпляр Map3DView одновременно . Отображение нескольких экземпляров Map3DView одновременно (например, в одном макете или в разных видимых Activity или Fragment) не поддерживается и может привести к проблемам с рендерингом, таким как черные экраны на дополнительных представлениях.

Более того, все Map3DView будут использовать одно и то же состояние карты (например, положение камеры, добавленные маркеры, полигоны и т. д.), которое сохранится даже после уничтожения одного Map3DView (с помощью onDestroy ) и создания другого, если только оно не будет очищено вручную. Например, если вы добавите маркеры в Map3DView1 , затем уничтожите его и создадите Map3DView2 , эти же маркеры останутся на Map3DView2 .

Обязанности разработчика:

• Только одно представление за раз: убедитесь, что в любой момент времени в активной части иерархии представлений находится только одно Map3DView .
• Ручная очистка: При переключении с одного Map3DView (например, Map3DView1 ) на другой (например, Map3DView2 ) необходимо вызвать onDestroy() для старого экземпляра ( Map3DView1 ). Поскольку базовое состояние карты является общим, для обеспечения запуска Map3DView2 с новым или определенным состоянием необходимо вручную очистить любое состояние, установленное Map3DView1 . Это включает удаление маркеров, наложений и т. д., а также сброс положения камеры с помощью объекта GoogleMap3D полученного в методе OnMap3DViewReadyCallback .

1. Откройте файл MainActivity.kt , который обычно находится по адресу app/src/main/java/com/example/yourpackagename/MainActivity.kt .

2. Добавьте необходимые импорты для Maps 3D SDK для Android:

   import com.google.android.gms.maps3d.GoogleMap3D
   import com.google.android.gms.maps3d.Map3DView
   import com.google.android.gms.maps3d.OnMap3DViewReadyCallback
   

3. Измените класс MainActivity , добавив в него интерфейс OnMap3DViewReadyCallback :

   class MainActivity : AppCompatActivity(), OnMap3DViewReadyCallback {
   

4. Объявите переменные для Map3DView и GoogleMap3D :

   private lateinit var map3DView: Map3DView
   private var googleMap3D: GoogleMap3D? = null
   

5. В методе onCreate , после setContentView(...) и блока ViewCompat.setOnApplyWindowInsetsListener , инициализируйте map3DView , вызовите его метод жизненного цикла onCreate и запросите карту асинхронно:

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       enableEdgeToEdge()
       setContentView(R.layout.activity_main)
       ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.main)) { v, insets ->
           val systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
           v.setPadding(systemBars.left, systemBars.top, systemBars.right, systemBars.bottom)
           insets
       }
   
       map3DView = findViewById(R.id.map3dView)
       map3DView.onCreate(savedInstanceState)
       map3DView.getMap3DViewAsync(this)
   }
   

6. Переопределите метод onMap3DViewReady . Этот коллбэк срабатывает, когда карта готова к использованию:

   override fun onMap3DViewReady(googleMap3D: GoogleMap3D) {
       // Interact with the googleMap3D object here
       this.googleMap3D = googleMap3D
       // You can now make calls to the googleMap3D object, e.g.,
       // googleMap3D.cameraController.flyTo(camera { ... })
   }
   

7. Для пересылки событий жизненного цикла из вашей Activity в Map3DView добавьте следующие переопределения в MainActivity :

   override fun onStart() {
       super.onStart()
       map3DView.onStart()
   }
   
   override fun onResume() {
       super.onResume()
       map3DView.onResume()
   }
   
   override fun onPause() {
       map3DView.onPause()
       super.onPause()
   }
   
   override fun onStop() {
       map3DView.onStop()
       super.onStop()
   }
   
   override fun onDestroy() {
       map3DView.onDestroy()
       super.onDestroy()
   }
   
   override fun onSaveInstanceState(outState: Bundle) {
       super.onSaveInstanceState(outState)
       map3DView.onSaveInstanceState(outState)
   }
   
   override fun onLowMemory() {
       super.onLowMemory()
       map3DView.onLowMemory()
   }
   

Часть 3: Синхронизация Gradle и запуск

Теперь, когда вы обновили макет и активность своего приложения, вы можете собрать и запустить приложение, чтобы увидеть трехмерную карту.

1. Чтобы синхронизировать проект с Gradle, выберите Файл > Синхронизировать проект с файлами Gradle.

2. Чтобы собрать и запустить приложение на эмуляторе или физическом устройстве, выберите «Запуск» > «Запуск» .

Если все настроено правильно, в вашем приложении должна отобразиться трехмерная карта, центрированная вблизи координат, указанных в файле activity_main.xml .

Следующие шаги

Теперь, когда вы добавили в свое приложение базовую 3D-карту, вы можете изучить более продвинутые функции SDK Maps 3D для Android, такие как анимация траектории камеры , 3D-маркеры или полигоны .

Отслеживайте события кликов по карте.

Для отслеживания событий клика по карте используйте GoogleMap3D.setMap3DClickListener . Этот обработчик срабатывает, когда пользователь щелкает по карте, и предоставляет местоположение и ID точки, по которой был произведен клик.

В следующем примере показано, как настроить обработчик кликов по карте:

googleMap3D.setMap3DClickListener { location, placeId ->
    lifecycleScope.launch(Dispatchers.Main) {
        if (placeId != null) {
            Toast.makeText(this@MainActivity, "Clicked on place with ID: $placeId", Toast.LENGTH_SHORT).show()
        } else {
            Toast.makeText(this@MainActivity, "Clicked on location: $location", Toast.LENGTH_SHORT).show()
        }
    }
}

Обратите внимание, что обработчик кликов не выполняется в основном потоке (или потоке пользовательского интерфейса). Если вы хотите внести изменения в пользовательский интерфейс (например, отобразить всплывающее сообщение), вам необходимо переключиться в основной поток. В Kotlin это можно сделать с помощью lifecycleScope.launch(Dispatchers.Main) .