Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Menambahkan peta 3D ke aplikasi

Pilih platform: Android iOS JavaScript

Peta 3D yang menampilkan New York City

Halaman ini membahas contoh cara menambahkan peta 3D dasar ke aplikasi Android menggunakan Maps 3D SDK for Android. Petunjuk di halaman ini mengasumsikan bahwa Anda telah menyelesaikan langkah-langkah di halaman Penyiapan dan memiliki hal berikut:

Project Google Cloud dengan Maps 3D SDK for Android diaktifkan
Kunci API yang dikonfigurasi untuk digunakan dengan Maps 3D SDK for Android
Project Android Studio yang disiapkan untuk digunakan dengan Maps 3D SDK for Android

Untuk mengetahui informasi selengkapnya tentang prasyarat ini, lihat Penyiapan.

Bagian 1: Memperbarui File Tata Letak (`activity_main.xml`) untuk menambahkan komponen `Map3DView`

Komponen Map3DView adalah tampilan yang merender peta 3D dalam aplikasi. Langkah-langkah berikut menambahkan komponen dan mengonfigurasi status awal peta, termasuk posisi kamera dan atribut terkait:

Buka file tata letak aktivitas utama Anda, yang biasanya terletak di app/src/main/res/layout/activity_main.xml.
Di ConstraintLayout root (atau elemen tata letak root), tambahkan namespace XML map3d:
```
xmlns:map3d="http://schemas.android.com/apk/res-auto"
```
Hapus <TextView> default yang menampilkan "Halo Dunia!".

Tambahkan komponen Map3DView ke tata letak Anda. Anda dapat menyesuaikan posisi kamera dan atribut lainnya:

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

Bagian 2: Memperbarui MainActivity.kt

Langkah-langkah berikut menginisialisasi komponen Map3DView yang ditambahkan ke file activity_main.xml di Bagian 1 dan mengelola peristiwa siklus proses komponen.

Perhatikan bahwa Maps 3D SDK for Android hanya mendukung satu instance Map3DView aktif dalam satu waktu. Menampilkan beberapa instance Map3DView secara bersamaan (misalnya, dalam tata letak yang sama atau Aktivitas atau Fragmen yang terlihat berbeda) tidak didukung dan dapat menyebabkan masalah rendering, seperti layar hitam pada tampilan sekunder.

Selain itu, semua Map3DView akan berbagi dan mencerminkan status peta yang sama (misalnya, posisi kamera, penanda yang ditambahkan, poligon, dll.), yang akan tetap ada meskipun satu Map3DView dihancurkan (menggunakan onDestroy) dan yang lain dibuat, kecuali jika dihapus secara manual. Misalnya, jika Anda menambahkan penanda ke Map3DView1, lalu menghancurkannya dan membuat Map3DView2, penanda yang sama tersebut akan tetap ada di Map3DView2.

Tanggung Jawab Developer:

Satu tampilan dalam satu waktu: Pastikan hanya satu Map3DView yang berada di bagian aktif hierarki tampilan Anda setiap saat.
Pembersihan manual: Saat beralih dari satu Map3DView (misalnya, Map3DView1) ke yang lain (misalnya, Map3DView2), Anda harus memanggil onDestroy() pada instance lama (Map3DView1). Karena status peta yang mendasarinya dibagikan, untuk memastikan Map3DView2 dimulai dengan status baru atau tertentu, Anda bertanggung jawab untuk menghapus secara manual status apa pun yang ditetapkan oleh Map3DView1. Hal ini mencakup menghapus penanda, overlay, dll., dan mereset posisi kamera menggunakan objek GoogleMap3D yang diperoleh di OnMap3DViewReadyCallback.

Buka file MainActivity.kt, yang biasanya terletak di app/src/main/java/com/example/yourpackagename/MainActivity.kt.

Tambahkan impor yang diperlukan untuk Maps 3D SDK for Android:

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

Ubah class MainActivity untuk menerapkan OnMap3DViewReadyCallback:

class MainActivity : AppCompatActivity(), OnMap3DViewReadyCallback {

Deklarasikan variabel untuk Map3DView dan GoogleMap3D:

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

Dalam metode onCreate, setelah setContentView(...) dan blok ViewCompat.setOnApplyWindowInsetsListener, lakukan inisialisasi map3DView, panggil metode siklus proses onCreate, dan minta peta secara asinkron:

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

Ganti metode onMap3DViewReady dan onError. Callback ini dipicu saat peta siap digunakan, atau saat terjadi error selama inisialisasi:

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

Teruskan peristiwa siklus proses dari Aktivitas Anda ke Map3DView dengan menambahkan penggantian berikut ke 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()
}

Bagian 3: Sinkronkan Gradle dan Jalankan

Setelah memperbarui tata letak dan aktivitas aplikasi, Anda dapat mem-build dan menjalankan aplikasi untuk melihat tampilan peta 3D.

Untuk menyinkronkan project dengan Gradle, pilih File > Sync Project with Gradle Files.
Untuk mem-build dan menjalankan aplikasi di emulator atau perangkat fisik, pilih Run > Run.

Jika semuanya dikonfigurasi dengan benar, Anda akan melihat peta 3D yang ditampilkan di aplikasi, yang berpusat di dekat koordinat yang ditentukan di activity_main.xml.

Status pemuatan dan error peta

Maps 3D SDK for Android secara otomatis menampilkan masukan visual bawaan saat mengelola status peta:

Overlay pemuatan: Indikator progres yang berpusat ditampilkan saat tampilan peta pertama kali diinisialisasi atau memuat area tampilan awal.
Overlay error: Kartu error yang diberi gaya ditampilkan jika terjadi kegagalan penting, seperti kunci API yang tidak valid, error jaringan, atau saat menjalankan di perangkat yang tidak didukung.

Anda dapat menangkap error inisialisasi atau pemuatan ini secara terprogram dengan mengganti onError(error: Exception) dalam implementasi OnMap3DViewReadyCallback.

Memproses peristiwa klik peta

Untuk memproses peristiwa klik pada peta, panggil setMap3DClickListener di GoogleMap3D. Saat pengguna mengklik peta, callback onMap3DClick menerima objek Map3DClickEvent yang memberikan location dan placeId titik yang diklik, serta menampilkan Boolean (true untuk menyembunyikan widget UI Tempat default, atau false untuk menampilkannya). Untuk mengetahui informasi selengkapnya, lihat Berinteraksi dengan tempat menarik.

Contoh berikut menunjukkan cara menetapkan pemroses klik peta:

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

Langkah berikutnya

Setelah menambahkan peta 3D dasar ke aplikasi, Anda dapat menjelajahi fitur Maps 3D SDK for Android yang lebih canggih, seperti animasi jalur kamera, penanda 3D, atau poligon.