Uygulamanıza 3D harita ekleme

Platform seçin: Android iOS JavaScript

Bu sayfada, Android için Haritalar 3D SDK'sını kullanarak Android uygulamasına temel bir 3D harita ekleme örneği açıklanmaktadır. Bu sayfadaki talimatlar, Kurulum sayfasındaki adımları tamamladığınızı ve aşağıdakilere sahip olduğunuzu varsayar:

• Android için Haritalar 3D SDK'sının etkin olduğu bir Google Cloud projesi
• Android için Haritalar 3D SDK'sı ile kullanılacak şekilde yapılandırılmış bir API anahtarı
• Android için Haritalar 3D SDK'sı ile kullanılmak üzere ayarlanmış bir Android Studio projesi

Bu ön koşullar hakkında daha fazla bilgi için Kurulum bölümüne bakın.

1. Bölüm: Map3DView bileşenini eklemek için düzen dosyasını (activity_main.xml) güncelleme

Map3DView bileşeni, uygulamada 3D haritayı oluşturmak için kullanılan görünümüdür. Aşağıdaki adımlarda bileşen eklenir ve haritanın ilk durumu (kamera konumu ve ilgili özellikler dahil) yapılandırılır:

Not: Bu bölümdeki adımlarda, Android Studio projenizi Kurulum bölümünde açıklanan süreci kullanarak oluşturup yapılandırdığınız veya mevcut bir projeye yeni bir görünüm etkinliği eklediğiniz varsayılmaktadır. Görünüm etkinliği eklemeden yeni bir Android Studio projesi oluşturursanız projenizde activity_main.xml dosyası bulunmaz.

1. Ana etkinliğinizin düzen dosyasını açın. Bu dosya genellikle app/src/main/res/layout/activity_main.xml konumunda bulunur.

2. Kök ConstraintLayout (veya kök düzen öğeniz) içine map3d XML ad alanını ekleyin:

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

3. "Hello World!" ifadesini gösteren varsayılan <TextView> öğesini silin.

4. Düzene Map3DView bileşenini ekleyin. Kamera konumunu ve diğer özellikleri özelleştirebilirsiniz:

   <?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:mapMode="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. bölüm: MainActivity.kt dosyasını güncelleme

Aşağıdaki adımlar, Bölüm 1'de activity_main.xml dosyasına eklenen Map3DView bileşenini başlatır ve bileşen yaşam döngüsü etkinliklerini yönetir.

Android için Haritalar 3D SDK'sının aynı anda yalnızca bir etkin Map3DView örneği desteklediğini unutmayın. Aynı anda birden fazla Map3DView örneğinin gösterilmesi (ör. aynı düzende veya farklı görünür Etkinlikler ya da Parçalar) desteklenmez ve ikincil görünümlerde siyah ekran gibi oluşturma sorunlarına yol açabilir.

Ayrıca, tüm Map3DView aynı harita durumunu (ör.kamera konumu, eklenen işaretçiler, poligonlar vb.) paylaşır ve yansıtır. Bu durum, manuel olarak temizlenmediği sürece bir Map3DView yok edilse (onDestroy kullanılarak) ve başka bir oluşturulsa bile devam eder. Örneğin, Map3DView1 öğesine işaretçiler ekleyip ardından bu öğeyi siler ve Map3DView2 öğesini oluşturursanız aynı işaretçiler Map3DView2 öğesinde de bulunur.

Geliştirici Sorumlulukları:

• Aynı anda tek bir görünüm: Herhangi bir anda görünüm hiyerarşinizin etkin bir bölümünde yalnızca bir Map3DView olduğundan emin olun.
• Manuel temizleme: Bir Map3DView (ör. Map3DView1) örneğinden diğerine (ör. Map3DView2) geçerken eski örnekte (Map3DView1) onDestroy() yöntemini çağırmanız gerekir. Temel harita durumu paylaşıldığından, Map3DView2 örneğinin yeni veya belirli bir durumla başlamasını sağlamak için Map3DView1 tarafından ayarlanan tüm durumları manuel olarak temizlemeniz gerekir. Buna işaretçilerin, yer paylaşımlarının vb. kaldırılması ve OnMap3DViewReadyCallback içinde elde edilen GoogleMap3D nesnesi kullanılarak kamera konumunun sıfırlanması dahildir.

1. Genellikle app/src/main/java/com/example/yourpackagename/MainActivity.kt konumunda bulunan MainActivity.kt dosyanızı açın.

