เพิ่มแผนที่ 3 มิติลงในแอป

หน้านี้จะแสดงตัวอย่างวิธีเพิ่มแผนที่ 3 มิติพื้นฐานลงใน แอป 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 คือมุมมองที่แสดงแผนที่ 3 มิติภายในแอป ขั้นตอนต่อไปนี้จะเพิ่มคอมโพเนนต์และกำหนดค่าสถานะเริ่มต้นของ แผนที่ รวมถึงตำแหน่งกล้องและแอตทริบิวต์ที่เกี่ยวข้อง

1. เปิดไฟล์เลย์เอาต์ของกิจกรรมหลัก ซึ่งโดยปกติจะอยู่ที่ app/src/main/res/layout/activity_main.xml

2. ในรูท ConstraintLayout (หรือองค์ประกอบเลย์เอาต์รูท) ให้เพิ่มเนมสเปซ map3d XML ดังนี้

   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 เพียงครั้งละ 1 รายการเท่านั้น การแสดงMap3DViewอินสแตนซ์หลายรายการพร้อมกัน (เช่น ในเลย์เอาต์เดียวกันหรือในกิจกรรมหรือ Fragment ที่มองเห็นได้ต่างกัน) ไม่ รองรับและอาจทำให้เกิดปัญหาในการแสดงผล เช่น หน้าจอสีดำในมุมมองรอง

นอกจากนี้ Map3DView ทั้งหมดจะแชร์และแสดงสถานะแผนที่เดียวกัน (เช่น ตำแหน่งกล้อง เครื่องหมายที่เพิ่ม รูปหลายเหลี่ยม ฯลฯ) ซึ่งจะยังคงอยู่แม้ว่า Map3DView รายการใดรายการหนึ่งจะถูกทำลาย (โดยใช้ onDestroy) และมีการสร้างรายการอื่นขึ้นมา เว้นแต่จะล้างด้วยตนเอง เช่น หากคุณเพิ่มเครื่องหมายใน Map3DView1 แล้วทำลาย และสร้าง Map3DView2 เครื่องหมายเดียวกันนั้นจะยังคงอยู่ใน Map3DView2

ความรับผิดชอบของนักพัฒนาแอป:

• ดูครั้งละ 1 รายการ: ตรวจสอบว่ามี 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 ระบบจะทริกเกอร์ Callback นี้เมื่อแผนที่พร้อมใช้งาน

   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. ส่งต่อเหตุการณ์วงจรจากกิจกรรมไปยัง 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 และเรียกใช้

ตอนนี้คุณได้อัปเดตเลย์เอาต์และกิจกรรมของแอปแล้ว คุณสามารถสร้างและ เรียกใช้แอปเพื่อดูมุมมองแผนที่ 3 มิติได้

1. หากต้องการซิงค์โปรเจ็กต์กับ Gradle ให้เลือก ไฟล์ > ซิงค์โปรเจ็กต์กับไฟล์ Gradle

2. หากต้องการสร้างและเรียกใช้แอปในโปรแกรมจำลองหรืออุปกรณ์จริง ให้เลือก เรียกใช้ > เรียกใช้

หากกำหนดค่าทุกอย่างถูกต้อง คุณควรเห็นแผนที่ 3 มิติแสดงในแอป โดยมีจุดกึ่งกลางอยู่ใกล้กับพิกัดที่ระบุใน activity_main.xml

ขั้นตอนถัดไป

ตอนนี้คุณได้เพิ่มแผนที่ 3 มิติพื้นฐานลงในแอปแล้ว คุณสามารถสำรวจฟีเจอร์ขั้นสูงเพิ่มเติมของ Maps 3D SDK สำหรับ Android เช่น ภาพเคลื่อนไหวเส้นทางกล้อง เครื่องหมาย 3 มิติ หรือ รูปหลายเหลี่ยม

ฟังกิจกรรมการคลิกแผนที่

หากต้องการฟังเหตุการณ์การคลิกบนแผนที่ ให้ใช้ GoogleMap3D.setMap3DClickListener ระบบจะเรียกใช้ Listener นี้เมื่อผู้ใช้ คลิกบนแผนที่ และจะระบุตำแหน่งและรหัสสถานที่ของจุดที่คลิก

ตัวอย่างต่อไปนี้แสดงวิธีตั้งค่าฟังก์ชันรอคลิกแผนที่

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

โปรดทราบว่าตัวแฮนเดิลการคลิกไม่ได้ทำงานในเธรดหลัก (หรือ UI) หากต้องการทำการเปลี่ยนแปลง UI (เช่น แสดงข้อความ Toast) คุณต้องเปลี่ยนไปใช้เทรดหลัก สำหรับ Kotlin คุณสามารถทำได้โดยใช้ lifecycleScope.launch(Dispatchers.Main)