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, uygulama içinde 3D haritayı oluşturan görünümdür. Aşağıdaki adımlarda bileşen eklenir ve kamera konumu ile ilgili özellikler de dahil olmak üzere haritanın ilk durumu 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 genellikle app/src/main/res/layout/activity_main.xml konumunda bulunan düzen dosyasını açın.

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üzeninize 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ımlarda, 1. Bölüm'de activity_main.xml dosyasına eklenen Map3DView bileşeni ilk kullanıma hazırlanır ve bileşen yaşam döngüsü olayları yönetilir.

Android için Haritalar 3D SDK'sı, aynı anda yalnızca bir etkin Map3DView örneği destekler. Birden fazla Map3DView örneğinin aynı anda gösterilmesi (ör. aynı düzende veya farklı görünür etkinliklerde ya da parçalarda) desteklenmez ve ikincil görünümlerde siyah ekranlar gibi oluşturma sorunlarına yol açabilir.

Ayrıca tüm Map3DView, aynı harita durumunu (ör.kamera konumu, eklenen işaretçiler, çokgenler vb.) paylaşır ve yansıtır. Bu durum, bir Map3DView yok edilse (onDestroy kullanılarak) ve başka bir oluşturulsa bile manuel olarak temizlenmediği sürece 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. OnMap3DViewReadyCallback sınıfını uygulamak için MainActivity sınıfını 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 sınıfına ekleyerek Activity kitaplığınızdaki yaşam döngüsü olaylarını Map3DView sınıfına 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 bildirimleri 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 yer paylaşımı: 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.

OnMap3DViewReadyCallback uygulamanızda onError(error: Exception) yöntemini geçersiz kılarak bu başlatma veya yükleme hatalarını programatik olarak 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 location ve placeId değerlerini sağlayan bir Map3DClickEvent nesnesi alır ve bir Boolean döndürür (varsayılan Places kullanıcı arayüzü widget'ını gizlemek için true veya göstermek için false). Daha fazla bilgi için Önemli yerlerle etkileşim kurma başlıklı makaleyi inceleyin.

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

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

Not: Tıklama işleyicisi, 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.