2. Android için Haritalar 3D SDK'sı için gerekli içe aktarma işlemlerini ekleyin:

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

3. MainActivity sınıfını OnMap3DViewReadyCallback'ı uygulayacak şekilde değiştirin:

   class MainActivity : AppCompatActivity(), OnMap3DViewReadyCallback {
   

4. Map3DView ve GoogleMap3D için değişkenleri tanımlayın:

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

5. onCreate yönteminde, setContentView(...) ve ViewCompat.setOnApplyWindowInsetsListener bloğundan sonra map3DView öğesini ilk kullanıma hazırlayın, onCreate yaşam döngüsü yöntemini çağırın ve haritayı eşzamansız olarak isteyin:

   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 ve onError yöntemlerini geçersiz kılın. Bu geri çağırmalar, harita kullanıma hazır olduğunda veya başlatma sırasında bir hata oluştuğunda tetiklenir:

   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.flyTo(camera { ... })
   }
   
   override fun onError(error: Exception) {
       // Handle the error gracefully here (for example, show an error dialog or log the error).
       Log.e("MainActivity", "Error loading 3D map", error)
   }
   

7. Aşağıdaki geçersiz kılmaları MainActivity'ye ekleyerek etkinlik yaşam döngüsü etkinliklerini Etkinliğinizden Map3DView'ya yönlendirin:

   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. bölüm: Gradle'ı senkronize etme ve çalıştırma

Uygulamanızın düzenini ve etkinliğini güncellediğinize göre artık uygulamayı derleyip çalıştırarak 3D harita görünümünü görebilirsiniz.

1. Projenizi Gradle ile senkronize etmek için File > Sync Project with Gradle Files'ı (Dosya > Projeyi Gradle Dosyalarıyla Senkronize Et) seçin.

2. Uygulamanızı bir emülatörde veya fiziksel cihazda derleyip çalıştırmak için Run > Run'ı (Çalıştır > Çalıştır) seçin.

Her şey doğru şekilde yapılandırıldıysa uygulamanızda, activity_main.xml dosyanızda belirtilen koordinatların yakınında ortalanmış bir 3D harita görürsünüz.

Harita yükleme ve hata durumları

Android için Haritalar 3D SDK'sı, haritanın durumunu yönetirken yerleşik görsel geri bildirimi otomatik olarak gösterir:

• Yükleme yer paylaşımı: Harita görünümü ilk kez başlatıldığında veya ilk görüntü alanını yüklerken ortalanmış bir ilerleme göstergesi görüntülenir.
• Hata yerleşimi: Geçersiz API anahtarı, ağ hatası veya desteklenmeyen bir cihazda çalıştırma gibi kritik bir hata oluşursa stilize edilmiş bir hata kartı gösterilir.

onError(error: Exception)'ı OnMap3DViewReadyCallback uygulamanızda geçersiz kılarak bu başlatma veya yükleme hatalarını programlı bir şekilde yakalayabilirsiniz.

Harita tıklama etkinliklerini dinleme

Haritadaki tıklama etkinliklerini dinlemek için GoogleMap3D üzerinde setMap3DClickListener yöntemini çağırın. Kullanıcı haritayı tıkladığında onMap3DClick geri çağırma işlevi, tıklanan noktanın Map3DClickEvent nesnesini alır ve location ile placeId değerlerini sağlar. Ayrıca, Boolean (varsayılan Places kullanıcı arayüzü widget'ını gizlemek için true veya göstermek için false) döndürür. Daha fazla bilgi için İlgi çekici yerlerle etkileşim kurma başlıklı makaleyi inceleyin.

Aşağıdaki örnekte, harita tıklama işleyicisinin nasıl ayarlanacağı gösterilmektedir:

googleMap3D.setMap3DClickListener { event: Map3DClickEvent ->
    Log.d(
        "MainActivity",
        "Clicked at ${event.location}, placeId: ${event.placeId}"
    )
    false
}

Not: Tıklama dinleyicisi, ana kullanıcı arayüzü iş parçacığında çalışmaz. Kullanıcı arayüzü öğelerini güncellemeden önce ana iş parçacığına geçin.

Sonraki adımlar

Uygulamanıza temel bir 3D harita eklediğinize göre Android için Maps 3D SDK'nın kamera yolu animasyonları, 3D işaretçiler veya poligonlar gibi daha gelişmiş özelliklerini keşfedebilirsiniz.