Dodawanie mapy 3D do aplikacji

Wybierz platformę: Android iOS JavaScript

Mapa 3D przedstawiająca Nowy Jork

Na tej stronie znajdziesz przykład dodawania podstawowej mapy 3D do aplikacji na Androida za pomocą pakietu Maps 3D SDK na Androida. Instrukcje na tej stronie zakładają, że masz już za sobą kroki opisane na stronie Konfiguracja i masz następujące:

projekt Google Cloud z włączonym pakietem Maps 3D SDK na Androida,
klucz interfejsu API skonfigurowany do użycia z pakietem Maps 3D SDK na Androida,
projekt Android Studio skonfigurowany do użycia z pakietem Maps 3D SDK na Androida.

Więcej informacji o tych wymaganiach wstępnych znajdziesz w sekcji Konfiguracja.

Część 1. Aktualizowanie pliku układu (`activity_main.xml`) w celu dodania komponentu `Map3DView`

Komponent Map3DView to widok, który renderuje mapę 3D w aplikacji. Poniższe kroki dodają komponent i konfigurują stan początkowy mapy, w tym położenie kamery i powiązane atrybuty:

Otwórz plik układu głównego działania, który zwykle znajduje się w app/src/main/res/layout/activity_main.xml.
W głównym elemencie ConstraintLayout (lub głównym elemencie układu) dodaj przestrzeń nazw XML map3d:
```
xmlns:map3d="http://schemas.android.com/apk/res-auto"
```
Usuń domyślny element <TextView>, który wyświetla „Hello World!”.

Dodaj do układu komponent Map3DView. Możesz dostosować położenie kamery i inne atrybuty:

<?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>

Część 2. Aktualizowanie pliku MainActivity.kt

Poniższe kroki inicjują komponent Map3DView dodany do pliku activity_main.xml w części 1 i zarządzają zdarzeniami cyklu życia komponentu.

Pamiętaj, że pakiet Maps 3D SDK na Androida obsługuje tylko jedną aktywną Map3DView instancję naraz. Wyświetlanie wielu instancji Map3DView jednocześnie (np. w tym samym układzie lub w różnych widocznych działaniach lub fragmentach) nie jest obsługiwane i może powodować problemy z renderowaniem, takie jak czarne ekrany w widokach dodatkowych.

Ponadto wszystkie elementy Map3DView będą współdzielić i odzwierciedlać ten sam stan mapy (np. położenie kamery, dodane znaczniki, wielokąty itp.), który będzie się utrzymywać nawet wtedy, gdy jeden element Map3DView zostanie zniszczony (za pomocą onDestroy) i utworzony zostanie inny, chyba że zostanie ręcznie wyczyszczony. Jeśli na przykład dodasz znaczniki do Map3DView1, a następnie zniszczysz go i utworzysz Map3DView2, te same znaczniki będą nadal obecne w Map3DView2.

Obowiązki dewelopera:

Jeden widok naraz: upewnij się, że w danym momencie tylko jeden element Map3DView znajduje się w aktywnej części hierarchii widoków.
Ręczne czyszczenie: gdy przełączasz się z jednego elementu Map3DView (np. Map3DView1) na inny (np. Map3DView2), musisz wywołać onDestroy() w starej instancji (Map3DView1). Ponieważ stan mapy jest współdzielony, aby mieć pewność, że Map3DView2 zaczyna się od nowego lub określonego stanu, musisz ręcznie wyczyścić każdy stan ustawiony przez Map3DView1. Obejmuje to usuwanie znaczników, nakładek itp. oraz resetowanie położenia kamery za pomocą obiektu GoogleMap3D uzyskanego w OnMap3DViewReadyCallback.

Otwórz plik MainActivity.kt, który zwykle znajduje się w app/src/main/java/com/example/yourpackagename/MainActivity.kt.

Dodaj niezbędne importy dla pakietu Maps 3D SDK na Androida:

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

Zmodyfikuj klasę MainActivity, aby zaimplementować OnMap3DViewReadyCallback:
```
class MainActivity : AppCompatActivity(), OnMap3DViewReadyCallback {
```

Zadeklaruj zmienne dla Map3DView i GoogleMap3D:

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

W metodzie onCreate po setContentView(...) i bloku ViewCompat.setOnApplyWindowInsetsListener zainicjuj map3DView, wywołaj jego metodę cyklu życia onCreate i asynchronicznie poproś o mapę:

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)
}

Zastąp metodę onMap3DViewReady. To wywołanie zwrotne jest aktywowane, gdy mapa jest gotowa do użycia:

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 { ... })
}

Przekaż zdarzenia cyklu życia z działania do Map3DView, dodając te zastąpienia do 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()
}

Część 3. Synchronizowanie Gradle i uruchamianie

Teraz, gdy zaktualizujesz układ i działanie aplikacji, możesz ją skompilować i uruchomić, aby zobaczyć widok mapy 3D.

Aby zsynchronizować projekt z Gradle, wybierz Plik > Synchronizuj projekt z plikami Gradle.
Aby skompilować i uruchomić aplikację w emulatorze lub na urządzeniu fizycznym, wybierz Uruchom > Uruchom.

Jeśli wszystko jest prawidłowo skonfigurowane, w aplikacji powinna się wyświetlać mapa 3D wyśrodkowana w pobliżu współrzędnych określonych w pliku activity_main.xml.

Dalsze kroki

Teraz, gdy dodasz do aplikacji podstawową mapę 3D, możesz poznać bardziej funkcje zaawansowane pakietu Maps 3D SDK na Androida, takie jak animacje ścieżki kamery, znaczniki 3D czy wielokąty.

Nasłuchiwanie zdarzeń kliknięcia mapy

Aby nasłuchiwać zdarzeń kliknięcia na mapie, użyj GoogleMap3D.setMap3DClickListener. Ten odbiornik jest aktywowany, gdy użytkownik kliknie mapę, i podaje lokalizację oraz identyfikator miejsca klikniętego punktu.

Poniższy przykład pokazuje, jak ustawić detektor kliknięć mapy:

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()
        }
    }
}

Pamiętaj, że moduł obsługi kliknięć nie jest uruchamiany w wątku głównym (ani w wątku interfejsu użytkownika). Jeśli chcesz wprowadzić zmiany w interfejsie użytkownika (np. wyświetlić komunikat Toast), musisz przełączyć się na wątek główny. W Kotlinie możesz to zrobić za pomocą lifecycleScope.launch(Dispatchers.Main).