הוספת מפה תלת-ממדית לאפליקציה

בדף הזה מוסבר איך להוסיף מפה תלת-ממדית בסיסית לאפליקציית 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 הוא התצוגה שבה המפה בתלת-ממד מוצגת באפליקציה. בשלבים הבאים מוסיפים את הרכיב ומגדירים את המצב הראשוני של המפה, כולל מיקום המצלמה ומאפיינים קשורים:

1. פותחים את קובץ הפריסה של הפעילות הראשית, שבדרך כלל נמצא בנתיב app/src/main/res/layout/activity_main.xml.

2. ב-root ConstraintLayout (או ברכיב פריסת ה-root), מוסיפים את מרחב השמות של ה-XML:‏ map3d

   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 ומנהלים את אירועי מחזור החיים של הרכיב:

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. הקריאה החוזרת הזו מופעלת כשהמפה מוכנה לשימוש:

   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 והרצה

אחרי שמעדכנים את הפריסה והפעילות של האפליקציה, אפשר ליצור ולהפעיל את האפליקציה כדי לראות את תצוגת המפה בתלת-ממד.

1. כדי לסנכרן את הפרויקט עם Gradle, בוחרים באפשרות File > Sync Project with Gradle Files (קובץ > סנכרון הפרויקט עם קובצי Gradle).

2. כדי ליצור ולהפעיל את האפליקציה באמולטור או במכשיר פיזי, בוחרים באפשרות Run > Run (הפעלה > הפעלה).

אם הכול מוגדר בצורה נכונה, אמורה להופיע באפליקציה מפה תלת-ממדית, עם מרכז שקרוב לקואורדינטות שצוינו ב-activity_main.xml.

השלבים הבאים

אחרי שמוסיפים לאפליקציה מפה תלת-ממדית בסיסית, אפשר לנסות תכונות מתקדמות יותר של Maps 3D SDK ל-Android, כמו אנימציות של נתיבי מצלמה, סמנים תלת-ממדיים או מצולעים.